视频集成指南

A1　调用流程

1. 1. 提交
2. 2. 保存 taskId
3. 3. 查状态
4. 4. 获取文件
5. 5. 自存

1. 提交 POST /v1/media/video：受理即返回 HTTP 200、status "pending"、taskId，以及这次预扣的 quotaCost。
2. 立刻把 taskId 与 quotaCost 写进你自己的数据库——没有 webhook、取消、幂等键，也没有列出任务的 API，taskId 是追踪这笔任务的唯一凭证。
3. 用 POST /v1/media/task/status 带 taskId 查询，直到 status 变成 succeeded、failed 或 delivery_failed。
4. 成功后照状态响应里的 delivery 描述子（method 与 path），用同一个 Authorization 下载成品。
5. 下载后自行检查文件的实际宽高、fps 与音轨；提交响应的 size 只是请求回显，不代表成品尺寸。

图片端点 POST /v1/media/image 有两种响应：异步模型返回 202 与 taskId（流程同上）；同步模型（例如 Seedream 5.0）直接返回 200 与图片网址，该网址只保存 1 小时，请立即下载。

手册原文：请保存好：没有 webhook、取消、幂等键或任务列表端点，视频也没有 seed。如果提交请求本身超时、没拿到 taskId，API 无法确认任务是否已创建；重新提交前请先联系客服。

A2　查状态的间隔与速率限制

• 每个任务每 5 秒以上查一次即可；生成时间依模型、分辨率与秒数而异。
• 查状态、Seedance 获取文件与批量查询共用「每个来源 IP 每分钟 200 次」的限制（响应标头 x-ratelimit-limit）；提交端点不计入。
• 换算：每 5 秒查一次＝每任务每分钟 12 次，同一个 IP 最多约 16 个任务同时轮询。任务更多时，请拉长间隔，或用队列轮流查询，不要并行狂查。
• Starter 方案另有每日上限。

手册原文：请每 5 秒或更久轮询一次。状态、Seedance 成品与批量状态查询共用每个客户端 IP 每分钟 200 次的全局限制（x-ratelimit-limit）；媒体提交不计入此限制，Starter 方案另有每日上限。

A3　错误处理对照表

原则：拿到 taskId 之后，任何暂时错误都用同一个 taskId 继续查，不要重送生成。各模型的失败与点数处理细节不同，以手册中该模型说明的「失败」段为准。

A4　点数的预扣与结算

• 受理时先预扣点数；视频提交响应的 quotaCost 就是这次预扣的点数。任务到终局才结算：成功时扣除，失败时依该模型说明处理；查状态时的 pending 不会结算。
• 部分情况（例如派送结果不确定、退款本身失败）点数会保留待核对，不能只凭某个错误码就判断已退还。批量作业请记录每个 taskId 的 quotaCost 与最终状态，方便对账。
• 异步图片的 202 响应与状态响应不带 quotaCost，点数以目录为准。
• Seedance 的来源视频请求可先带 quoteOnly=true 取得精确报价，不扣点、不创建任务。

A5　获取文件与保存

• 保存期限只在有写明的地方承诺：Seedance 成品 30 天、私有图片 7 天、同步图片网址 1 小时（服务器重启也会消失）。其他成品的保存期限未承诺，请取得后立即下载自存。
• 把「下载完成」当成任务的最后一步：状态一变 succeeded 就下载并存到自己的保存空间，存好才把任务标记完成。
• 以下载响应的 Content-Type 判断格式，不要假设；Seedance 实测为 MP4（H.264 视频＋AAC 音轨）。
• Seedance 获取文件与 /v1/media/delivery/rmw 支持单一 Range，可用来续传大型文件。

手册原文：请依返回的交付描述获取文件。provider 中继使用 POST /v1/media/delivery/video 或 /rmw；持久保存的 Seedance 成品使用需验证的 GET /v1/media/artifact/:taskId。Seedance 的状态响应也以这个 GET 路径作为交付描述，所以每个模型都可以直接照描述获取文件。视频下载带 video/* 的 Content-Type（Seedance 实测为 video/mp4，H.264 视频＋AAC 音轨）；请读取 Content-Type，不要自行假设格式。只有明文写出的才有保存承诺：Seedance 成品 30 天、私有图片成品 P7D（7 天）、同步图片 blob 一小时。其他成品文件都没有保存承诺，上游副本可能过期（410），因此成功后请立即下载并自行保存。

A6　目前不提供的功能

A7　批量端点

• POST /v1/media/video/batch 一次提交多个视频请求（items），可另给共用的 size、duration、model；返回 202 与 batchId、totalItems、quotaCost。
• 用 GET /v1/media/batch/:batchId 查进度：completedItems、failedItems 与每一项的状态。
• 手册目前没有列出 items 每一项可用的字段；需要带起始图、首尾帧、参考图或来源视频的镜头，请改用单笔 POST /v1/media/video 提交，自己控制并行数量。
• 批量端点的 429 也可能代表达到批量上限。

B0　流程总览

1. 1. 剧本与分镜
2. 2. 关键帧
3. 3. 镜头视频
4. 4. 试拍与定稿
5. 5. 声音
6. 6. 剪辑成片

B1　剧本与分镜表

• 用 POST /v1/chat/completions 写剧本，并带 "modalities": ["text"]（或标头 X-TokenTable-Modalities: text），避免请求被判断成媒体生成。
• 要固定模型时，先用 GET /v1/models 确认 id 存在：不存在的 id 不会报错，而是改走 auto 智能路由。
• 请模型输出固定格式的 JSON（如下）。每个角色写一段固定的外观描述，之后每次产图都原样粘贴，这是角色一致的基础。

{
  "characters": [
    {
      "id": "A",
      "look": "二十多岁女性，黑色短发，红色风衣，左耳银色耳环"
    }
  ],
  "shots": [
    {
      "shot": 1,
      "seconds": 5,
      "characters": [
        "A"
      ],
      "camera": "缓慢推近",
      "line": "（台词）",
      "startFrame": "（起始画面描述）",
      "endFrame": "（结束画面描述＝下一镜的起始画面）"
    }
  ]
}

B2　关键帧

• 用 POST /v1/media/image 产生每一镜的起始画面；20 镜用首尾帧接镜时需要 21 张（下一镜的起始画面同时是这一镜的结束画面）。
• 目前图片端点的模型都只吃文字、不能带参考图，角色一致只能靠固定的外观描述。
• 直式 9:16 请带 size=1080*1920，搭配：qwen-image-3.0、wan2.7-image、kling/kling-v3-omni-image-generation（Kling 会转成最接近的比例，实际像素由上游决定）。
• volcengine/doubao-seedream-5.0-flash、volcengine/doubao-seedream-5.0-pro 不提供比例参数、比例由模型决定，适合做角色设置图（给 R2V 当参考图），不适合需要固定比例的关键帧。
• 存盘时扩展名要和实际格式一致（例如 JPEG 存成 .jpg），否则上传到视频端点会返回 415。

B3　镜头视频

• 首尾帧接镜（I2V_LAST）：第 N 镜以关键帧 N 为 image、关键帧 N+1 为 lastImage，镜头会自然接到下一镜的开头。支持的模型：volcengine/doubao-seedance-2.5、volcengine/doubao-seedance-2.0、volcengine/doubao-seedance-2.0-fast、volcengine/doubao-seedance-2.0-mini、bytedance/seedance-2.5-spicy、bytedance/seedance-2.0-spicy、bytedance/seedance-2.0-fast-spicy、bytedance/seedance-2.0-mini-spicy、w3.0-video（高级）、w3.0-video-pro（高级）。
• 两张关键帧请用相同比例：Seedance 以起始帧比例为准，结束帧会被居中裁剪。Seedance 的 I2V_LAST 点数与同分辨率、同秒数的 T2V 相同。
• 锁定角色外观（R2V）：重复 referenceImage 字段上传角色参考图，在提示词以「第一张参考图」等方式指称（效果不保证）。支持的模型：volcengine/doubao-seedance-2.5、volcengine/doubao-seedance-2.0、volcengine/doubao-seedance-2.0-fast、volcengine/doubao-seedance-2.0-mini、bytedance/seedance-2.5-spicy、bytedance/seedance-2.0-spicy、bytedance/seedance-2.0-fast-spicy、bytedance/seedance-2.0-mini-spicy、w3.0-video（高级）、w3.0-video-pro（高级）。
• 直式短剧注意：Seedance 的 T2V 与 R2V 输出固定 16:9；要直式成品，请用 9:16 的起始图（I2V 或 I2V_LAST），Seedance 会跟随起始图比例。
• 图片以 multipart/form-data 上传（image、lastImage、referenceImage），不支持图片网址。

B4　试拍与定稿

• 先用低分辨率确认构图与动作，满意后再用同一组素材以高分辨率重送；例如 volcengine/doubao-seedance-2.0-mini 480p 5 秒为 13 点。
• 文生视频可用 volcengine/doubao-seedance-2.5 的草稿→定稿：draft=true 以 480p 价格产生草稿，满意后以 draftTaskId 产生 1080p 定稿（沿用草稿的提示词与秒数；每份草稿只能定稿一次，七天内有效；草稿不能带图片或视频）。
• 视频没有 seed，同一提示词每次结果都不同；满意的镜头请立刻下载保存。

B5　声音

• volcengine/doubao-seedance-2.5、volcengine/doubao-seedance-2.0、volcengine/doubao-seedance-2.0-fast、volcengine/doubao-seedance-2.0-mini、wan2.6-t2v、happyhorse-1.1-t2v、w3.0-video（高级）、w3.0-video-pro（高级） 的成品含音轨，无法关闭或指定；其他模型的音轨情况见各模型说明。需要干净画面时，请在后期去除原音轨（见 B6）。
• 旁白与配音用 POST /v1/media/audio，同步返回音频文件网址；音频文件保存期限未承诺，请立即下载。
• text：每次最多 2000 字符；超过会返回 400 text_too_long，请自行分段。
• voice：longxiaochun_v2（默认）、longcheng_v2、longhua_v2 或 longshu_v2；其他值或未填都会改用默认值，不会报错。

B6　剪辑成片

TokenTable 不做剪辑合成；下载后用剪辑软件或 ffmpeg 串接、混音、上字幕。以下是常用的 ffmpeg 指令：

# 1) 去除原音轨
ffmpeg -i shot01.mp4 -an -c:v copy shot01_silent.mp4
# 2) 串接（所有镜头编码、分辨率、fps 相同时）
printf "file 'shot01.mp4'\nfile 'shot02.mp4'\n" > list.txt
ffmpeg -f concat -safe 0 -i list.txt -c copy episode.mp4
# 3) 换上旁白
ffmpeg -i episode.mp4 -i narration.mp3 -map 0:v -map 1:a -c:v copy -c:a aac -shortest episode_vo.mp4

混用不同模型或分辨率的镜头时，串接前先统一分辨率与 fps（重新编码），直接用 -c copy 会失败。

B7　成本估算

以下为「20 镜 × 5 秒＋21 张关键帧」的估算，由目录点数实时计算；另计试拍、重试、配音与文字用量。

各视频模型每镜 5 秒的点数（换模型时用这张表自行估算）：