視頻與素材
建立影片
啟動影片生成任務
概覽
影片生成是非同步的。成功的建立請求會回傳一個任務 id(與 task_id 的值相同)以及一個 poll_url。請使用該 ID 呼叫 GET /v1/tasks/{id},直到 status 變為 completed 或 failed,然後讀取 video_url。請參閱 取得影片狀態。
- 結果檔案會保存 30 天。若需更長時間保存,請下載該檔案;請參閱 資料保留。
- 已排隊的 Seedance 任務可以使用 取消任務 來取消。
- 費用會在任務被接受時預扣,並在任務完成或失敗時結算。請參閱 帳單與定價。
- 發送
Idempotency-Key標頭,以便在逾時後安全地重試建立請求。
每個模型都接受其專屬的操作與欄位。GET /v1/models/{model}(取得模型)會列出每個操作所接受的欄位、解析度、持續時間與長寬比。若欄位或值不在該列表中,將會回傳 400 並列出可接受的值。請自行設定 duration、resolution、aspect_ratio 與 output_audio:若省略其中一項,TokenLab 將會使用該操作的模型預設值;若無匹配的預設值,請求將回傳 400 並指出需要設定的欄位。
音訊與媒體輸入
音訊行為取決於所選的模型與操作。即使未顯示音訊選擇器,影片仍可能包含聲音。省略選擇器與發送 false 是不同的。
veo3.1、veo3.1-fast和veo3.1-lite一律會生成音訊。請省略output_audio或發送true;發送false將會被拒絕。wan-2.6和wan-2.7一律包含音訊。請省略output_audio或發送true。wan-3.0和wan-3.0-prime同樣一律包含音訊,且不接受任何音訊選擇器。hailuo-h3會生成原生音訊且沒有靜音開關。請勿發送模型詳細資訊中未列出的音訊選擇器。viduq3-pro和viduq3-turbo預設會生成音訊;若要輸出靜音,請發送output_audio: false(或audio: false)。Seedance 和 PixVerse 模型接受output_audio;請明確發送該參數,而非依賴預設值。僅在列出該參數的操作中使用它。audio_url/audio_urls用於提供輸入或參考音訊。它們並非音訊輸出開關。影片編輯、動作遷移和風格遷移可能會保留輸入音軌;保留來源音訊並不代表將其靜音。
請檢查模型詳細資訊以獲取允許的值以及與音訊相關的價格。若模型列出了這些別名,則 outputAudio、generate_audio 和布林值 audio 在組合使用時必須與 output_audio 一致。請勿假設同一模型系列中的每個版本或操作都共享相同的音訊控制項。
請使用可公開存取的 https URL 來提供圖片、影片與音訊,並確保它們在任務開始前保持有效。媒體 URL 最長可達 8,192 個字元。部分模型也接受內嵌的 data: 圖片 URL(每個欄位最多 2,000,000 個字元);對於大型檔案,使用 URL 會更可靠。請勿在同一個請求中混用內嵌 base64 與遠端 URL。
請求主體
veo3.1影片模型 ID。請使用 列出模型 (recommended_for=video) 來列出目前的影片模型,然後明確指定模型。
PixVerse
- 模型:
pixverse-c1,pixverse-v6,pixverse-v5.6 - 操作:
text-to-video,image-to-video,start-end-to-video,reference-to-video - 音訊選擇器:
output_audio, 預設為false
在 TokenLab 上,上述 PixVerse 模型不接受 operation=video-extension。
HappyHorse
- 模型:
happyhorse-1.0 - 操作:
text-to-video,image-to-video,reference-to-video,video-to-video - 音訊選擇器: 請勿傳送
output_audio
影片的文字描述,最多 10,000 個字元。大多數操作都需要此欄位;模型詳細資訊會說明哪些操作不需要。
生成模式:text-to-video、image-to-video、reference-to-video、start-end-to-video、video-to-video、video-extension 或 motion-control。每個模型僅支援其中部分模式;若使用不支援的模式,將會回傳 400 unsupported_operation。若省略此參數,TokenLab 將根據輸入內容進行推斷:若 task_id 包含 extend_at 或 extend_times,則為 video-extension;若包含參考圖像或素材,則為 reference-to-video;若包含 end_image,則為 start-end-to-video;若包含影片輸入,則為 video-to-video;若包含圖像輸入(image、image_url、image_urls 或 start_image),則為 image-to-video;其餘情況則預設為 text-to-video。建議明確指定此參數,以便在欄位不匹配時能儘早觸發錯誤。
第一幀圖片的可公開存取 URL。Seedance 2.0 模型也接受 asset://asset-YYYYMMDDHHMMSS-xxxxx,以使用 ACTIVE 的 TokenLab 素材作為第一幀。建議優先使用 https URL 以獲得最廣泛的模型支援。
作為資料 URL 的內嵌圖片(例如 data:image/jpeg;base64,...)。僅部分模型接受此格式;image_url 的適用範圍更廣。
針對列出此欄位的模型所使用的圖片 URL。請參閱 reference_images 以了解數量限制。
reference-to-video 的參考圖片,以 https URL 或資料 URL 形式提供。數量限制取決於模型:
seedance-2.0、seedance-2.0-fast與seedance-2.0-mini:總共最多 9 張參考圖片(包含素材資產)。超過此數量會回傳400 too_many_seedance_reference_images。seedance-2.5:image_urls與reference_images合計最多 30 張圖片輸入。grok-imagine-video:最多 7 張,且duration上限為 10 秒。grok-imagine-video-1.5與grok-imagine-video-1.5-preview不接受參考圖片。- 其他模型:請參閱模型詳細資訊。超過限制的請求會回傳
400 too_many_items。
Seedance 2.0 模型也接受 asset://asset-YYYYMMDDHHMMSS-xxxxx 作為 ACTIVE 的 TokenLab 素材。關於模型選擇、4K 邊界與 Mini 注意事項,請參閱 Seedance 2.0 影片模型指南。對於 grok-imagine-video,請勿將參考圖片與 image_url 或 image 混用。
第一幀圖像。若同時提供 end_image,請求將被視為 start-end-to-video。若未提供 end_image,則為 image-to-video,且 start_image 的運作方式與合約中列出該參數之模型上的 image 相同。接受公開 URL 或資料 URL;Seedance 2.0 模型亦接受 asset://asset-YYYYMMDDHHMMSS-xxxxx。
start-end-to-video 的最後一幀圖片。接受與 start_image 相同的輸入。
由 建立素材資產 回傳的 TokenLab Seedance 素材資產 ID。僅 Seedance 2.0 模型接受;其他模型會回傳 400 unsupported_seedance_material_asset_model。該資產必須為 ACTIVE 且屬於您的帳戶。此欄位為通用參考輸入;若要明確指定為第一幀、最後一幀或參考圖片,請改為在 start_image、end_image 或 reference_images 中放入 asset://<material_asset_id>。
最多 9 個 TokenLab Seedance 素材資產 ID。它們會計入 Seedance 2.0 模型的 9 張圖片參考限制中。
一般的圖片 URL 會被視為圖片輸入;它們不會建立可重複使用的素材資產。請透過素材 API 建立可重複使用的資產,然後使用其 TokenLab ID 或 asset://asset-YYYYMMDDHHMMSS-xxxxx URI。若明確指定的素材回傳 409 seedance_material_preparing,請檢查回傳的 inactive_asset_ids,並在這些素材變為 ACTIVE 後重試。
來源影片的可公開存取 URL,適用於支援此欄位的模型中需要影片輸入的操作:video-to-video、video-extension 與 motion-control。
針對列出此欄位的模型所使用的來源或參考影片。seedance-2.5 在 video_url 與 video_urls 中合計最多接受 10 個影片輸入。其他模型請參閱模型詳細資訊。
針對列出此欄位的模型,用於音訊參考或音訊驅動操作的公開音訊 URL。這是一個輸入欄位,而非音訊輸出開關。
針對列出此欄位的模型所使用的參考音訊。seedance-2.5 在 audio_url 與 audio_urls 中合計最多接受 10 個音訊輸入,並允許在沒有提示詞 (prompt) 的情況下發送包含音訊參考的請求。對於 seedance-2.5,參考音訊加上參考影片的總長度最多為 30 秒。
工作區中先前任務的 ID,適用於列出此欄位的模型中的 video-extension 操作。若任務不屬於您的工作區,將回傳 403 task_not_owned。
video-extension 開始的來源影片秒數。grok-imagine-video 必須填寫。
在 video-extension 中增加的秒數,適用於列出此欄位的模型。grok-imagine-video 接受 6 或 10。
輸出持續時間(秒)。允許的值取決於模型與操作;其他值會回傳 400 invalid_duration。Seedance 模型也接受 -1,讓模型在其範圍內自行選擇;費用將在任務完成前進行保守估算。部分操作不接受持續時間,例如 motion-control 與 grok-imagine-video 的 video-to-video。
duration 的相容性別名。若兩者皆發送,其值必須相同。
長寬比,例如 16:9、9:16、1:1、4:3、3:4、21:9 或 adaptive (Seedance)。允許的值取決於模型與操作;其他值會回傳 400 invalid_aspect_ratio。
輸出解析度,例如 480p、720p、1080p 或 4k。允許的值取決於模型與操作,部分模型也使用 360p、540p 或 768p。其他值會回傳 400 invalid_resolution。
針對列出此欄位的操作所使用的音訊輸出選擇器。省略時將遵循模型預設值;false 僅在模型允許的情況下請求靜音輸出。請參閱上方的音訊注意事項與所選模型的詳細資訊。
容器格式,mp4 或 mov,適用於列出此欄位的模型(如 seedance-2.5)。若模型未列出此欄位,請省略。
同時將最後生成的幀作為 last_frame_url 回傳。僅限 Seedance 模型。
浮水印開關,適用於列出此欄位的模型(Seedance 模型)。
在生成影片中要避免的內容,最多 5,000 個字元,適用於列出此欄位的模型。
用於可重現生成的種子 (seed),適用於列出此欄位的模型。Seedance 2.0 模型接受 -1 作為隨機種子;seedance-2.5 不接受此欄位。
每秒幀數 (1-120),適用於列出此欄位的模型。
幀數,適用於列出此欄位的模型。Seedance 模型不接受此欄位。
任務在佇列中等待過期的秒數 (3600 到 259200),適用於 Seedance 模型。
任務優先級,從 0 到 9,適用於 Seedance 模型。請勿與 service_tier=flex 混用。
default 在 Seedance 2.0 與 2.5 模型上被視為相容的無操作 (no-op)。flex 在這些模型上會被拒絕。
終端使用者安全識別碼(最多 128 個字元),適用於 Seedance 模型。若省略,TokenLab 會在提供時使用 user。
模型在生成時可能使用的工具,適用於 Seedance 2.0 與 2.5 模型。支援的工具為 {"type": "web_search"}。
終端使用者的唯一識別碼。對於 Seedance 模型,當省略 safety_identifier 欄位時,TokenLab 也會將其用作安全識別碼。
相容欄位名稱
- 主要欄位使用 snake_case:
aspect_ratio、output_audio與reference_images。 - 為保持相容性,TokenLab 也接受
ratio、generate_audio、outputAudio、seconds與referenceImages。 - 若同時發送主要欄位及其別名,其值必須一致。不一致將回傳
400並附帶conflicting_audio_selector、conflicting_duration或conflicting_aspect_ratio。
Seedance 參數
Seedance 模型 (seedance-2.0、seedance-2.0-fast、seedance-2.0-mini 與 seedance-2.5) 接受上述 TokenLab 欄位名稱以及別名 seconds、ratio 與 generate_audio。版本間的差異如下:
| Seedance 2.0 模型 | seedance-2.5 | |
|---|---|---|
| 解析度 | seedance-2.0: 480p, 720p, 1080p, 4k. seedance-2.0-fast 與 seedance-2.0-mini: 480p, 720p | 480p, 720p |
| 持續時間 | -1, 4 到 15 秒 | -1, 4 到 30 秒 |
| 長寬比 | 1:1, 3:4, 4:3, 9:16, 16:9, 21:9, adaptive | text-to-video 與 reference-to-video 相同。image-to-video、start-end、影片編輯與擴充需要 adaptive;影片編輯還需要 duration=-1 |
| 輸出格式 | mp4 | mp4 或 mov |
seed | 接受 | 不接受 |
| 參考輸入 | 9 張圖片參考(包含素材,素材僅在這些模型上接受) | 合計 30 張圖片、10 個影片與 10 個音訊檔案 |
模型詳細資訊是這些數值的最新來源。請明確發送 duration、resolution、aspect_ratio 與 output_audio,而非依賴預設值;模型的 recommended_request 顯示了典型的請求範例。
duration=-1 或 seconds=-1 允許 Seedance 在模型範圍內選擇輸出持續時間。TokenLab 會在任務完成前進行保守的費用估算,並在任務完成後根據實際使用量進行結算。service_tier=flex 與 frames 在這些模型上會被拒絕。
Seedance 範例
curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5",
"prompt": "A sleek product reveal with cinematic camera movement",
"operation": "text-to-video",
"duration": -1,
"aspect_ratio": "adaptive",
"resolution": "720p",
"output_audio": true
}'回應
描述結果、錯誤、時間戳記與模型的欄位會在任務可用時回傳。
任務 ID。與 task_id 相同。
用於 GET /v1/tasks/{id} 輪詢的任務 ID。
此任務的狀態 URL,即 /v1/tasks/{id}。請使用您的 API 金鑰呼叫它。
任務狀態:pending、processing、completed、failed。新任務通常為 pending。
任務建立時的 Unix 時間戳記。
所使用的模型。
結算已完成時的帳單交易 ID。它與任務 ID 是分開的。
影片 URL,僅在建立回應已包含結果時出現。通常您應從狀態回應中讀取它。
任務失敗時的錯誤訊息或結構化錯誤物件。
錯誤
| 狀態與代碼 | 含義 |
|---|---|
400 invalid_request | 欄位格式錯誤、超出範圍或缺失。error.param 會指出該欄位。例如「Set aspect_ratio explicitly」的訊息表示該省略的欄位在此請求中沒有預設值。 |
400 unsupported_operation, unsupported_parameter, invalid_resolution, invalid_duration, invalid_aspect_ratio, invalid_parameter_value, too_many_items, prompt_too_long | 請求與模型針對該操作所接受的內容不符。錯誤通常會列出可接受的值。 |
400 invalid_parameter | 輸入內容不符合操作,例如在 text-to-video 中發送了圖片。 |
400 conflicting_audio_selector, conflicting_duration, conflicting_aspect_ratio | 別名與其主要欄位不一致。 |
400 unpriceable_selection | 所選組合沒有價格。請更改 resolution、duration、aspect_ratio 或音訊設定。 |
400 too_many_seedance_reference_images, unsupported_seedance_material_asset_model | Seedance 2.0 模型的圖片參考過多,或將素材發送給了其他模型。 |
402 | 餘額不足。 |
403 task_not_owned | task_id 屬於另一個工作區。 |
409 seedance_material_preparing, seedance_material_route_unavailable | 素材尚未 ACTIVE,或所選模型無法使用提供的素材。 |
429 | 超出速率限制。請參閱 速率限制。 |
請求
curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "veo3.1",
"prompt": "A cat walking through a garden, cinematic lighting",
"operation": "text-to-video",
"duration": 4,
"resolution": "720p",
"aspect_ratio": "16:9"
}'回應
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"model": "veo3.1",
"created": 1706000000
}圖片轉影片 (Image to Video)
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "hailuo-2.3",
"prompt": "The scene begins from the provided image and adds gentle natural motion.",
"operation": "image-to-video",
"image_url": "https://example.com/image.jpg",
"duration": 6,
"resolution": "768p"
}
)參考轉影片 (Reference to Video)
當模型支援專用的參考條件設定時,請使用 operation=reference-to-video。圖片參考請放入 reference_images;接受參考影片與音訊的模型請使用 video_urls 與 audio_urls。duration 僅設定生成的輸出長度,不會限制參考影片輸入的長度。請參閱上方的 reference_images 以了解每個模型的數量限制。
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "veo3.1",
"prompt": "Keep the same subject identity, palette, and framing while adding subtle natural motion.",
"operation": "reference-to-video",
"reference_images": [
"https://example.com/ref-a.jpg",
"https://example.com/ref-b.jpg"
],
"duration": 8,
"resolution": "720p",
"aspect_ratio": "9:16"
}
)關鍵幀控制 (Keyframe Control)
使用 start_image 與 end_image 來控制第一幀與最後一幀:
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "viduq2-pro",
"operation": "start-end-to-video",
"start_image": "https://example.com/day.jpg",
"end_image": "https://example.com/night.jpg",
"duration": 5,
"resolution": "720p"
}
)影片轉影片 (Video to Video)
當模型接受現有影片作為主要輸入時,請使用 operation=video-to-video。對於 grok-imagine-video,請在 video_url 中發送公開的 HTTPS .mp4 URL 以及編輯 prompt,並省略 resolution、duration 與 aspect_ratio。
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "grok-imagine-video",
"operation": "video-to-video",
"video_url": "https://example.com/source.mp4",
"prompt": "Enhance the clip while preserving the original motion."
}
)影片擴充 (Video Extension)
使用 operation=video-extension 來延續先前的結果。發送您工作區中某個任務的 task_id 與 prompt;其他欄位取決於模型。grok-imagine-video 還需要 extend_at,並接受 6 或 10 的 extend_times。veo3.1 與 veo3.1-fast 接受 task_id 與 prompt。Seedance 模型針對此操作列出了 video_url、video_urls 與 task_id。
動作控制 (Motion Control)
當模型同時需要主體圖片與動作參考影片時,請使用 operation=motion-control。發送 image_url 與 video_url;resolution 為必填。
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "kling-3.0-motion-control",
"operation": "motion-control",
"prompt": "Keep the subject identity stable while following the motion reference.",
"image_url": "https://example.com/subject.png",
"video_url": "https://example.com/motion.mp4",
"resolution": "720p"
}
)模型探索 (Model Discovery)
公開的影片庫與支援的操作會隨時間變更。在建立模型專屬流程之前,請使用 模型 API 來檢查目前的支援情況:
curl "https://api.tokenlab.sh/v1/models?recommended_for=video"
curl "https://api.tokenlab.sh/v1/models/veo3.1"在依賴模型專屬操作或欄位之前,請閱讀模型詳細資訊回應。諸如 video-extension 與 motion-control 等操作是模型專屬的;請確認目前的可用性,而非依賴本頁面中的靜態範例。
授權
BearerAuth API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。
位置: header
請求標頭
單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。
可選值
- "auto"
- "verified"
- "official"
選填鍵值,使建立請求可安全重試。請為每個任務發送一個新的唯一值(例如 UUID)。使用相同鍵值與相同主體的重試會回傳原始建立請求的結果(通常是原始任務),且不會建立、分發或扣款第二次任務。若使用已接受的鍵值但主體不同,則會回傳 409 錯誤。超過 255 個字元的鍵值將被忽略,該請求將不具備冪等性保護。請參閱 安全地使用冪等鍵進行重試。
1 <= length <= 255請求主體
application/json
回應
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json