> For the complete documentation index, see [llms.txt](https://docs.apismart.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apismart.ai/api-guides/response-modes.md).

# Response Modes

Streaming allows your application to receive generated text in small chunks while the model is producing the response, instead of waiting for the complete result.

This is useful for chat interfaces, assistants, and other applications that display text in real time.

Streaming applies to supported models using the [**Chat Completions API**](/api-guides/chat-completions-api.md). Video generation uses a separate asynchronous task workflow.

***

### Enable Streaming

To request a streaming response, add:

```json
{
  "stream": true
}
```

Example request body:

```json
{
  "model": "YOUR_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "Explain ApiSmart in one sentence."
    }
  ],
  "stream": true
}
```

> ⚠️ **Important:** Streaming support varies by model. Confirm that the selected model supports `stream: true` in its **Code Example**.

***

### Send a Streaming Request

Example with cURL:

```bash
curl https://gw.apismart.ai/v1/chat/completions \
  -H "Authorization: Bearer $APISMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "Explain ApiSmart in one sentence."
      }
    ],
    "stream": true
  }'
```

Replace `YOUR_MODEL_ID` with the exact Model ID shown on the selected model’s details page.

***

### Python Example

The following example reads the response incrementally:

```python
import os
import requests

api_key = os.getenv("APISMART_API_KEY")

if not api_key:
    raise RuntimeError("APISMART_API_KEY is not set.")

with requests.post(
    "https://gw.apismart.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "model": "YOUR_MODEL_ID",
        "messages": [
            {
                "role": "user",
                "content": "Explain ApiSmart in one sentence.",
            }
        ],
        "stream": True,
    },
    stream=True,
    timeout=120,
) as response:
    response.raise_for_status()

    for line in response.iter_lines(decode_unicode=True):
        if line:
            print(line)
```

The exact chunk structure may vary by model. Parse the returned stream according to the selected model’s supported response format.

***

### Streaming vs. Non-Streaming

| Mode          | Behaviour                                           |
| ------------- | --------------------------------------------------- |
| Non-streaming | Waits for the complete response before returning it |
| Streaming     | Returns generated content incrementally             |

Use streaming when you want users to see generated text as it becomes available.

For background processing or workflows that only need the final result, a standard non-streaming request may be simpler.

***

### Important Notes

When using streaming:

* Keep the connection open until the stream finishes.
* Process chunks as they arrive.
* Do not assume every model returns identical streaming fields.
* Handle connection interruptions and API errors in your application.
* Use only parameters supported by the selected model.

Streaming does not change the Model ID or authentication method.

***

### 🛠️ Common Problems

| Problem                     | What to Check                                         |
| --------------------------- | ----------------------------------------------------- |
| **No streaming output**     | Confirm that the model supports `stream: true`        |
| **Authentication failed**   | API Token status and Bearer header                    |
| **Model not found**         | Exact Model ID and capitalization                     |
| **Connection closes early** | Client timeout or network interruption                |
| **Chunks cannot be parsed** | Actual response format returned by the selected model |

When troubleshooting, review the related request in [**Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md) and save the **Request ID** when available.

> 🔐 Never provide your full API Token to support.

***

### 🚀 Next Steps

Continue with:

* [**Chat Completions API**](/api-guides/chat-completions-api.md)
* [**Choose a Model and Find Its Model ID**](/models-and-pricing/models-and-model-ids.md)
* [**API Basics**](/api-guides/api-basics.md)
* [**Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md)