媒体指南

从火山迁移 Seedance

保留火山请求格式,把 Seedance 切换到 TokenLab

已有火山 Seedance 应用可以继续使用原来的 REST 路径、content[] 请求体、响应字段、回调和 PascalCase 素材 Action。只需更换 API 主机,并把 AK/SK 签名换成 TokenLab API 密钥。

需要修改的内容

变更项现有火山客户端TokenLab
基础 URL你的火山端点https://api.tokenlab.sh/
鉴权AK/SK 请求签名Authorization: Bearer <TOKENLAB_API_KEY>
任务传输官方 /api/v3/contents/generations/tasks REST 路径保持不变
素材/验证 ActionAction 和 Version 查询参数保持不变
任务请求体火山风格的 content[]保持不变
素材请求体GroupId、ProjectName 等 PascalCase 字段保持不变
异步结果火山引擎任务生命周期TokenLab cgt-... 任务 ID,支持轮询和可选回调

只带 AK/SK 签名的请求会返回 401 AuthenticationError。所有 TokenLab 请求都必须包含 Authorization: Bearer <TOKENLAB_API_KEY>。

选择接口

现有客户端TokenLab 接口
火山 REST 任务客户端/api/v3/contents/generations/tasks 及其任务路径
素材或验证 Action 客户端POST /?Action=...&Version=2024-01-01 或 POST /api/v3?Action=...&Version=2024-01-01

视频任务请保持原有的 REST 方法、路径和 JSON 请求体。素材和验证请求继续使用 Action 和 Version 查询参数。Action 端点也接受任务类 Action:CreateContentsGenerationsTasks、GetContentsGenerationsTask、ListContentsGenerationsTasks 和 DeleteContentsGenerationsTasks;新接入请使用 REST 路径。

官方任务路径

方法与路径用途
POST /api/v3/contents/generations/tasks创建视频任务
GET /api/v3/contents/generations/tasks/{id}查询单个任务
GET /api/v3/contents/generations/tasks列出任务
DELETE /api/v3/contents/generations/tasks/{id}取消仍在排队的任务;已开始的任务返回 409 task_not_cancellable

REST 客户端可以参考以下对应页面:

请求体规则

  • content[] 支持 text、image_url、video_url、audio_url 和 draft_task 项。
  • 对 image_url,图生视频时省略 role 或使用 first_frame。last_frame 需与首帧一起使用;参考图生视频使用 reference_image。
  • 所选 Seedance 工作流接受对应媒体角色时,可以使用 asset://asset-YYYYMMDDHHMMSS-xxxxx 这类公开素材 URI。
  • REST 请求体只接受官方字段,包括 model、content、ratio、duration、resolution、generate_audio、watermark、return_last_frame、seed、execution_expires_after 和 safety_identifier。默认值因模型而异:generate_audio 在 seedance-2.0 系列为 false,在 seedance-2.5 为 true;duration 在 seedance-2.0 系列为 5,在 seedance-2.5 为 -1。这种 REST 格式的 resolution 接受 480p、720p 和 1080p(seedance-2.5 只有 480p 和 720p),不接受 4k;4k 只有统一的 /v1/videos/generations 接口支持。seedance-2.5 会拒绝 seed、frames 和 camera_fixed。
  • callback_url 接受公网 HTTP(S) 端点。TokenLab 会在 queued、running、succeeded、failed 和 expired 时发送与查询任务相同的请求体;只有 succeeded 和 failed 采用官方行为:五秒超时,你的端点没有确认时会重试。

最小 REST 示例

curl 'https://api.tokenlab.sh/api/v3/contents/generations/tasks' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Idempotency-Key: $CLIENT_JOB_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "content": [
      {"type":"text","text":"A cinematic product reveal"},
      {"type":"image_url","role":"reference_image","image_url":{"url":"https://example.com/reference.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }'

保存返回的 cgt-... ID。轮询直到 status 变为 succeeded、failed、cancelled 或 expired;不要把创建响应当作已完成的视频。如果提供了 callback_url,请允许重复收到 succeeded 或 failed 通知,并保留轮询作为恢复手段。

区分 v1 与 v3 类型

不要把 /v1/tasks/{id} 的响应 struct 复用于本接口。统一 v1 API 的状态是 pending、processing、completed、failed;火山兼容 v3 API 的状态是 queued、running、succeeded、failed、cancelled、expired。官方 v3 响应还将 duration 表示为 JSON 字符串,并在非失败任务上省略 error。

为了在创建超时或连接断开后安全恢复,请在 REST 创建请求中添加唯一的 Idempotency-Key。使用同一 key 重试相同请求体会返回原 cgt-... ID;同一 key 配不同请求体返回 409。

素材与真人验证

同一个 Action 入口也支持 10 个素材和素材组操作。请参阅素材 Action(火山兼容)了解其 PascalCase 请求体、筛选、分页、响应信封和 12 小时素材 URL。

真人素材在上传前需要额外两个 Action:

  1. 创建视觉验证会话
  2. 获取视觉验证结果

第二个 Action 会返回已验证的 GroupId。将该 ID 用于 CreateAsset;客户端不能直接创建 LivenessFace 分组。

迁移检查清单

  1. 把 API 主机替换为 https://api.tokenlab.sh。
  2. 把 AK/SK 签名替换为 TokenLab Bearer API 密钥。
  3. 保留官方 REST 任务的方法、路径和请求体大小写;仅素材或验证操作保留 Action 和版本。
  4. 相关的素材和验证请求使用相同的 ProjectName。
  5. 保存这些接口返回的 TokenLab 任务、素材组和素材 ID。
  6. 将生产流量切换过来之前,验证一次创建、轮询、列表和错误响应。

本页内容