认证与基础规范

本页是所有接口的公共约定，包括基础地址、认证、请求与响应格式、分页、限流、幂等和错误处理。具体接口的参数与示例见接口总览以及各自的接口页面。

基础地址

认证

所有接口都使用同一把平台 API Key：

Authorization: Bearer sk-你的APIKey
Content-Type: application/json

Bearer 前缀可以省略（但不建议）

实测四种写法：

平台同时接受裸 token，因此返回 200 不代表客户端配置正确。反过来，如果某个客户端返回 401，先确认它是否漏发了整个 Authorization 头，而不是直接怀疑 Key 本身。请始终使用 Bearer 写法。

API Key 缺失、错误、被禁用或不属于当前账号时返回 HTTP 401：

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: 202609221135501066578648268d9d6uXuM5QgH)",
    "type": "new_api_error"
  }
}

注意 code 是空字符串。 鉴权失败时平台不填 code，所以不要用 code 是否为空来判断 请求是否出错，应以 HTTP 状态码为准。message 里的 request id 可直接取出用于提工单。

这类鉴权失败在所有接口上结构一致，message 会带上请求标识，便于排查。

响应结构

平台有三套响应结构，客户端必须同时检查 HTTP 状态码和响应体。

模型、文本、图片、视频和音频接口

成功时直接返回结果对象，失败时返回 HTTP 非 2xx 并带 error 对象：

{
  "error": {
    "code": "invalid_parameter",
    "message": "请求参数不符合所选模型要求",
    "type": "invalid_request_error",
    "param": "size"
  }
}

视频任务查询是例外：查不到任务时返回 400，响应体是顶层 { code, message, data } 结构（code 为字符串 task_not_exist），不是上述 error 对象。 详见错误码与排查。 code、type、param 的取值随错误类型变化，排查时以 message 为主，不要只匹配固定的 code 文本。

素材库接口

成功和失败都使用统一结构：

{ "code": 0, "data": {}, "msg": "OK" }

{ "code": 401, "data": null, "msg": "API Key 无效或已失效" }

失败时 HTTP 状态码与 code 一致（400 / 401 / 404 / 429 / 502 / 503）。素材审核未完成不是错误，而是 200 响应里的 status 字段（Processing / Active / Failed）。

分页

素材分组、素材列表等列表接口使用统一分页参数：

响应中的 data.total 是总条数，data.page、data.page_size 是本次生效的分页参数。请始终读取 total 判断是否还有下一页，不要用「本次返回条数」判断。

限流与重试

只对 429 和短暂的 5xx 重试；400、401、403、404、409 属于请求或权限问题，重试不会成功。

幂等与重复提交

平台不提供跨接口的自动幂等键，请在业务侧保证只提交一次：

• 每次用户操作先在自有数据库落一条业务记录，再调用平台接口；
• 视频任务和素材提交都要保存平台返回的 ID，重试前先查询是否已创建；
• 素材处于 Processing 时不要重复提交，否则会创建多份素材；
• 计费以实际提交成功的任务为准，重复提交会造成重复计费。

推荐调用顺序

GET  /v1/models                     选择模型，确认能力与可用性
POST /api/v1/materials/groups       需要素材时创建分组
POST /api/v1/materials/assets       提交图片，保存 asset_id
GET  /api/v1/materials/assets/{id}  轮询到 status 为 Active
POST /v1/video/generations          提交视频任务，用 asset://<id> 引用素材
GET  /v1/video/generations/{id}     轮询任务，读取结果或错误

服务端接入建议

1. 为每次请求设置合理超时，并区分「超时」和「用户取消」；
2. 对 429 和短暂的 5xx 做有限次退避重试，其余错误直接返回调用方；
3. 保存业务请求号、模型 ID、素材 ID、任务 ID 和平台返回的请求标识，便于排查；
4. 不要把 API Key 写进日志、错误上报、前端埋点或截图；
5. 大文件优先使用对象存储的公开 HTTPS 地址或素材库 asset:// 引用，不要把大文件塞进请求体。

下一步