> ## 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 创建虚拟人像素材组、上传图片并生成视频的流程。

本文只介绍私域虚拟人像，不包含公共虚拟人像目录。

<h2 id="prerequisites">
  前置条件
</h2>

* 准备有效的 AIHubMix API Key，通过环境变量 `AIHUBMIX_API_KEY` 读取。
* 确认账户已开通目标视频模型和虚拟人像素材能力，并有足够额度。
* 准备模型可以访问的公网 HTTPS 图片直链。
* 准备 Bash、curl 和 jq。

虚拟人像不需要创建真人确认 Session，也不能为虚拟人像组创建真人确认 Session。

<h2 id="create-group">
  1. 创建虚拟人像素材组
</h2>

创建时将 `kind` 设置为 `virtual_portrait`：

```bash theme={null}
BASE_URL="https://aihubmix.com"
GROUP_JSON=$(curl --fail-with-body -sS --max-time 60 \
  -X POST "$BASE_URL/ai/v1/asset-groups" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: virtual-portrait-group-<unique-id>" \
  -d '{"name":"我的虚拟人像","kind":"virtual_portrait"}')
printf '%s\n' "$GROUP_JSON" | jq '{id,object,kind,status,error}'
GROUP_ID=$(printf '%s' "$GROUP_JSON" | jq -er '.id')
```

创建成功返回 HTTP `201`。虚拟组通常直接返回 `status=active`，授权状态为 `not_required`。只有 `active` 且已绑定模型推理厂商素材组的虚拟组才能添加素材。

<h2 id="create-asset">
  2. 上传图片素材
</h2>

图片必须是公网可访问的 HTTP(S) 直链，不要使用本地路径、内网地址、Base64 或需要登录的链接。

```bash theme={null}
IMAGE_JSON=$(curl --fail-with-body -sS --max-time 60 \
  -X POST "$BASE_URL/ai/v1/asset-groups/$GROUP_ID/assets" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: virtual-portrait-image-<unique-id>" \
  -d '{"url":"https://example.com/virtual-portrait.jpg","asset_type":"image","client_reference_id":"my-virtual-portrait"}')
printf '%s\n' "$IMAGE_JSON" | jq '{id,object,group_id,asset_type,status,error}'
ASSET_ID=$(printf '%s' "$IMAGE_JSON" | jq -er '.id')
```

上传成功通常返回 `201` 和 `status=processing`，不表示素材已经可用于视频。建议图片小于 30 MB，宽高均在 300 至 6000 像素之间，宽高比大于 0.4 且小于 2.5。

<h2 id="wait-active">
  3. 等待素材可用
</h2>

```bash theme={null}
curl --fail-with-body -sS "$BASE_URL/ai/v1/assets/$ASSET_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq '{id,status,error}'
```

只有 `status=active` 才能用于视频。`creating`、`processing` 继续查询；`failed` 检查图片地址和素材要求；`reconciling` 表示结果待确认，暂不使用。

<h2 id="generate-video">
  4. 使用虚拟人像生成视频
</h2>

使用上传接口返回的完整素材 ID，格式为 `asset://<asset_id>`。不要使用原图片 URL，也不要手工拼接模型推理厂商素材 ID。

```bash theme={null}
VIDEO_JSON=$(curl --fail-with-body -sS --max-time 120 \
  -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":"让虚拟人像自然地向镜头微笑并轻微转头。","input_references":[{"type":"image_url","url":"asset://<asset_id>"}]}' )
printf '%s\n' "$VIDEO_JSON" | jq '{id,object,status,model,error}'
VIDEO_ID=$(printf '%s' "$VIDEO_JSON" | jq -er '.id')
```

同一次请求引用的私域素材必须属于同一素材组、归当前账户所有，并且均为 `active`。虚拟人像组固定使用创建时绑定的渠道、账号、地域和 Project。

通过 `GET /ai/v1/videos/<video_id>` 查询任务。返回 HTTP `200` 不等于生成成功，必须检查 `status`。只有 `status=completed` 才算生成成功；`in_progress` 继续查询，`failed` 或 `cancelled` 停止并读取 `error`。任务完成后通过 `GET /ai/v1/videos/<video_id>/content` 获取 `video/mp4` 内容。线上验证中，状态查询的 `results` 可能为空，不能仅依赖 `results` 判断是否成功。

建议每 15 秒查询一次，并设置本地等待上限。任务变为 `completed` 后，再请求 `/ai/v1/videos/<video_id>/content` 保存视频文件。示例中的 `<group_id>`、`<asset_id>`、`<video_id>` 和 `<unique-id>` 都是占位符，必须替换为前一步接口实际返回的值，不能原样复制执行。

<h2 id="errors">
  常见错误
</h2>

| HTTP | `error.code`                                                        | 处理方式                 |
| ---- | ------------------------------------------------------------------- | -------------------- |
| 400  | `asset_group_invalid`                                               | 检查素材组名称和 `kind`      |
| 400  | `asset_invalid`                                                     | 检查图片公网地址、类型和请求字段     |
| 400  | `asset_binding_mismatch`                                            | 同一次请求只引用同一素材组素材      |
| 400  | `channel_pin_conflict`                                              | 指定渠道与素材绑定不一致，修改请求后再试 |
| 404  | `asset_group_not_found`、`asset_not_found`                           | 检查资源 ID 和当前账户        |
| 409  | `asset_not_ready`                                                   | 等待素材状态变为 `active`    |
| 503  | `asset_group_unavailable`、`asset_unavailable`、`channel_unavailable` | 稍后重试并检查绑定渠道          |

<h2 id="troubleshooting">
  删除和排障
</h2>

虚拟组处于 `creating` 或 `reconciling` 时，因创建结果仍未知，暂不允许直接删除或自动清理。持续查询不到模型推理厂商素材组时保留本地记录和恢复定位，需要运维核对后处理。

API Key 只通过环境变量传入，不写入脚本、日志或文档。反馈问题时提供发生时间、HTTP 状态、错误码、请求编号和资源 ID，不提供 API Key 或带签名的图片地址。

<h2 id="faq">
  常见问题
</h2>

### 虚拟人像需要真人确认吗？

不需要。创建素材组时指定 `kind=virtual_portrait`，组授权状态为 `not_required`。

### 为什么图片上传成功后还不能生成视频？

图片通常会先处于 `processing`。必须查询到 `status=active` 后再提交视频任务。

### 视频任务完成后如何获取文件？

查询到 `status=completed` 后，请求 `GET /ai/v1/videos/<video_id>/content` 获取视频文件。

更新时间：2026-09-11