> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 豆包私域虛擬人像素材使用指南

> 建立無需本人確認的虛擬人像素材組，上傳圖片並使用 asset:// 呼叫豆包 Seedance 影片生成。

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

## 前置條件

* 透過環境變數 `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`：

```bash theme={null}
BASE_URL="https://aihubmix.com"
curl --fail-with-body -sS -X POST "$BASE_URL/ai/v1/videos" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"doubao-seedance-2-5-260628","prompt":"Make the virtual portrait smile naturally.","input_references":[{"type":"image_url","url":"asset://<asset_id>"}]}' | jq
```

使用 `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 只透過環境變數管理，不寫入程式碼或日誌。