约定与错误码
两个命名空间、请求与响应头约定、三种错误信封、完整错误码表、分页与版本兼容。
内容最后核对:2026-11-18
本页目录
两个命名空间
| 前缀 | 鉴权 | 用途 | 错误信封 |
|---|---|---|---|
/v1/**、/v1beta/**、厂商原生路径 | API Key | 模型调用 | OpenAI 嵌套 |
/api/** | 登录后拿到的访问令牌 | 控制台、管理、账单 | 扁平 |
/api 不是 /v1 的前缀。两套命名空间互不通用,理由见鉴权与密钥。
请求约定
- JSON 用
Content-Type: application/json;音频上传用multipart/form-data。 - 接口返回的时间是 UTC。任务视图里的时间字段形如
2026-11-17T07:05:22,不带时区后缀,按 UTC 解析;Sora 形状的时间是秒级整数。 - 未知字段被静默忽略(不是 400)。写错键名会得到「参数没生效」的 200 —— 这类问题只能靠对照本文的字段表发现。
- 需要幂等的提交认
Idempotency-Key头,也认请求体里的idempotencyKey。
响应头
| 头 | 说明 |
|---|---|
X-Request-Id | 每个响应都有,也出现在错误体的 request_id 里 |
Content-Type | 语音合成、视频下载的成败要靠它区分(audio/*、video/* vs application/json) |
Cache-Control: … no-transform | 流式端点会加(另含 X-Accel-Buffering: no),避免中间代理与压缩把逐帧增量攒成整包 |
错误信封
/v1/** 是 OpenAI 嵌套形状,固定英文:
{"error": {"message": "Invalid API key.", "type": "authentication_error",
"code": "auth.invalid_key", "request_id": "req_b716..."}}
code是稳定契约,永不随语言变化。用它判分支。message永远英文:调用方是程序,SDK 要可 grep、可写进单测。不读Accept-Language。request_id与响应头X-Request-Id是同一个值。
/api/** 是扁平信封,且按语言本地化:
{"code": "validation.failed", "message": "参数不合法", "request_id": "req_...", "details": null}
两套信封共用同一套 code。
厂商路径有它们自己的信封,因为要用官方 SDK 解析:
| 路径 | 信封 |
|---|---|
/kling/** | {"code": 0, "message": "", "request_id": "", "data": {...}},错误码是数值(1201 / 1000 / 1203 / 1302 / 5000) |
/jimeng* | {"code": 10000, "data": {...}, "message": "Success", "status": 10000},错误码是 5xxxx |
/v1/messages | 顶层 {"type": "error", "error": {...}}(Anthropic 协议要求) |
把可灵的 400 翻成 {error:{code:"validation.failed"}} 等于让它的 SDK 报「解析失败」,真实原因完全不可见。
错误码
按场景分组。code 是稳定标识,前端与调用方都应按它分支。
鉴权
| code | 状态码 | 说明 |
|---|---|---|
auth.key_missing | 401 | 请求里没有任何一个被接受的密钥位置 |
auth.invalid_key | 401 | 密钥无效、已停用,或签发它的账号被停用 |
auth.unauthorized | 401 | 控制台接口需要登录(未带或无法识别访问令牌) |
auth.forbidden | 403 | 已登录,但没有这个操作的权限 |
auth.account_disabled | 403 | 账号被停用 |
auth.key_on_console | 401 | 把 API Key 用在控制台接口上 |
模型与渠道
| code | 状态码 | 说明 |
|---|---|---|
model.not_found | 404 | 模型不在可用清单 |
model.disabled | 403 | 模型被停用或已下架 |
model.not_in_group | 403 | 当前分组的密钥不可用该模型 |
model.modality_not_supported | 400 | 入站协议、端点与模型能力不符 |
model.ambiguous | 409 | 显示名对应多条记录,请用规范 id |
model.async_not_supported | 400 | 该渠道只提供流式,不支持异步参数 |
channel.unavailable | 503 | 没有可用渠道 |
channel.all_failed | 502 | 所有候选渠道都失败 |
channel.credential_expired | 502 | 上游凭据失效 |
channel.protocol_unsupported | 400 | 该渠道不支持这种调用格式 |
计量与计费
| code | 状态码 | 说明 |
|---|---|---|
quota.insufficient | 402 | 余额不足(异步任务在预扣阶段返回) |
quota.exhausted | 402 | 额度已用尽 |
price.stale | 409 | 价目表已过期,暂时无法下单 |
image.tier_unsupported | 400 | 该模型不支持请求的尺寸档位 |
上游
| code | 状态码 | 说明 |
|---|---|---|
upstream.timeout | 504 | 上游超时 |
upstream.error | 502 | 上游返回错误 |
upstream.invalid_response | 502 | 上游响应无法解析 |
upstream.auth_failed | 502 | 上游拒绝我们的凭据 |
upstream.rate_limited | 429 | 上游限流 |
upstream.unreachable | 502 | 连不上上游 |
upstream.bad_request | 400 | 上游认为请求本身有问题 |
任务与产物
| code | 状态码 | 说明 |
|---|---|---|
job.failed | 500 | 任务失败(异步端点以 SUBMIT_FAILED 表达) |
job.submit_failed | 502 | 提交就被上游拒绝,预扣已全额释放;/v1/videos 的响应体里仍带任务 id |
job.invalid_state | 409 | 当前状态不允许这个动作(如还没完成就取产物) |
content_link.expired | 400 | 产物链接过期,走 refresh-url |
content_link.refresh_unsupported | 400 | 该上游不能续期,只能重新生成 |
请求本身
| code | 状态码 | 说明 |
|---|---|---|
validation.failed | 400 | 字段缺失或格式不对,message 会指出哪一项 |
rate.limited | 429 | 请求过于频繁 |
internal.error | 500 | 服务暂时不可用,带 X-Request-Id 联系管理员 |
分页(/api/**)
没有统一的信封,按端点各写各的:
| 端点 | 请求参数 | 响应字段 |
|---|---|---|
GET /api/jobs | status、page(从 1 起)、size | {total, page, size, rows} |
GET /api/logs | range、status、q、page、pageSize(超过 200 按 200 处理) | {total, limit, offset, rows} |
新接入按上表写,别按一个假想的「通用分页形状」写 —— 猜错的表现是 rows 读成 items、拿到空列表却以为没数据。
total 是发起请求那一刻的总数,而每页是分批取的:两次请求之间新增的记录,会让翻页出现一条重复或漏项。需要严格快照时按 id 升序自行分页。
版本与兼容
- 入站形状一旦发布就不改语义:
/v1/videos的字段按 Sora 契约,/kling、/jimeng按厂商契约。 - 新增字段是兼容的,调用方应忽略不认识的字段;改字段类型不兼容(例如把
seconds从字符串改成数字),这类变更会同步发公告。 - 网关扩展出来的字段一律带说明(如 Sora 形状里的
state、/link端点),官方 SDK 不认识它们也不会报错。