Skip to main content
私域虛擬人像素材用於在影片中引用不需要本人確認的虛擬人物形象。本頁介紹建立素材組、上傳圖片、查詢狀態和生成影片的流程，不包含公共虛擬人像目錄。

​
前置條件

  • 透過環境變數 AIHUBMIX_API_KEY 設定有效的 API Key。
  • 確認帳戶已開通目標影片模型和虛擬人像素材能力。
  • 準備模型推理廠商可以讀取的公開 HTTPS 圖片直連網址。

​
建立虛擬人像素材組

向 POST /ai/v1/asset-groups 傳送 kind: "virtual_portrait"。成功回傳 201，通常直接為 active，授權狀態為 not_required。此流程不需要建立本人確認工作階段。

​
上傳並等待圖片

向 POST /ai/v1/asset-groups/<group_id>/assets 傳送 url、asset_type: "image" 和可選的 client_reference_id。圖片網址必須公開可讀取，不使用本機路徑、內網網址、Base64 或需要登入的連結。 使用 GET /ai/v1/assets/<asset_id> 查詢，直到 status=active 才能用於影片。processing、creating 繼續查詢，failed 檢查圖片，reconciling 暫不使用。

​
生成影片

使用 asset://<asset_id> 作為 input_references[].url 呼叫 POST /ai/v1/videos：
使用 GET /ai/v1/videos/<video_id> 查詢，只有 status=completed 代表生成成功。in_progress 繼續查詢，failed 或 cancelled 停止並讀取 error。完成後使用 /ai/v1/videos/<video_id>/content 取得影片。

​
常見錯誤

asset_not_ready 表示素材尚未為 active。asset_binding_mismatch 表示同一請求引用了不相容的私域素材。channel_pin_conflict 表示指定渠道與素材綁定不一致。實際渠道不可用時返回 channel_unavailable。

​
刪除與排障

虛擬組處於 creating 或 reconciling 時，建立結果仍未知，暫不直接刪除或自動清理。持續查詢不到模型推理廠商素材組時保留本地記錄和恢復定位，需要運維核對後處理。 API Key 只透過環境變數管理，不寫入程式碼或日誌。