影片整合指南

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 秒的點數（換模型時用這張表自行估算）：