通用响应

开发者 API 的请求追踪、成功响应、异步响应、分页、错误格式和 HTTP 状态码约定。

最后更新: 2026-11-02

本页内容

请求追踪 ID

每次响应通过 X-Request-Id 返回请求编号。调用方可传入 1-64 个字符，且只含字母、数字、点、下划线、冒号和连字符；未传或格式不合法时会生成新编号，不能据此保证跨请求防重。视频任务在 result.requestId 保存原创建编号。不要在请求编号中填写完整 API Key。

X-Request-Id: req_Kf82Lm90

普通成功响应

平台 /api/v1 接口使用统一响应包装。OpenAI 兼容的 Chat Completions 与 Images API 使用各自原生成功/错误结构和真实 HTTP 状态。

Anthropic 兼容的 Messages 使用原生 message / error 结构，流式使用 Messages SSE；不使用 code/msg/result 包装，也不使用 OpenAI choices 或 [DONE]。

{
  "code": "SUCCESS",
  "msg": "操作成功",
  "result": { "id": "asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa01", "name": "品牌人物主视觉", "status": "ACTIVE" }
}

异步任务响应

V3视频创建返回原生id；异步受理不代表执行完成，请查询原任务状态。素材同步仍沿用各自统一响应。

{
  "id": "cgt-20261102120000-abc12"
}

分页响应

{
  "code": "SUCCESS",
  "msg": "操作成功",
  "result": [],
  "page": {
    "pageNum": 1,
    "pageSize": 20,
    "startRow": 0,
    "endRow": 0,
    "total": 0,
    "pages": 0
  }
}

字段	类型	说明
result	array	当前页数据。
page.pageNum	integer	当前页码，从 1 开始。
page.pageSize	integer	每页数量。
page.startRow	integer	当前页起始偏移量，第一页为 0。
page.endRow	integer	起始偏移量加当前页实际返回数量。
page.total	integer	符合条件的数据总数。
page.pages	integer	总页数。

无正文成功响应

删除等无返回数据的操作仍返回 HTTP 200 和统一成功响应。

{ "code": "SUCCESS", "msg": "操作成功" }

错误响应

{
  "code": "FAIL",
  "msg": "参数校验失败"
}

字段	类型	说明
code	string	稳定错误码，程序应使用该字段判断结果。
msg	string	可读错误说明，不建议用于程序判断。
result	object	成功时的业务结果；失败时通常为空。

HTTP 状态码

HTTP	使用场景
200 OK	成功、业务失败、参数错误和鉴权失败均使用 200。