視頻生成

視頻生成是異步的。 POST /v1/videos/generations 返回一個公共任務身份，通常還會返回一個 poll_url；最終視頻會在後續的狀態響應中出現。當所選 Seedance 模型可使用 TokenLab 素材庫時，圖片 URL 和支援的內嵌 data URL 會在生成前自動準備為可重複使用的 TokenLab 素材。如果準備超過 60 秒，請在回傳的 auto_material_asset_ids 變為 ACTIVE 後重試。如果所選模型暫不可使用素材庫，一般圖片輸入仍會走常規圖片路徑。

支援的操作

在生產中使用明確的 operation。TokenLab 可以從輸入中推斷某些操作，但明確的操作值使得驗證、支持和重試更加清晰。

操作	必需或典型輸入	使用案例
`text-to-video`	`prompt`	僅從文本生成
`image-to-video`	`image_url` 或兼容的 `image`	動畫化起始圖像
`reference-to-video`	`reference_images` 和可選的 `video_urls` / `audio_urls` 在支持的模型上	保持身份、風格或資產參考
`start-end-to-video`	`start_image`, `end_image`	控制第一幀和最後一幀
`video-to-video`	`video_url` 或模型特定的 `task_id`	轉換或升級現有片段
`motion-control`	`image_url` 加上 `video_url`	將運動參考應用於主題
`audio-to-video`	`audio_url`	音頻條件視頻流
`video-extension`	`task_id`, `extend_at` 或模型特定的擴展字段	繼續生成的視頻

模型發現

curl "https://api.tokenlab.sh/v1/models?recommended_for=video" \\
  -H "Authorization: Bearer sk-your-api-key"

model 應使用 TokenLab 顯示的模型 ID，再用 operation 和對應媒體輸入選擇操作能力。示例包括 wan-2.7、happyhorse-1.0、viduq3、viduq3-mix、pixverse-v6、kling-3.0-video、veo3.1、seedance-2.0；不要把供應商的操作名稱當成 TokenLab 模型名。在依賴於專用字段如 reference_images、kling_elements、output_audio、duration、resolution 或 aspect_ratio 之前，請閱讀所選模型的詳細信息。

創建請求

curl https://api.tokenlab.sh/v1/videos/generations \\
  -H "Authorization: Bearer sk-your-api-key" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "veo3.1",
    "operation": "text-to-video",
    "prompt": "一隻貓在陽光明媚的花園中漫步的平靜電影鏡頭",
    "duration": 4,
    "aspect_ratio": "16:9"
  }'

對於生產媒體輸入，優先使用公共 https URL，而不是內聯 data: URL。如果使用臨時存取 URL，請確保它在 TokenLab 完成任務建立前保持有效。

輸入和模型特定字段

Veo 3 系列請求默認為音頻開啟，當 output_audio 被省略時。當模型支持切換且您的用戶體驗依賴於聲音時，請明確設置它。
kling_elements 用於 kling-3.0-video 圖像條件請求。在 prompt 中引用每個元素為 @name；不要將其與 output_audio=true 結合使用。
使用 Seedance 2.0 家族的 4K 輸出、Fast/Mini 解析度邊界或多模態參考輸入前，請閱讀 Seedance 2.0 影片模型指南。
對於 grok-imagine-video，video-to-video 使用公共的 .mp4 video_url；模型特定的限制如 duration 和 resolution 必須來自模型說明。

PixVerse 與 HappyHorse

模型	操作	輸入	解析度	時長	音訊選擇器
`pixverse-c1`, `pixverse-v6`	`text-to-video`, `image-to-video`, `start-end-to-video`, `reference-to-video`	`prompt`; `image_url`; `start_image` + `end_image`; `reference_images`	360p, 540p, 720p, 1080p	1 到 15 秒之間的任意整數	`output_audio`, 預設為 `false`
`pixverse-v5.6`	`text-to-video`, `image-to-video`, `start-end-to-video`, `reference-to-video`	與 C1 和 V6 相同的欄位	360p, 540p, 720p, 1080p	5、8 或 10 秒；1080p 支援 5 或 8 秒	`output_audio`, 預設為 `false`
`happyhorse-1.0`	`text-to-video`, `image-to-video`, `reference-to-video`, `video-to-video`	`prompt`; `image_url`; `reference_images`; `video_url` + `reference_images`	720p, 1080p	生成操作為 3 到 15 秒；video-to-video 輸出上限為 15 秒	請勿傳送 `output_audio`

在 TokenLab 上，上述 PixVerse 模型不接受 operation=video-extension。

curl https://api.tokenlab.sh/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pixverse-v6",
    "operation": "image-to-video",
    "prompt": "A slow camera move through a neon-lit street",
    "image_url": "https://example.com/start.jpg",
    "resolution": "1080p",
    "duration": 5,
    "output_audio": true
  }'

輪詢結果

首先使用返回的 poll_url。如果您需要固定端點，請使用 GET /v1/tasks/{id}，並使用來自創建響應的相同 id / task_id。完成的影片任務可能會根據模型和輸出數量返回 video_url、video 或 videos。請將 billing_transaction_id 視為計費識別符，而不是任務識別符。

常見陷阱

不要硬編碼舊的視頻狀態路徑；優先使用 poll_url。
除非模型說明允許，否則不要將第一幀字段與專用的參考圖像流結合使用。
不要假設 duration 描述輸入參考視頻的長度；它通常控制生成的輸出長度。
在超時後不要重試創建請求，而不檢查任務是否已經創建。

API 參考

主題	參考
創建視頻	創建視頻
獲取視頻狀態	獲取視頻狀態
獲取任務狀態	獲取任務狀態
取消任務	取消任務
計費與定價	計費與定價

統一影片 API 與火山相容入口

跨模型影片生成建議使用 /v1/videos/generations。如果你正在遷移既有 Seedance 2.0 整合，且請求已是火山風格 content[] 或 Action 形式，可以使用 /api/v3 下的 Seedance 相容入口。兩種入口都使用 TokenLab Bearer API Key 和非同步輪詢，但請求與回應結構不同。

OpenAI 風格和火山相容影片 API

跨模型影片生成請使用 TokenLab 統一的 /v1/videos/generations。如果你正在遷移已經使用火山風格 content[] 或 Action 請求的 Seedance 2.0 整合，可以使用 /api/v3 下的 Seedance 相容入口。兩種入口都使用 TokenLab Bearer API Key 和異步輪詢，但請求與回應結構不同。

快速入門

核心指南

媒體指南

支援的操作

模型發現

創建請求

輸入和模型特定字段

PixVerse 與 HappyHorse

輪詢結果

常見陷阱

API 參考

統一影片 API 與火山相容入口

OpenAI 風格和火山相容影片 API

​支援的操作

​模型發現

​創建請求

​輸入和模型特定字段

​PixVerse 與 HappyHorse

​輪詢結果

​常見陷阱

​API 參考

​統一影片 API 與火山相容入口

​OpenAI 風格和火山相容影片 API

支援的操作

模型發現

創建請求

輸入和模型特定字段

PixVerse 與 HappyHorse

輪詢結果

常見陷阱

API 參考

統一影片 API 與火山相容入口

OpenAI 風格和火山相容影片 API