请求与响应格式

请求格式

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

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

成功响应

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

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

计费字段（usage.cost）

/v1/chat/completions 与 /v1/embeddings 的 OpenAI 格式响应在 usage.cost 中返回本次调用的计费额度。单位是 quota（整数），不是美元（USD）。例如，cost: 150 表示 150 quota。

{
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20,
    "cost": 150
  }
}

Chat Completions 非流式、Embeddings → 响应体 usage.cost
Chat Completions 流式（SSE） → 最后一个带 usage 的数据帧（详见流式输出）

Claude Messages（/v1/messages）、OpenAI Responses（/v1/responses）与 Gemini 原生接口使用各自的用量结构，目前未定义统一的网关 usage.cost 字段。不要将其中的同名上游字段直接解释为网关 quota；这些接口的费用请在控制台用量记录中核对。异步任务有独立的费用和结算状态字段，见查询任务。不要将任务费用字段与文本 usage.cost 按同一单位直接相加。

错误响应

不同端点的错误结构略有差异: 同步端点(chat / messages / images 等)— OpenAI 兼容格式,带 type 字段:

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

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

{
  "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	服务器内部错误	稍后重试

开始

核心概念

请求与响应格式

请求格式

成功响应

计费字段（usage.cost）

错误响应

状态码

​请求格式

​成功响应

​计费字段（usage.cost）

​错误响应

​状态码

请求格式

成功响应

计费字段（usage.cost）

错误响应

状态码