通用响应

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

最后更新: 2026-08-06

请求追踪 ID

每次请求都会生成唯一请求 ID，并通过 X-Request-Id 响应头返回；也可以主动传入不超过 128 个字符且只含字母、数字、点、下划线、冒号和连字符的 X-Request-Id。视频任务还会把创建请求的 requestId 保存到 result.requestId。

X-Request-Id: req_Kf82Lm90

普通成功响应

所有接口使用统一响应包装。code 为 SUCCESS 表示成功，msg 为提示文本，result 为业务对象。

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

异步任务响应

视频生成、素材同步等异步接口也返回 HTTP 200。QUEUED 或 PROCESSING 仅表示任务已创建，不表示处理完成。

{
  "code": "SUCCESS",
  "msg": "操作成功",
  "result": { "taskId": "task_550e8400e29b41d4a71644665544000012345", "status": "QUEUED", "model": "doubao-seedance-2-0-260128", "createdAt": "2026-07-10 09:42:00" }
}

分页响应

{
  "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。