视频生成API 文档

1. 接口概览

基础路径：/video/generation/tasks

鉴权方式：API Key

接口协议：HTTP + JSON

任务模式：异步任务

接口	方法	路径	说明
创建视频任务	`POST`	`/video/generation/tasks`	按照实际厂商的原始请求参数格式，并返回统一响应结构
查询任务详情	`GET`	`/video/generation/tasks/{taskId}`	查询单个视频任务详情

2. 鉴权说明

所有接口都需要传 API Key。

推荐请求头：

同时兼容以下请求头：

x-api-key

api-key

apikey

api_key

x-auth-token

authorization

如果未传 API Key，会返回 401。
如果 API Key 无效，会返回 403。

3. 返回结构说明

创建接口和查询接口都使用统一返回结构：

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}

字段说明：

字段	类型	说明
`code`	integer	业务状态码，成功通常为 `200`
`msg`	string	响应消息
`data`	object	具体业务数据

4. 创建视频任务

4.1 接口信息

方法：POST

路径：/video/generation/tasks

Content-Type：application/json

4.2 请求体要求

请求体必须是合法 JSON 字符串，且至少包含一个有效模型字段。

通用约束：

模型必须是当前 API Key 已授权模型

4.3 幂等键（Idempotency-Key）

创建接口支持幂等键，强烈建议客户端在每次创建请求时携带，用于防止网络超时重试时产生重复计费。

使用方式

在请求头中传入 Idempotency-Key，值为客户端生成的唯一字符串（推荐 UUID）：

行为说明

场景	服务端行为
首次请求（无缓存）	正常执行，成功后将响应缓存 24 小时
重试（相同幂等键，首次已成功）	直接返回缓存响应，不重新执行预扣费，不产生新任务
重试（相同幂等键，首次失败）	正常重新执行（失败结果不缓存，允许重试）
并发请求（相同幂等键同时到达）	第一个请求正常执行，后续返回 `500` 提示处理中
不传幂等键	每次请求独立执行，不保证幂等

幂等键格式建议

使用 UUID v4（如 550e8400-e29b-41d4-a716-446655440000）

每次新的任务创建意图使用新的幂等键

同一次创建意图的重试，使用相同的幂等键

幂等键有效期为 24 小时，超期后相同 key 视为新请求

4.5 请求示例

说明：提示词根据官方的要求来传，下面只是示例

不带幂等键：

带幂等键（推荐）：

4.6 成功响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "taskId": "0198b6b7-xxxx-xxxx-xxxx-abcdef123456",
    "status": "queued",
    "createdAt": "1778823817"
  }
}

4.7 响应说明

创建接口 data 字段说明：

字段	类型	说明
`taskId`	string	任务 ID，后续查询建议直接使用该值
`status`	string	任务状态
`createdAt`	string	创建时间

5. 查询视频任务详情

5.1 接口信息

方法：GET

路径：/video/generation/tasks/{taskId}

5.2 路径参数

参数	类型	必填	说明
`taskId`	string	是	任务 ID，建议优先传创建接口返回的 `taskId`

5.3 请求示例

5.4 成功响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "taskId": "zlhub:0198b6b7-xxxx-xxxx-xxxx-abcdef123456",
    "status": "SUCCESS",
    "createdAt": "2026-05-15T10:00:00Z",
    "progress": 100,
    "resultUrl": "https://example.com/result.mp4",
    "thumbnailUrl": "https://example.com/thumbnail.jpg",
    "failReason": null,
    "tokenUsage": {
      "taskId": "0198b6b7-xxxx-xxxx-xxxx-abcdef123456",
      "model": "seedance-2-0",
      "inputTokens": 1200,
      "outputTokens": 0,
      "totalTokens": 1200,
      "durationMs": 32500,
      "inputTokenDetails": {},
      "outputTokenDetails": {},
      "rawUsage": {}
    }
  }
}

5.5 `data` 字段说明

字段	类型	说明
`taskId`	string	统一任务 ID
`status`	string	统一任务状态，固定映射为 `PENDING`、`RUNNING`、`SUCCESS`、`FAILED`、`CANCELLED` 之一
`createdAt`	string	任务创建时间
`progress`	integer	任务进度，成功时通常为 `100`
`resultUrl`	string	生成结果地址
`thumbnailUrl`	string	缩略图地址
`failReason`	string	失败原因
`tokenUsage`	object	token 用量信息，未返回时可能为 `null`

5.6 `tokenUsage` 字段说明

字段	类型	说明
`taskId`	string	厂商原始任务 ID
`model`	string	模型编码
`inputTokens`	integer	输入 token 数
`outputTokens`	integer	输出 token 数
`totalTokens`	integer	总 token 数
`durationMs`	integer	耗时，毫秒
`inputTokenDetails`	object	输入 token 细项
`outputTokenDetails`	object	输出 token 细项
`rawUsage`	object	厂商原始用量明细

说明：

如果需要做业务状态判断，建议优先使用统一状态字段 status

6. 错误响应

6.1 厂商类错误和鉴权错误

这类错误返回 HTTP 状态码，并使用统一结构：

{
  "code": 400,
  "msg": "错误信息",
  "data": {
    "code": "VID-4001",
    "message": "错误信息",
    "retryable": false,
    "requestId": "req_xxx",
    "provider": "byteplus",
    "path": "/video/generation/tasks/xxx"
  }
}

字段说明：

字段	类型	说明
`code`	integer	HTTP 状态码，同时也会写入响应体
`msg`	string	错误消息
`data.code`	string	业务错误码
`data.message`	string	错误描述
`data.retryable`	boolean	是否建议重试
`data.requestId`	string	上游请求 ID，部分场景可能为空
`data.provider`	string	厂商标识，鉴权错误时通常为 `local`
`data.path`	string	当前请求路径

6.2 常见错误码

错误码	HTTP 状态	说明	是否可重试
`VID-4001`	`400`	请求参数校验失败	否
`VID-4002`	`401`	供应商鉴权失败	否
`VID-4004`	`404`	任务不存在	否
`VID-4290`	`429`	请求频率过高	是
`VID-5001`	`500`	供应商请求超时	是
`VID-5002`	`500`	供应商服务暂不可用	是
`VID-5003`	`500`	供应商返回数据无法解析	否
`VID-5004`	`500`	供应商内部错误	是
`VID-5999`	`500`	未知供应商异常	否

6.3 鉴权失败示例

缺少 API Key：

{
  "code": 401,
  "msg": "缺少 API Key",
  "data": {
    "code": "VID-4010",
    "message": "缺少 API Key",
    "retryable": false,
    "requestId": null,
    "provider": "local",
    "path": "/video/generation/tasks"
  }
}

API Key 无效：

{
  "code": 403,
  "msg": "无效的 API Key",
  "data": {
    "code": "VID-4030",
    "message": "无效的 API Key",
    "retryable": false,
    "requestId": null,
    "provider": "local",
    "path": "/video/generation/tasks"
  }
}

6.4 框架级参数错误

如果请求体不是合法 JSON，可能返回：

{
  "code": 400,
  "msg": "请求参数格式错误：具体解析异常",
  "data": null
}

7. 对接建议

创建接口的请求体字段，应以目标上游厂商实际文档为准

创建成功后务必保存统一 taskId

查询时推荐直接使用创建接口返回的 taskId

对接方做业务状态判断时，优先使用查询结果中的统一状态 status

如果需要做计费或用量展示，可优先读取查询结果中的 tokenUsage

创建接口强烈建议携带 Idempotency-Key 请求头，防止网络超时重试产生重复计费

Seedance视频生成API 文档

视频生成API 文档#

1. 接口概览#

2. 鉴权说明#

3. 返回结构说明#

4. 创建视频任务#

4.1 接口信息#

4.2 请求体要求#

4.3 幂等键（Idempotency-Key）#

使用方式#

行为说明#

幂等键格式建议#

4.5 请求示例#

4.6 成功响应示例#

4.7 响应说明#

5. 查询视频任务详情#

5.1 接口信息#

5.2 路径参数#

5.3 请求示例#

5.4 成功响应示例#

5.5 data 字段说明#

5.6 tokenUsage 字段说明#

6. 错误响应#

6.1 厂商类错误和鉴权错误#

6.2 常见错误码#

6.3 鉴权失败示例#

6.4 框架级参数错误#

7. 对接建议#