> 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

Understand how ApiSmart APIs return results, including standard responses, streaming output, synchronous image generation, and asynchronous video tasks.

ApiSmart APIs use different response modes depending on the type of workload.

Text requests can return a complete response or stream generated content progressively. Image generation is synchronous by default and can also support streaming. Video generation uses asynchronous tasks because generation can take longer to complete.

Understanding these response modes helps you choose the right request-handling strategy for your application.

### 🔄 Response Modes at a Glance

| API                  | Default Mode         | Alternative Mode |
| -------------------- | -------------------- | ---------------- |
| **Chat Completions** | Standard response    | Streaming        |
| **Image Generation** | Synchronous response | SSE streaming    |
| **Video Generation** | Asynchronous task    | —                |

The implementation differs by API, so always follow the behavior documented for the endpoint you are using.

### 📄 Standard Responses

A standard response waits until the model finishes processing the request and then returns the completed result.

This is the default behavior for Chat Completions when streaming is not enabled.

Example:

```bash
curl https://gw.apismart.ai/v1/chat/completions \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "user",
        "content": "Explain API gateways in simple terms."
      }
    ]
  }'
```

Standard responses are useful when:

* You want to receive the complete result at once
* The response is relatively short
* Your application does not need progressive output
* Simpler request handling is preferred

For request parameters and examples, see [**Chat Completions API**](/api-guides/chat-completions-api.md).

### 🌊 Streaming Text Responses

Chat Completions can return generated content progressively instead of waiting for the complete response.

Enable streaming by setting:

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

Example:

```bash
curl https://gw.apismart.ai/v1/chat/completions \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "user",
        "content": "Write a short story."
      }
    ],
    "stream": true
  }'
```

Streaming can be useful for:

* Conversational applications
* Longer text generations
* Interfaces that display output as it is generated
* Applications where receiving partial output earlier improves the user experience

If streaming is not required, omit `stream` or use the default response behavior.

For the complete request format, see [**Chat Completions API**](/api-guides/chat-completions-api.md).

### 🖼️ Synchronous Image Responses

Image generation is synchronous by default.

When you send a request to:

`POST /v1/images/generations`

the connection remains open until image generation finishes and the result is returned.

Example:

```bash
curl https://gw.apismart.ai/v1/images/generations \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0",
    "prompt": "A mountain village at sunrise, watercolor style",
    "size": "2K"
  }'
```

Image generation can take considerably longer than a typical text request.

A single image commonly takes approximately **20–40 seconds**, while high-resolution, multi-reference, or sequential generation requests may take longer.

Set your client timeout to at least:

`90 seconds`

> If your client disconnects before the response is returned, the generation may still complete and incur a charge.

For complete image request parameters, see [**Image Generation API**](/api-guides/image-generation-api.md).

### 🌊 Streaming Image Responses

Supported image generation workflows can also return results using SSE streaming.

Enable streaming with:

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

When testing with curl, use `-N` to prevent output buffering:

```bash
curl https://gw.apismart.ai/v1/images/generations \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "doubao-seedream-5-0",
    "prompt": "Create a minimalist product design sequence",
    "size": "2K",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {
      "max_images": 6
    },
    "stream": true
  }'
```

Streaming is particularly useful for generation workflows that may produce multiple image results.

For supported image parameters and sequential generation options, see [**Image Generation API**](/api-guides/image-generation-api.md).

### 🎬 Asynchronous Video Tasks

Video generation uses a different response pattern.

Instead of keeping the original request open until the video finishes, ApiSmart creates an asynchronous task.

The typical flow is:

1. Create a video task
2. Receive a task ID
3. Query the task status
4. Continue polling while the task is processing
5. Retrieve the result when the task succeeds

#### Step 1: Create a Task

Send:

`POST /v1/video/tasks`

Example:

```bash
curl https://gw.apismart.ai/v1/video/tasks \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0",
    "prompt": "A miniature city at night with a train moving through the streets",
    "duration": 5,
    "size": "720p"
  }'
```

The response includes a task ID.

#### Step 2: Query the Task

Use the task ID with:

`GET /v1/video/tasks/{id}`

Example:

```bash
curl https://gw.apismart.ai/v1/video/tasks/<task_id> \
  -H "Authorization: Bearer <your-api-key>"
```

#### Task Statuses

| Status      | Meaning                           |
| ----------- | --------------------------------- |
| `queued`    | Waiting to start                  |
| `running`   | Generation in progress            |
| `succeeded` | Generation completed successfully |
| `failed`    | Generation failed                 |
| `cancelled` | Task was cancelled                |
| `expired`   | Task expired                      |

Continue polling while the task is `queued` or `running`.

When the task reaches `succeeded`, the response can include the generated video result.

For complete video workflows and parameters, see [**Video Generation API**](/api-guides/video-generation-api.md).

### 🧩 Choosing the Right Response Mode

You normally do not need to choose between all response modes manually. The available options depend on the API you are calling.

Use this general guidance:

| Situation                                                    | Recommended Mode     |
| ------------------------------------------------------------ | -------------------- |
| Short text generation                                        | Standard response    |
| Interactive or longer text generation                        | Streaming            |
| Normal image generation                                      | Synchronous response |
| Supported multi-image workflows requiring progressive output | Image streaming      |
| Video generation                                             | Asynchronous task    |

When building an application that uses several ApiSmart APIs, handle each endpoint according to its response behavior rather than assuming that every model returns results in the same way.

### ⚠️ Timeouts and Long-Running Requests

Different response modes require different timeout strategies.

For standard text requests, use a timeout appropriate for the expected generation length.

For synchronous image generation, set the client timeout to at least **90 seconds**.

For asynchronous video generation, your initial request only creates the task. Your application should then query the task separately until it reaches a final state.

Avoid treating a long-running generation as a failed request solely because it takes longer than a normal API call.

### ➡️ Next Steps

Continue with:

* [**Chat Completions API**](/api-guides/chat-completions-api.md) — Send standard and streaming text requests
* [**Image Generation API**](/api-guides/image-generation-api.md) — Use synchronous and streaming image generation
* [**Video Generation API**](/api-guides/video-generation-api.md) — Create and query asynchronous video tasks
* [**API Basics**](/api-guides/api-basics.md) — Review common API conventions
* [**HTTP Status Codes and API Errors**](/troubleshooting/http-status-codes-and-api-errors.md) — Handle API errors and temporary failures