TokenLab

視頻與素材

建立任務 (Volc 相容)

使用 Volc 相容 API 建立 Seedance 任務。

POST
/api/v3/contents/generations/tasks

概覽

現有的 Volc 風格 Seedance 客戶端可以透過更改 API 位址和金鑰來使用 TokenLab。

這些範例使用 Seedance 2.0。此端點也支援 Seedance 2.5,並具有以下模型特定的差異。本頁面中可重複使用的 TokenLab 素材 URI 範例適用於 Seedance 2.0。

另請參閱 Seedance 2.0 影片模型 與 影片生成。

驗證與端點

  • 使用 Authorization: Bearer <TOKENLAB_API_KEY>。
  • 不接受 Volc AK/SK 簽章。請求必須包含 TokenLab Bearer 金鑰。
  • 使用官方任務路徑:POST /api/v3/contents/generations/tasks。

內容規則

  • type: "text" 為提示詞文字。
  • type: "image_url" 若無 role,或設定為 role: "first_frame",將被視為首幀。
  • role: "last_frame" 必須與首幀搭配使用。
  • type: "video_url" 需要 role: "reference_video",而 type: "audio_url" 需要 role: "reference_audio"。role: "reference_image" 用於標記參考圖像。
  • 項目限制:Seedance 2.0 最多接受 16 個 content 項目(1 個文字、9 個圖像、3 個影片、3 個音訊、1 個 draft_task)。Seedance 2.5 最多接受 51 個(1 個文字、30 個圖像、10 個影片、10 個音訊、1 個 draft_task)。
  • image_url.url 接受公開圖像 URL 或素材 URI,例如 asset://asset-YYYYMMDDHHMMSS-xxxxx。role 決定該素材是首幀、末幀還是參考圖像。
  • 請勿在同一個請求中混合使用首/末幀輸入與參考媒體。
  • REST 本體僅接受本頁面列出的欄位。任何其他頂層欄位(包括 material_asset_id 和 material_asset_ids)將回傳 400 UnsupportedParameter。請將 TokenLab 素材 URI 放入 image_url.url 中。

參數說明

model 接受 TokenLab 模型 ID,例如 seedance-2.0 或 seedance-2.5。現有客戶端可以繼續發送他們已用於這些模型的 Volcengine 模型 ID。取得任務的回應會回傳您發送的 model 值。無法識別的值會回傳 400 InvalidParameter。

duration 為整數秒數;-1 選擇自動時長。預設值與限制因模型而異:

參數Seedance 2.0Seedance 2.5
duration4–15 / -1 (預設: 5)4–30 / -1 (預設: -1)
resolution480p, 720p, 1080p (預設: 720p)480p, 720p (預設: 720p)
generate_audioboolean (預設: false)boolean (預設: true)
priority不支援integer: 0–9
seedinteger: -1–4294967295 (預設: -1)不支援
execution_expires_after3600–259200 秒 (預設: 172800)3600–259200 秒 (預設: 172800)

對於 Seedance 2.5,首幀、首/末幀、影片擴展及影片轉影片請求需要 ratio: "adaptive";影片轉影片也需要 duration: -1。output_format 僅對 Seedance 2.5 接受 mp4 或 mov。

  • ratio 接受 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 或 adaptive (預設: adaptive)。
  • watermark 和 return_last_frame 為布林值 (預設: false)。safety_identifier 為最多 64 個字元的字串。
  • service_tier 僅接受 default;flex 會回傳 400 UnsupportedParameter。
  • tools 最多接受一個項目:{"type": "web_search"}。
  • draft: true、frames 和 camera_fixed 不受支援。僅 Seedance 2.0 接受 camera_fixed: false。
  • callback_url 可指向最多 2,048 個字元的公開 HTTP(S) 端點。

回調傳遞 (Callback Delivery)

當存在 callback_url 時,TokenLab 會在任務狀態變更時發送 HTTP POST。回調狀態包括 queued、running、succeeded、failed 和 expired。JSON 本體與取得任務的回應相符。

2xx 回應表示傳遞成功。對於 succeeded 和 failed,若傳遞未能在五秒內成功,將重試最多三次。回調僅包含標準 JSON 內容標頭,沒有 TokenLab 特定的傳遞標頭。不支援重新導向,且私人或保留網路目標將被拒絕。

請儲存任務 ID。如果回調未傳遞,您仍然可以使用取得任務端點來檢索結果。

圖像準備

公開的 HTTP(S) 圖像 URL 和支援的資料 URL 將按原樣使用;它們不會自動儲存為可重複使用的素材。明確的 asset://asset-... 參照會使用現有的 TokenLab 素材。TokenLab 會在生成前檢查所有權和就緒狀態。如果參照的素材仍在準備中,請等待其就緒後再重試;當建立失敗時,請檢查 error.code 和 error.message。

對於現有素材,請使用公開的 asset-YYYYMMDDHHMMSS-xxxxx ID,而不是其他系統回傳的原始資產 ID。TokenLab 會在生成前驗證素材所有權。

建立回應

{
  "id": "cgt-20260102030405-a1b2c"
}

建立回應僅包含任務 ID。請儲存它,以便隨時檢索狀態和結果。

防止重複任務

在建立請求時發送唯一的 Idempotency-Key(1–255 個字元,無換行符)。如果連線在回應到達前中斷,請使用相同的 API 金鑰、冪等性金鑰 (idempotency key) 和請求本體進行重試:

  • 如果原始任務已建立,TokenLab 會回傳相同的 cgt-... ID 並加入 Idempotency-Replayed: true。
  • 使用相同的金鑰但不同的本體會回傳 409,錯誤代碼為 idempotency_conflict,且不會建立第二個任務。
  • 超過 255 個字元或包含換行符的金鑰會回傳 400 InvalidParameter。

該金鑰不會改變 JSON 回應的格式。TokenLab 不會從 X-Request-ID 或沒有金鑰的相同請求本體中推斷重複。

範例

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.0",
    "content": [
      {"type": "text", "text": "A cinematic forest at sunset"},
      {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/ref.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p",
    "generate_audio": false,
    "callback_url": "https://example.com/webhooks/seedance"
  }'

對於現有素材,請將每個 URI 放入官方的 content[] 項目中並宣告其角色:

[
  {
    "type": "image_url",
    "role": "first_frame",
    "image_url": {"url": "asset://asset-20260720123458-start"}
  },
  {
    "type": "image_url",
    "role": "last_frame",
    "image_url": {"url": "asset://asset-20260720123459-end01"}
  }
]

錯誤

REST 錯誤使用 {"error": {"code", "message", "param", "type"}}。請求問題會回傳 400 並附帶 InvalidParameter 或 UnsupportedParameter,缺少 Bearer 金鑰則回傳 401 AuthenticationError。來自影片生成的錯誤(例如餘額不足 402 或速率限制 429)將保留其 HTTP 狀態。

相同的操作也可作為 POST /api/v3?Version=2024-01-01 上的 Actions 使用,包括 CreateContentsGenerationsTasks、GetContentsGenerationsTask、ListContentsGenerationsTasks 和 DeleteContentsGenerationsTasks。新的整合應使用上述的 REST 路徑。

下一步

使用回傳的 cgt-... ID 搭配 取得任務 (Volc 相容),直到任務達到終止狀態。

curl -X POST "https://example.com/api/v3/contents/generations/tasks" \  -H "Content-Type: application/json" \  -d '{    "model": "seedance-2.0",    "content": [      {        "type": "text",        "text": "A cinematic forest at sunset"      },      {        "type": "image_url",        "role": "reference_image",        "image_url": {          "url": "https://example.com/ref.png"        }      }    ],    "ratio": "16:9",    "duration": 5,    "resolution": "720p",    "generate_audio": false  }'
{  "id": "string"}

授權

BearerAuth
AuthorizationBearer <token>

API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。

位置: header

請求標頭

X-TokenLab-Delivery-Policy?string

單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。

可選值

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

由用戶端產生的金鑰,用於冪等(idempotent)REST 任務建立,長度為 1-255 個字元且不含換行符號。在相同的 TokenLab API 憑證下,若使用相同的金鑰與 JSON 本體重複請求,將傳回原始的 cgt 任務 ID;若使用不同的本體,將傳回 409 並附帶代碼 idempotency_conflict。金鑰過長或包含換行符號將回傳 400。在逾時或中斷後重試時,請保持憑證、金鑰與請求本體不變。

長度1 <= length <= 255

請求主體

application/json

回應

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json