媒体接口 / 视频生成

视频生成 API

使用火山方舟兼容的异步任务接口生成视频。本文档覆盖当前 TokenBox 生产环境已经开放的模型、参数、素材规则和任务状态。

异步任务video.generations生产链路已验证

接口概览

创建接口返回 HTTP 202 和平台任务 ID。查询接口读取平台任务状态；Worker 在后台轮询上游并完成 usage 与账单结算。

方法	路径	用途
POST	`/api/v3/contents/generations/tasks`	创建异步视频任务
GET	`/api/v3/contents/generations/tasks/{task_id}`	查询单个视频任务
POST	`/v1/contents/generations/tasks`	创建异步视频任务
GET	`/v1/contents/generations/tasks/{task_id}`	查询单个视频任务

推荐新的视频客户端使用 /api/v3 路径以对齐火山方舟；现有 /v1 路径行为完全一致。

当前不提供任务取消、删除、公开任务列表或 callback_url。客户端必须保存创建响应中的 id 并主动轮询。

模型能力

模型 ID 使用 TokenBox 平台标识，不要提交上游供应商模型名。上线前应通过 GET /v1/models 确认目标模型对当前 Key 可见。

模型 ID	输出分辨率	输出时长	参考素材上限
`bytedance/seedance-2.0`	480p / 720p / 1080p / 4k	-1 / 4–15s	9 图 / 3 视频 / 3 音频
`bytedance/seedance-2.0-fast`	480p / 720p	-1 / 4–15s	9 图 / 3 视频 / 3 音频
`bytedance/seedance-2.0-mini`	480p / 720p	-1 / 4–15s	9 图 / 3 视频 / 3 音频
`bytedance/seedance-2.5`	480p / 720p / 1080p	-1 / 4–30s	30 图 / 10 视频 / 10 音频

鉴权与幂等

创建和查询均使用 Bearer API Key，并要求 video.generations 权限。创建请求还必须包含 Idempotency-Key。

Header	必填	说明
`Authorization: Bearer $TOKENBOX_API_KEY`	是	API Key，仅在服务端发送
`Idempotency-Key: <unique-value>`	是	每个业务任务唯一；网络重试必须复用原值
`Content-Type: application/json`	是	创建任务时固定为 application/json

相同 Idempotency-Key 与相同请求会返回原任务；同一个 Key 对应不同请求时返回 409 idempotency_conflict。

创建请求参数

未填写的可选参数按表中默认值处理。未知顶层字段会被拒绝，避免未纳入计费和安全控制的参数透传上游。

字段	类型	必填	默认值	说明
`model`	`string`	是	—	TokenBox 视频模型 ID。
`content`	`array`	是	—	提示词与参考素材组成的数组，至少 1 项。
`resolution`	`string`	否	720p	输出分辨率；可选值受模型能力限制。
`ratio`	`string`	否	adaptive	adaptive、21:9、16:9、4:3、1:1、3:4、9:16。
`duration`	`integer`	否	5	-1，或整数秒。2.0 系列为 4–15，2.5 为 4–30；与 frames 互斥。
`frames`	`integer`	否	—	1–361；与 duration 互斥，平台按 24 FPS 计费估算。
`generate_audio`	`boolean`	否	true	是否生成音频。
`watermark`	`boolean`	否	false	是否添加水印。
`return_last_frame`	`boolean`	否	—	成功结果是否返回 content.last_frame_url。
`seed`	`integer`	否	—	随机种子整数；相同种子不保证完全相同的结果。
`camera_fixed`	`boolean`	否	—	是否尽量保持镜头固定。
`omni_reference_task_type`	`string`	否	—	仅 Seedance 2.5：auto、edit、extend。
`execution_expires_after`	`integer`	否	172800	仅接受 172800。
`priority`	`integer`	否	0	任务优先级，0–9。

callback_url、tools、draft、service_tier 当前不支持。

content 与素材规则

content 按数组顺序编号。同一种素材分别从 1 开始，可在提示词中使用 @图像1、@视频1、@音频1 指定引用关系。

type	role	可用来源
`text`	—	提示词文本
`image_url`	`first_frame / last_frame / reference_image`	公网 HTTP(S)、data: Base64、asset://vas_*
`video_url`	`reference_video`	公网 HTTP(S)、asset://vas_*；不支持 Base64 视频
`audio_url`	`reference_audio`	公网 HTTP(S)、data: Base64、asset://vas_*

首帧/首尾帧与全模态参考素材互斥。首帧、尾帧各最多 1 张；帧模式必须使用 ratio=adaptive。

Seedance 2.5 的 edit 和 extend 必须包含 reference_video 且 ratio=adaptive；edit 还要求 duration=-1。2.5 支持纯音频，2.0 音频必须搭配图片或视频。

媒体文件要求

以下为火山方舟当前输入要求。TokenBox 会校验 JSON、数量、角色和 asset:// 状态；公网 URL 或 Base64 的媒体字节仍可能由上游在任务处理阶段拒绝，因此调用方应在提交前完成同等规格校验。

素材	格式	大小	尺寸 / 时长
图片	JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF	单张小于 30 MB	宽高各 300–6000 px；宽高比 0.4–2.5
视频	MP4、MOV；H.264/AVC 或 H.265/HEVC	单段不超过 200 MB	宽高各 300–6000 px；407696–8295044 像素；24–60 FPS
音频	MP3、WAV	单段不超过 15 MB	单段及同类总时长：2.0 不超过 15 秒；2.5 不超过 30 秒

JSON 请求体最大 64 MiB。较大素材应使用公网 URL 或先上传到素材库，不要放入 Base64。

调用示例

以下示例使用生产域名和已开放的平台模型 ID。将占位素材替换为可公开下载或当前用户拥有的 active 素材。

文生视频

export TOKENBOX_API_KEY="tfk-your-key"
export IDEMPOTENCY_KEY="$(uuidgen)"

curl -sS https://tokenbox.me/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $TOKENBOX_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0-mini",
    "content": [
      {"type": "text", "text": "雨后的杭州西湖，电影感航拍镜头"}
    ],
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "generate_audio": false,
    "watermark": false
  }'

图片 + 视频 + 音频参考

export IDEMPOTENCY_KEY="$(uuidgen)"

curl -sS https://tokenbox.me/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $TOKENBOX_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.5",
    "content": [
      {"type": "text", "text": "参考 @图像1、@视频1 和 @音频1 的主体、运动与节奏，生成一段连贯视频"},
      {"type": "image_url", "role": "reference_image",
       "image_url": {"url": "asset://vas_image_id"}},
      {"type": "video_url", "role": "reference_video",
       "video_url": {"url": "asset://vas_video_id"}},
      {"type": "audio_url", "role": "reference_audio",
       "audio_url": {"url": "asset://vas_audio_id"}}
    ],
    "resolution": "720p",
    "ratio": "adaptive",
    "duration": -1,
    "omni_reference_task_type": "auto"
  }'

首尾帧生成

curl -sS https://tokenbox.me/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $TOKENBOX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "content": [
      {"type": "text", "text": "雨后的杭州西湖，电影感航拍镜头"},
      {"type": "image_url", "role": "first_frame",
       "image_url": {"url": "https://example.com/first.jpg"}},
      {"type": "image_url", "role": "last_frame",
       "image_url": {"url": "https://example.com/last.jpg"}}
    ],
    "resolution": "720p",
    "ratio": "adaptive",
    "duration": 5,
    "return_last_frame": true
  }'

响应与轮询

创建成功返回 202。查询成功返回 200；仅 succeeded 状态包含 content.video_url 和 usage。

202 创建响应

{
  "id": "video_01JXXXXXXXXXXXXXXX",
  "object": "video.generation.task",
  "model": "bytedance/seedance-2.0-mini",
  "status": "queued",
  "created_at": 1780000000,
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 4
}

200 成功任务

{
  "id": "video_01JXXXXXXXXXXXXXXX",
  "object": "video.generation.task",
  "model": "bytedance/seedance-2.0-mini",
  "status": "succeeded",
  "content": {
    "video_url": "https://provider.example/result.mp4"
  },
  "usage": {
    "completion_tokens": 40594,
    "total_tokens": 40594
  },
  "created_at": 1780000000,
  "updated_at": 1780000060,
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 4,
  "framespersecond": 24,
  "generate_audio": false
}

状态	含义与处理
`submitting`	平台正在提交上游；继续轮询，不要重新创建。
`queued`	任务已被上游接受，等待执行。
`running`	正在生成。
`succeeded`	生成成功；读取 content.video_url 和 usage。
`failed`	生成失败；读取 error.code 和 error.message。
`cancelled`	上游取消，终态，不计生成结果。
`expired`	任务租约或上游任务已过期，终态。

建议首次等待 15 秒后查询；queued/running 可每 15–30 秒轮询，网络错误按 15、30、60 秒退避。结果签名 URL 有效期为 24 小时，请及时转存。

错误处理

优先判断 HTTP 状态码和 error.code，并保存响应头 x-request-id。Provider 处理阶段失败会体现在任务的 error 字段。

HTTP	错误码	处理建议
`400`	`invalid_request`	JSON、字段范围、素材数量或模式组合不合法
`400`	`idempotency_key_required`	创建请求缺少 Idempotency-Key
`409`	`idempotency_conflict`	同一幂等键被用于不同请求
`402`	`insufficient_balance`	积分不足，充值积分后重新创建
`422`	`pricing_limit_exceeded`	预估积分消耗超过当前模型的单请求扣费上限
`429`	`rate_limit_exceeded / concurrent_limit_exceeded`	创建频率或活跃任务数超过限制
`400`	`provider_invalid_request`	上游拒绝媒体或生成参数；检查任务错误信息
`503`	`provider_result_unknown`	上游提交结果不确定；不要自动更换幂等键重试

可执行端到端脚本

脚本会创建一个 480p、4 秒、无声任务并轮询到终态，会产生实际积分消耗。执行前确认 Key 能访问 bytedance/seedance-2.0-mini 且积分充足。

bash · curl · jq

#!/usr/bin/env bash
set -euo pipefail

: "${TOKENBOX_API_KEY:?Set TOKENBOX_API_KEY first}"
BASE_URL="https://tokenbox.me"
MODEL="bytedance/seedance-2.0-mini"
IDEMPOTENCY_KEY="$(uuidgen)"

curl -fsS "$BASE_URL/v1/models/$MODEL" \
  -H "Authorization: Bearer $TOKENBOX_API_KEY" >/dev/null

CREATE_RESPONSE="$(curl -fsS "$BASE_URL/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $TOKENBOX_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "content": [{"type": "text", "text": "雨后的杭州西湖，电影感航拍镜头"}],
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "generate_audio": false,
    "watermark": false
  }')"

TASK_ID="$(printf '%s' "$CREATE_RESPONSE" | jq -er '.id')"
printf 'task_id=%s\n' "$TASK_ID"

while true; do
  TASK="$(curl -fsS "$BASE_URL/api/v3/contents/generations/tasks/$TASK_ID" \
    -H "Authorization: Bearer $TOKENBOX_API_KEY")"
  STATUS="$(printf '%s' "$TASK" | jq -r '.status')"
  printf 'status=%s\n' "$STATUS"

  case "$STATUS" in
    succeeded)
      printf '%s\n' "$TASK" | jq '{id,status,content,usage}'
      break
      ;;
    failed|cancelled|expired)
      printf '%s\n' "$TASK" | jq '{id,status,error}'
      exit 1
      ;;
  esac
  sleep 15
done

不要修改轮询中的 Idempotency-Key，也不要在超时后用新 Key 重复创建同一业务任务。