> ## 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.

# 请求与响应格式

> 通用请求头、响应结构与错误码说明

## 请求格式

所有请求使用 JSON 格式，需要以下 headers：

```bash theme={"system"}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

## 成功响应

不同端点的响应结构有所不同，但都遵循各自的 API 规范：

* **Chat Completions** — OpenAI 标准响应格式
* **Claude Messages** — Anthropic 标准响应格式
* **Gemini** — Google 标准响应格式
* **异步任务** — 清波 API 统一任务响应格式

## 计费字段（usage.cost）

文本与嵌入端点的响应 `usage` 中带本次调用的实际扣费（quota，整数）：

```json theme={"system"}
{
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20,
    "cost": 150
  }
}
```

* **非流式** → 响应体 `usage.cost`
* **流式（SSE）** → 最后一个带 `usage` 的数据帧（详见[流式输出](/cn/docs/streaming)）
* **异步任务** → 提交返 `pre_consumed_cost`（预扣），终态返 `cost`（结算；失败/取消已退款为 0）

按调用对账时，以这些字段累计值为准，与账户余额扣减严格一致。

## 错误响应

不同端点的错误结构略有差异:

**同步端点(chat / messages / images 等)**— OpenAI 兼容格式,带 `type` 字段:

```json theme={"system"}
{
  "error": {
    "message": "具体的错误描述信息",
    "type": "invalid_request_error",
    "code": "invalid_request"
  }
}
```

**异步任务端点(`/v1/tasks/...`)**— 简化格式,只 `message` + `code`:

```json theme={"system"}
{
  "error": {
    "message": "具体的错误描述信息",
    "code": "task_failed"
  }
}
```

## 状态码

| 状态码 | 说明                                                                                    | 处理方式                       |
| --- | ------------------------------------------------------------------------------------- | -------------------------- |
| 400 | 请求参数无效                                                                                | 检查请求参数格式                   |
| 401 | 认证失败                                                                                  | 检查 API Key 是否正确            |
| 402 | 余额不足                                                                                  | 充值账户                       |
| 404 | 任务/资源未找到                                                                              | 检查 task\_id 是否正确 / 是否归当前账号 |
| 429 | 请求频率超限 / 滑动窗口额度用尽（`code: quota_window_exceeded`，响应含 `window`/`used`/`cap`/`reset_at`） | 降低频率，或等待 `reset_at` 后重试    |
| 500 | 服务器内部错误                                                                               | 稍后重试                       |