API 文档 · TRAE Video

VIDEO GENERATION API

把 Seedance 接入你的工作流

接口兼容常见的视频生成调用方式。创建任务后使用任务 ID 查询状态，完成后从同源地址播放或下载 MP4。

Base URL

建议把 API Key 放在服务端环境变量中，不要写入浏览器代码、日志或公开仓库。

认证

兼容 API 使用控制台 API 用户生成的 Bearer Key。

HEADERAuthorization: Bearer $API_USER_KEY

curl /v1/models \
  -H "Authorization: Bearer $API_USER_KEY"

Key 管理Key 只在管理台创建或轮换；停用后立即失效。文档页不会读取或保存任何 Key。

模型

用模型 ID 传入 model 字段；别名 seedance-2.0 和 seedance-2.5 也兼容。

GET/v1/models

模型 ID	显示名称	类型
`tr_seedance-2.0_faceok`	TRAE Seedance 2.0 过人脸	video
`tr_seedance-2.0`	TRAE Seedance 2.0	video

创建视频

三个路径完全等价，推荐使用 /v1/videos。

POST/v1/videos

POST/v1/videos/generations

POST/v1/video/generations

请求体

字段	类型	说明
`prompt`	string	视频描述，1-4000 字符；也可以用 `content` 提供素材。
`model`	string	模型 ID，默认 `tr_seedance-2.0`；别名 `seedance-2.0`、`seedance-2.5` 兼容。
`seconds`	number	时长：`5`、`10` 或 `12`。
`resolution`	string	`720p` 或 `1080p`，默认 `1080p`。
`aspect_ratio`	string	`16:9`、`9:16` 或 `1:1`。
`frame_mode`	string	`first_only` 或 `all`。
`generate_audio`	boolean	是否生成声音，默认 `true`；也接受 camelCase 写法。
`images`	array	可选图片 URL、data URL 或对象；远程 URL 必须在服务端白名单，也可使用 `content` 或先上传素材。

cURL 示例

curl -X POST /v1/videos \
  -H "Authorization: Bearer $API_USER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20260821-0001" \
  -d '{
    "model": "tr_seedance-2.0",
    "prompt": "一只猫在窗边看雨，镜头缓慢推近",
    "seconds": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "frame_mode": "first_only",
    "generate_audio": true
  }'

202 Accepted首次创建任务200 OK幂等键命中已有任务

{
  "id": "video_xxx",
  "task_id": "video_xxx",
  "object": "video",
  "status": "in_progress",
  "progress": 0,
  "model": "tr_seedance-2.0",
  "seconds": 5,
  "resolution": "1080p"
}

返回地址任务完成且成品已回传时，响应会附带 video_url；也可以直接调用 content 接口。

幂等同一个 Idempotency-Key 重试会返回原任务；换请求内容复用该 Key 会得到 idempotency_key_conflict。

查询与下载

任务只对创建它的 API 用户可见。

GET/v1/videos支持 search、status、limit

GET/v1/videos/:id

GET/v1/videos/:id/contentMP4；加 ?download=1 强制下载

in_progresscompletedfailed

兼容 API 会把内部的排队、处理中和待配置状态统一映射为 in_progress。建议每 3-10 秒轮询一次，直到进入终态。

curl /v1/videos/video_xxx \
  -H "Authorization: Bearer $API_USER_KEY"

curl -L /v1/videos/video_xxx/content?download=1 \
  -H "Authorization: Bearer $API_USER_KEY" \
  -o video_xxx.mp4

200 OK查询返回 JSON；内容接口返回 video/mp4。

原生任务 API

需要服务端配置的 UPSTREAM_API_KEY，适合需要先上传素材或读取完整任务字段的后端调用。

与兼容 API 分开这里的 Key 与“API 用户” Bearer Key 不是同一类凭据。不要把 UPSTREAM_API_KEY 放到浏览器或客户端应用中。

POST/api/v1/assets上传单个素材，最大 100 MB

curl -X POST /api/v1/assets \
  -H "Authorization: Bearer $UPSTREAM_API_KEY" \
  -H "Content-Type: image/png" \
  -H "X-File-Name: reference.png" \
  --data-binary @reference.png

POST/api/v1/video-jobs必须提供 8-128 字符幂等键

curl -X POST /api/v1/video-jobs \
  -H "Authorization: Bearer $UPSTREAM_API_KEY" \
  -H "Idempotency-Key: order-20260821-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "plugin": "seedance",
    "prompt": "使用参考图生成一段电影感运镜视频",
    "references": [{"assetId": "asset_xxx", "kind": "image"}]
  }'

GET/api/v1/video-jobs/:id

GET/api/v1/video-jobs/:id/video返回 MP4 附件

原生任务状态保留 queued、processing、completed、failed 和 configuration_required。下载和查询都需要同一把上游 Key。

错误处理

兼容 API 使用统一的错误对象；HTTP 状态码是判断请求是否成功的第一依据。

{
  "error": {
    "message": "API_KEY_INVALID",
    "type": "invalid_request_error",
    "code": "api_key_invalid"
  }
}

HTTP	code	处理建议
401	`api_key_required` / `api_key_invalid`	检查 Bearer Key 是否存在、有效且未停用。
400	`model_invalid` / `payload_invalid`	按请求字段表修正模型或 JSON。
404	`job_not_found`	确认任务 ID 属于当前 API 用户，且已完成后再下载。
409	`idempotency_key_conflict`	为新的请求生成新的幂等键。
409	`trae_credits_exhausted` / `trae_protocol_account_unavailable`	检查账号积分、登录状态和虚拟池成员。
429	`api_user_total_limit_exhausted`	检查 API 用户配额或联系管理台调整。
503	`trae_protocol_unavailable` / `trae_credits_unavailable` / `trae_credits_settlement_pending`	协议会话或积分状态暂不可用，稍后重试并检查账号会话。