> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qingbo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 同步与异步

> 了解 清波 API 的同步端点和异步任务系统

## 概述

清波 API 的端点分为两类：

<CardGroup cols={2}>
  <Card title="同步端点" icon="bolt">
    请求后阻塞等待，直接返回结果。适用于文本生成、语音合成等快速任务。
  </Card>

  <Card title="异步任务" icon="clock-rotate-left">
    请求后立即返回 task\_id，通过轮询或 Webhook 获取结果。适用于图像、视频生成等耗时任务。
  </Card>
</CardGroup>

## 同步端点

以下端点为同步模式，请求完成后直接返回结果：

| 端点                                        | 用途                   |
| ----------------------------------------- | -------------------- |
| `/v1/chat/completions`                    | 文本生成（OpenAI 兼容）      |
| `/v1/messages`                            | 文本生成（Claude 原生）      |
| `/v1/beta/models/{model}:generateContent` | 文本生成（Gemini 原生）      |
| `/v1/audio/speech`                        | TTS 文字转语音            |
| `/v1/audio/transcriptions`                | STT 语音识别             |
| `/v1/images/generations`                  | 同步图像生成               |
| `/v1/embeddings`                          | 文本嵌入                 |
| `/v1/responses`                           | OpenAI Responses API |

## 异步任务端点

图像和视频生成使用统一的异步任务系统：

| 端点                                | 用途                   |
| --------------------------------- | -------------------- |
| `POST /v1/tasks`                  | 提交异步任务，立即返回 task\_id |
| `GET /v1/tasks/{task_id}`         | 查询任务状态和结果            |
| `POST /v1/tasks/{task_id}/cancel` | 取消排队中的任务             |

<Note>
  任务族只有异步语义。需要"提交并等待"时，用 `POST /v1/tasks` + `Prefer: wait=N` 请求头
  （N ≤ 60 秒）：窗口内完成直接返回完整结果，超窗返回当前状态转轮询。
  详见 [提交任务](/cn/api-reference/task/submit#请求内等待prefer-wait)。
</Note>

## 如何选择

* **文本对话** → 使用同步端点，支持流式输出（SSE）
* **图像生成** → 简单场景用 `/v1/images/generations`，复杂场景用 `/v1/tasks`（不想轮询加 `Prefer: wait`）
* **视频生成** → 只能用 `/v1/tasks`（耗时较长）
* **需要回调通知** → 使用 `/v1/tasks` + `callback_url`