文档目录

约定与错误码

两个命名空间、请求与响应头约定、三种错误信封、完整错误码表、分页与版本兼容。

内容最后核对: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_missing401请求里没有任何一个被接受的密钥位置
auth.invalid_key401密钥无效、已停用,或签发它的账号被停用
auth.unauthorized401控制台接口需要登录(未带或无法识别访问令牌)
auth.forbidden403已登录,但没有这个操作的权限
auth.account_disabled403账号被停用
auth.key_on_console401把 API Key 用在控制台接口上

模型与渠道

code状态码说明
model.not_found404模型不在可用清单
model.disabled403模型被停用或已下架
model.not_in_group403当前分组的密钥不可用该模型
model.modality_not_supported400入站协议、端点与模型能力不符
model.ambiguous409显示名对应多条记录,请用规范 id
model.async_not_supported400该渠道只提供流式,不支持异步参数
channel.unavailable503没有可用渠道
channel.all_failed502所有候选渠道都失败
channel.credential_expired502上游凭据失效
channel.protocol_unsupported400该渠道不支持这种调用格式

计量与计费

code状态码说明
quota.insufficient402余额不足(异步任务在预扣阶段返回)
quota.exhausted402额度已用尽
price.stale409价目表已过期,暂时无法下单
image.tier_unsupported400该模型不支持请求的尺寸档位

上游

code状态码说明
upstream.timeout504上游超时
upstream.error502上游返回错误
upstream.invalid_response502上游响应无法解析
upstream.auth_failed502上游拒绝我们的凭据
upstream.rate_limited429上游限流
upstream.unreachable502连不上上游
upstream.bad_request400上游认为请求本身有问题

任务与产物

code状态码说明
job.failed500任务失败(异步端点以 SUBMIT_FAILED 表达)
job.submit_failed502提交就被上游拒绝,预扣已全额释放;/v1/videos 的响应体里仍带任务 id
job.invalid_state409当前状态不允许这个动作(如还没完成就取产物)
content_link.expired400产物链接过期,走 refresh-url
content_link.refresh_unsupported400该上游不能续期,只能重新生成

请求本身

code状态码说明
validation.failed400字段缺失或格式不对,message 会指出哪一项
rate.limited429请求过于频繁
internal.error500服务暂时不可用,带 X-Request-Id 联系管理员

分页(/api/**)

没有统一的信封,按端点各写各的:

端点请求参数响应字段
GET /api/jobsstatus、page(从 1 起)、size{total, page, size, rows}
GET /api/logsrange、status、q、page、pageSize(超过 200 按 200 处理){total, limit, offset, rows}

新接入按上表写,别按一个假想的「通用分页形状」写 —— 猜错的表现是 rows 读成 items、拿到空列表却以为没数据。

total 是发起请求那一刻的总数,而每页是分批取的:两次请求之间新增的记录,会让翻页出现一条重复或漏项。需要严格快照时按 id 升序自行分页。

版本与兼容

  • 入站形状一旦发布就不改语义:/v1/videos 的字段按 Sora 契约,/kling、/jimeng 按厂商契约。
  • 新增字段是兼容的,调用方应忽略不认识的字段;改字段类型不兼容(例如把 seconds 从字符串改成数字),这类变更会同步发公告。
  • 网关扩展出来的字段一律带说明(如 Sora 形状里的 state、/link 端点),官方 SDK 不认识它们也不会报错。