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

​
支援的操作

在生產中使用明確的 operation。TokenLab 可以從輸入中推斷某些操作，但明確的操作值使得驗證、支持和重試更加清晰。
操作必需或典型輸入使用案例
text-to-videoprompt僅從文本生成
image-to-videoimage_url 或兼容的 image動畫化起始圖像
reference-to-videoreference_images 和可選的 video_urls / audio_urls 在支持的模型上保持身份、風格或資產參考
start-end-to-videostart_image, end_image控制第一幀和最後一幀
video-to-videovideo_url 或模型特定的 task_id轉換或升級現有片段
motion-controlimage_url 加上 video_url將運動參考應用於主題
audio-to-videoaudio_url音頻條件視頻流
video-extensiontask_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-v6text-to-video, image-to-video, start-end-to-video, reference-to-videoprompt; image_url; start_image + end_image; reference_images360p, 540p, 720p, 1080p1 到 15 秒之間的任意整數output_audio, 預設為 false
pixverse-v5.6text-to-video, image-to-video, start-end-to-video, reference-to-video與 C1 和 V6 相同的欄位360p, 540p, 720p, 1080p5、8 或 10 秒；1080p 支援 5 或 8 秒output_audio, 預設為 false
happyhorse-1.0text-to-video, image-to-video, reference-to-video, video-to-videoprompt; image_url; reference_images; video_url + reference_images720p, 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 和異步輪詢，但請求與回應結構不同。