/ai/v1/videos 生成影片。已有 /v1/videos 用戶端可參考相容協定範例。
前置條件
- 準備有效的 AIHubMix API Key,透過環境變數
AIHUBMIX_API_KEY讀取。 - 使用新版影片介面前,在主控台開啟非同步任務,並確認帳戶有足夠額度及目標模型的使用權限。
- 素材中的本人同意相關用途,並親自完成網頁上的確認流程。同一素材組僅新增同一人的素材。
- 準備可供模型推理廠商讀取的圖片直連網址,確認連結在素材處理期間持續有效。
- 命令列範例需要 Bash、curl 和 jq。在同一終端機按步驟執行,保留回傳的素材組、確認工作階段、素材和影片任務 ID。
BytePlus 官方真人素材指南涵蓋 Seedance 2.0 和 Seedance 2.5。本頁新版影片主範例使用已完成線上驗證的 AIHubMix 模型 ID
doubao-seedance-2-5-260628;具體版本、參考媒體類型和參數以目前模型 Schema 及帳戶可用能力為準。驗證範圍見本次流程驗證,不要據此推定所有 Seedance 版本均可使用真人素材。
- 建立素材組
name,名稱不能為空,最長 100 個字元。建立成功回傳 HTTP 201,初始狀態為 pending_auth。
素材組公開欄位為 id、object、name、status、created_at、updated_at,其中 object 固定為 asset_group,時間欄位為 Unix 秒。後續以 status=active 判斷素材組已可新增素材。
若建立回應遺失,先查詢清單,避免直接重複建立:
data、has_more、next_after。下一頁傳入 after=上一頁的next_after;limit 預設 20,最大 100。名稱不作為冪等識別值,請結合 ID 和建立時間識別素材組。
- 取得本人確認連結
建立確認工作階段,無需請求主體:
201。公開欄位為 id、object、group_id、status、created_at、expires_at、completed_at;object 固定為 verification_session,時間欄位為 Unix 秒,未完成時 completed_at 為 null。
本人開啟 verification_url,核對頁面顯示的主體與用途,閱讀並確認相關條款,依頁面提示完成操作。BytePlus 官方指南說明此過程需要登入個人 BytePlus 帳戶;頁面需要相機權限時,由本人操作裝置並授權。
官方頁面可能包含素材上傳等步驟,依實際提示完成。本頁接下來的 API 素材建立步驟仍需執行,並取得 AIHubMix 回傳的素材 ID;不要把網頁顯示的其他素材 ID 直接代入 API 範例。
- 查詢確認結果
用戶端可每 10 至 15 秒查詢一次,並設定本機等待上限。該間隔為使用建議。網頁顯示完成或回傳空白頁面時,仍應透過 API 確認工作階段為
verified、素材組為 active,再新增素材。
若重新建立回傳 409 verification_session_active,先查詢已有工作階段和素材組。有效工作階段仍存在、素材組已完成確認,或前次結果仍待確認時,都不應反覆新增。持續未完成時聯絡支援。
- 透過圖片網址建立素材
圖片準備
提供回傳圖片檔案的絕對 HTTP(S) 網址,優先使用 HTTPS。連結應無需登入或附加請求標頭即可讀取;本機路徑、內部網路位址、Base64 和帶帳號密碼的 URL 不適用於素材建立介面。URL 不應包含# 片段。
根據 BytePlus 真人素材指南,圖片建議為清晰正面照,並符合以下素材入庫要求:
上述為官方素材庫要求,影片模型還可能有獨立的參考素材限制。上傳前同時核對目標模型要求;HTTP 建立成功也不表示素材已通過處理。
建立請求
將IMAGE_URL 改為你已獲得本人同意使用的圖片直連網址。範例網域僅作預留位置,不提供真人圖片。
請求主體只接受以上三個欄位。
Idempotency-Key 放在請求標頭,可選,最長 128 位元組,不能有前後空白或控制字元。音訊與影片的檔案限制請查閱上述官方指南,並核對目標模型支援的類型與時長。
首次建立通常回傳 HTTP 201;重用已有素材回傳 200;結果仍待確認、狀態為 reconciling 時回傳 202。一律讀取物件的 status。
素材公開欄位為 id、object、group_id、asset_type、status、client_reference_id、created_at、updated_at、deleted_at。object 固定為 asset;未提供或已刪除的 client_reference_id 不回傳,未刪除時 deleted_at 為 null。時間欄位為 Unix 秒,查詢不回傳原圖片網址,請自行保留業務記錄。
- 等待素材可用
可每 10 至 15 秒查詢一次,並設定本機等待上限。停止本機輪詢不會取消伺服器端操作。
- 使用素材生成影片
影片引用使用 AIHubMix 素材建立回應中的完整 id,格式為 asset://<asset_id>。同一次請求引用的全部素材必須屬於同一素材組、歸目前帳戶所有,且均為 active。素材組也必須保持可用。
引用類型必須與素材建立時的
asset_type 一致。asset:// 用於影片參考欄位,並非供瀏覽器下載的網址。
新版影片協定
先依端點路徑核對目前模型 Schema:duration=4、resolution="480p"、aspect_ratio="3:4"、generate_audio=false。新版直接使用 input_references[].url,其中 ASSET_ID 為前面 AIHubMix 回傳的素材 ID:
duration 表示請求時長;其他允許值以模型 Schema 為準。resolution="480p" 是請求的解析度級別,不保證輸出寬或高固定為 480 像素,實際尺寸以生成檔案為準。首尾影格可使用 frame_images[].image_url.url,同時設定 frame_type,僅在模型支援相應能力時使用。完整參數參閱影片生成。
相容影片協定
已有用戶端使用/v1/videos 時,將引用放在 content 或 extra_body.content,URL 以巢狀結構放在相應媒體物件內。本例選用 extra_body.content:
相容範例保留
doubao-seedance-2-0-260128,依據現有相容介面約定和 BytePlus 官方素材引用說明編寫。本次未實測 Seedance 2.0 影片生成及 /v1/videos 相容建立,不能將新版 Seedance 2.5 的驗證結果直接用於該範例。input_references。同時提供兩處 content 時,extra_body.content 覆寫頂層 content,建議只提供一處。
相容版回傳的 id 應用於 GET /v1/videos/{id} 查詢,完成後透過 GET /v1/videos/{id}/content 下載。不要把相容版 ID 交給 /ai/v1/videos 查詢。詳細說明見相容影片介面。
- 輪詢並下載新版影片
以下 Python 範例僅接續前面的新版建立步驟,讀取環境變數中的 VIDEO_ID,不重新建立任務。需要安裝 requests。
200 不代表生成成功,必須檢查 status。輪詢使用 /ai/v1/videos/{id},統一任務介面 /ai/v1/tasks/{id} 提供唯讀快照。
影片查詢和下載使用建立任務時的同一 API Key。完成後及時下載並自行儲存;結果有保留期限,以 expires_at 為準,過期可能回傳 410 artifact_expired。
本次流程驗證
2026-09-07 的線上驗證使用公開網路 HTTPS JPEG 直連網址、本人完成的網頁確認,以及上述 Seedance 2.5 參數,觀察到以下結果:
本次檔案為 1,558,358 位元組;ffprobe 偵測為 H.264、24 fps、560 × 752 像素、4.041667 秒、無音軌。這些數值為該次生成結果,不代表每次請求都會輸出相同尺寸、時長或檔案大小。
首次開啟確認頁面曾出現
internal error,隨後 API 查詢仍為 pending,頁面錯誤的原因尚未確認。該次測試隨後使用獨立測試組的新頁面,由本人完成操作後確認工作階段為 verified、素材組為 active。新組僅是本次測試的處理方式,不作為反覆重建素材組的通用建議,也不表示原工作階段已結束。
本次未實測 Seedance 2.0 影片生成、相容介面建立、音訊與影片素材、首尾影格、刪除及其他異常組合。相關說明保留介面約定和官方資料依據,本次驗證不涵蓋整篇指南的全部情境。
冪等重試
- 素材建立逾時或回應遺失時,保留原
Idempotency-Key、client_reference_id、URL 和asset_type,重新傳送同一請求。兩個識別值中任一個符合相同帳戶、相同素材組的已有素材時,會重用該素材。 - 相同識別值對應的 URL 或
asset_type發生變化時,回傳409 asset_idempotency_conflict。帶簽章的圖片 URL 更新後也屬於 URL 變化。 - 未提供任一識別值時,不保證跨請求去除重複。只有確認要建立另一份素材時,才使用新識別值。
- 已取得素材 ID 後,優先用
GET /ai/v1/assets/{id}查詢。reconciling不等於失敗,不應改用新識別值再建立。 - 素材刪除完成後,原冪等識別值不再保留。不要依賴它找回已刪除素材,也不要重送舊建立請求。
- 本節冪等約定僅適用於素材建立。素材組、確認工作階段和影片建立不能套用該約定。新版影片建立回應遺失時,先用
GET /ai/v1/videos?limit=20&order=desc尋找原任務,避免重複生成。
刪除素材和素材組
刪除前先確認所有引用該素材的影片均已結束,包括透過相容介面提交的任務。刪除操作無法復原,已下載的影片檔案需自行管理。 刪除單個素材:202 表示刪除仍在處理,透過 GET /ai/v1/assets/{id} 繼續查詢,直到 status=deleted。重複刪除回傳目前狀態;若為 reconciling,繼續確認結果,持續未完成時聯絡支援。
刪除整個素材組會同時刪除組內素材,必須明確傳入 cascade=true:
202,透過 GET /ai/v1/asset-groups/{id} 查詢。deleting 表示處理中,partially_deleted 表示尚未全部刪除,deleted 才表示完成。清單預設不顯示已刪除素材組。
409 asset_group_in_use 表示仍有操作或影片任務未結束。等待並查詢相關狀態後重試。相容影片任務需要自行確認結束,不要依賴刪除請求自動判斷所有相容任務的占用。
常見問題
已完成網頁操作,為什麼還不能新增素材?
先查詢確認工作階段和素材組,以verified 和 active 為準。網頁出現 internal error 時也執行相同檢查;pending 期間不反覆建立同組工作階段。結果尚未確認時稍後再查;持續未完成請提供 ID 聯絡支援,無需提交確認連結或本人照片。
素材可用,為什麼生成影片仍然失敗?
檢查引用是否使用 AIHubMix 回傳的素材 ID,所有素材是否屬於同一組,媒體類型是否相符,以及目前模型是否支援相應輸入。素材active 表示素材可用,影片任務仍需單獨檢查完成狀態和錯誤資訊。
如何處理常見介面錯誤?
其他影片錯誤參閱非同步任務錯誤碼。回報時提供發生時間、HTTP 狀態、
error.code、回傳的 error.tid(如有)及相關資源 ID;不要提供 API Key、確認連結或帶簽章的圖片網址。