虚拟人像素材管理

虚拟人像素材适用于无需真人活体授权的形象。提交后，平台会异步审核素材；审核通过后，可在 Seedance 2.0 视频任务中通过 qasset:// URI 反复引用。

如果需要使用经本人确认授权的公众人物或真实形象，请改用真人人像素材管理。

信息

若只需单次虚拟人像生视频、不希望自行编排素材 API，可在火山格式或 Fal 队列视频任务中设置 auto_create_assets: true。详见 Seedance 虚拟人像生视频自动临时素材。需要反复复用同一形象时，仍应走本文流程并使用 qasset://。

流程概览

创建或复用 aigc 分组 → 提交素材 → 轮询审核 → approved → qasset:// 引用

虚拟人像与真人人像共用素材审核和视频引用管线，但虚拟人像不需要刷脸，并支持自动创建默认分组。

准备接入点

export MODELINK_API_KEY="替换为你的 Modelink API Key"

# 中国大陆
export MODELINK_BASE_URL="https://api.qnaigc.com"

# 海外使用：
# export MODELINK_BASE_URL="https://api.modelink.ai"

国内和海外的素材管理流程一致。当前支持的模型 ID 以素材管理 API中的 model 枚举为准。

最短路径：直接提交素材

多数场景不需要先创建分组。调用 POST /v1/assets 时不传 group_id，平台会按当前用户、aigc 类型和模型选择默认分组；如果不存在，则异步创建一个默认分组。

curl "$MODELINK_BASE_URL/v1/assets" \
  -H "Authorization: Bearer $MODELINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "url": "https://example.com/avatar.png",
    "name": "品牌虚拟形象",
    "model": "bytedance/doubao-seedance-2-0-260128"
  }'

响应会包含素材 ID 和实际分组 ID：

{
  "qassetid": "qasset-<uid>-<timestamp>",
  "group_id": "qgroup-<uid>-<timestamp>",
  "status": "pending"
}

信息

第一次不传 group_id 上传时，平台可能先异步创建默认分组，素材会在 pending 停留一段时间；分组激活后，素材才进入 reviewing。后续上传会复用默认分组。

轮询审核状态

查询素材详情，直到进入 approved 或 failed：

export ASSET_ID="qasset-<uid>-<timestamp>"

curl "$MODELINK_BASE_URL/v1/assets/$ASSET_ID" \
  -H "Authorization: Bearer $MODELINK_API_KEY"

状态	含义	操作
`pending`	等待分组或审核任务创建	继续轮询
`reviewing`	审核中	继续轮询
`approved`	审核通过	可以在视频任务中引用
`failed`	审核或提交失败	查看 `fail_reason`，修正素材后重新提交

只有 approved 素材可以用于视频生成。

在视频生成中引用

将 qassetid 组成 qasset://{qassetid}，作为 reference_image 传给 Seedance 2.0：

curl "$MODELINK_BASE_URL/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $MODELINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "图片1在城市街道上自然行走"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "qasset://qasset-<uid>-<timestamp>"
        },
        "role": "reference_image"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'

qasset:// 仅适用于支持素材引用的 Seedance 2.0 系列模型。完整请求参数请参阅视频 / 火山格式 · Seedance 2.0。素材绑定的 model 必须与视频任务使用的模型一致。

主动管理分组

需要按项目或业务线管理素材时，可以显式创建 aigc 分组：

curl "$MODELINK_BASE_URL/v1/asset-groups" \
  -H "Authorization: Bearer $MODELINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "品牌形象组",
    "description": "用于品牌宣传视频",
    "type": "aigc",
    "model": "bytedance/doubao-seedance-2-0-260128"
  }'

创建分组是异步操作。保存返回的 qgroupid，轮询 GET /v1/asset-groups/{qgroupid} 到 active 后，再将其作为 group_id 传给 POST /v1/assets。

显式指定的分组必须满足：

属于当前 API Key 对应的用户。
状态为 active。
model 与素材请求完全一致。

否则创建素材会返回 400 invalid_request_error。

更新和删除

分组只允许更新 name 或 description，创建后不能修改 model。
只有 approved 或 failed 的终态素材可以删除。
删除非空分组前，需要先删除组内所有素材。
pending、awaiting_auth 或其他非终态分组不能删除。

接口和完整响应请参阅素材 / 素材分组与素材 / 素材管理。

配额与排查

默认情况下，单个账号最多创建 3 个素材分组、保存 30 个素材；如需调整，请联系技术支持。更多产品限制参阅 Seedance 2.0 产品 FAQ。

现象	排查方向
首次素材长时间 `pending`	默认分组仍在创建，先查询返回的 `group_id` 状态
素材进入 `failed`	检查 `fail_reason`、URL 可访问性、素材质量与内容合规
指定分组后返回 400	检查分组归属、状态和模型是否一致
视频任务拒绝 `qasset://`	检查素材是否 `approved`、模型是否一致、目标视频模型是否支持素材引用