Skip to main content
真人素材用於在影片中引用已由本人確認的人物形象。流程為:建立素材組、本人完成網頁確認、新增素材、等待素材可用,再提交影片生成任務。 本頁以圖片素材為例,使用 AIHubMix API 完成素材管理,優先使用新版 /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 版本均可使用真人素材。
準備終端機環境,API Key 應已由你的執行環境注入:

  1. 建立素材組

請求主體只接受 name,名稱不能為空,最長 100 個字元。建立成功回傳 HTTP 201,初始狀態為 pending_auth 素材組公開欄位為 idobjectnamestatuscreated_atupdated_at,其中 object 固定為 asset_group,時間欄位為 Unix 秒。後續以 status=active 判斷素材組已可新增素材。 若建立回應遺失,先查詢清單,避免直接重複建立:
清單回傳 datahas_morenext_after。下一頁傳入 after=上一頁的next_afterlimit 預設 20,最大 100。名稱不作為冪等識別值,請結合 ID 和建立時間識別素材組。

  1. 取得本人確認連結

建立確認工作階段,無需請求主體:
建立成功回傳 HTTP 201。公開欄位為 idobjectgroup_idstatuscreated_atexpires_atcompleted_atobject 固定為 verification_session,時間欄位為 Unix 秒,未完成時 completed_atnull
verification_url 僅在成功建立回應中回傳,後續查詢不會再次回傳連結。及時將連結交給素材中的本人,不要放入公開日誌、程式碼儲存庫或意見回饋截圖。有效期限以 expires_at 為準,過期後不能繼續使用原連結。
本人開啟 verification_url,核對頁面顯示的主體與用途,閱讀並確認相關條款,依頁面提示完成操作。BytePlus 官方指南說明此過程需要登入個人 BytePlus 帳戶;頁面需要相機權限時,由本人操作裝置並授權。 官方頁面可能包含素材上傳等步驟,依實際提示完成。本頁接下來的 API 素材建立步驟仍需執行,並取得 AIHubMix 回傳的素材 ID;不要把網頁顯示的其他素材 ID 直接代入 API 範例。

  1. 查詢確認結果

用戶端可每 10 至 15 秒查詢一次,並設定本機等待上限。該間隔為使用建議。網頁顯示完成或回傳空白頁面時,仍應透過 API 確認工作階段為 verified、素材組為 active,再新增素材。 若重新建立回傳 409 verification_session_active,先查詢已有工作階段和素材組。有效工作階段仍存在、素材組已完成確認,或前次結果仍待確認時,都不應反覆新增。持續未完成時聯絡支援
網頁出現 internal error 不代表確認工作階段已結束。先執行本節的兩個 GET 請求,查詢工作階段和素材組;工作階段仍為 pending 時,不要反覆建立同組工作階段。只有工作階段為 verified 且素材組為 active,才繼續新增素材。僅憑網頁錯誤無法判斷原因,持續未完成時保留 ID 聯絡支援。

  1. 透過圖片網址建立素材

圖片準備

提供回傳圖片檔案的絕對 HTTP(S) 網址,優先使用 HTTPS。連結應無需登入或附加請求標頭即可讀取;本機路徑、內部網路位址、Base64 和帶帳號密碼的 URL 不適用於素材建立介面。URL 不應包含 # 片段。 根據 BytePlus 真人素材指南,圖片建議為清晰正面照,並符合以下素材入庫要求: 上述為官方素材庫要求,影片模型還可能有獨立的參考素材限制。上傳前同時核對目標模型要求;HTTP 建立成功也不表示素材已通過處理。

建立請求

IMAGE_URL 改為你已獲得本人同意使用的圖片直連網址。範例網域僅作預留位置,不提供真人圖片。
請求主體只接受以上三個欄位。Idempotency-Key 放在請求標頭,可選,最長 128 位元組,不能有前後空白或控制字元。音訊與影片的檔案限制請查閱上述官方指南,並核對目標模型支援的類型與時長。 首次建立通常回傳 HTTP 201;重用已有素材回傳 200;結果仍待確認、狀態為 reconciling 時回傳 202。一律讀取物件的 status 素材公開欄位為 idobjectgroup_idasset_typestatusclient_reference_idcreated_atupdated_atdeleted_atobject 固定為 asset;未提供或已刪除的 client_reference_id 不回傳,未刪除時 deleted_atnull。時間欄位為 Unix 秒,查詢不回傳原圖片網址,請自行保留業務記錄。

  1. 等待素材可用

可每 10 至 15 秒查詢一次,並設定本機等待上限。停止本機輪詢不會取消伺服器端操作。
建立結果未知且持續沒有相符結果時,素材可能一直維持 reconciling,也可能影響素材或素材組刪除。保留 ID 和原請求識別值,聯絡支援;不要透過更換識別值反覆建立,也不要假設等待一段時間就會自動清理。

  1. 使用素材生成影片

影片引用使用 AIHubMix 素材建立回應中的完整 id,格式為 asset://<asset_id>。同一次請求引用的全部素材必須屬於同一素材組、歸目前帳戶所有,且均為 active。素材組也必須保持可用。 引用類型必須與素材建立時的 asset_type 一致。asset:// 用於影片參考欄位,並非供瀏覽器下載的網址。

新版影片協定

先依端點路徑核對目前模型 Schema:
確認模型支援參考圖片後提交。以下採用本次線上驗證成功的 Seedance 2.5 參數:duration=4resolution="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 時,將引用放在 contentextra_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 查詢。詳細說明見相容影片介面

  1. 輪詢並下載新版影片

以下 Python 範例僅接續前面的新版建立步驟,讀取環境變數中的 VIDEO_ID,不重新建立任務。需要安裝 requests
30 分鐘為範例的本機等待上限,不代表伺服器端任務逾時。查詢 HTTP 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-Keyclient_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 表示仍有操作或影片任務未結束。等待並查詢相關狀態後重試。相容影片任務需要自行確認結束,不要依賴刪除請求自動判斷所有相容任務的占用。

常見問題

已完成網頁操作,為什麼還不能新增素材?

先查詢確認工作階段和素材組,以 verifiedactive 為準。網頁出現 internal error 時也執行相同檢查;pending 期間不反覆建立同組工作階段。結果尚未確認時稍後再查;持續未完成請提供 ID 聯絡支援,無需提交確認連結或本人照片。

素材可用,為什麼生成影片仍然失敗?

檢查引用是否使用 AIHubMix 回傳的素材 ID,所有素材是否屬於同一組,媒體類型是否相符,以及目前模型是否支援相應輸入。素材 active 表示素材可用,影片任務仍需單獨檢查完成狀態和錯誤資訊。

如何處理常見介面錯誤?

其他影片錯誤參閱非同步任務錯誤碼。回報時提供發生時間、HTTP 狀態、error.code、回傳的 error.tid(如有)及相關資源 ID;不要提供 API Key、確認連結或帶簽章的圖片網址。

參考資料

更新時間:2026-09-07