真人人像素材管理

真人人像素材用于需要核验本人授权的真实形象。与虚拟人像素材相比，它多了一套活体认证建组流程；素材提交、审核和 qasset:// 视频引用方式相同。

警告

使用真人人像前，应确保已获得必要授权并满足适用的肖像权、隐私和内容合规要求。一般虚拟形象或无需真人授权的场景应优先使用虚拟人像素材。

流程概览

创建 liveness_face 分组
  → awaiting_auth
  → 用户打开 H5 完成刷脸
  → 回调确认成功
  → 触发一次认证回查
  → active
  → 提交真人素材
  → 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"

国内和海外的素材管理流程一致。callback_url 必须是你的服务提供的、可通过公网访问的 HTTPS 地址。

1. 创建真人认证分组

调用 POST /v1/asset-groups，将 type 设为 liveness_face：

curl "$MODELINK_BASE_URL/v1/asset-groups" \
  -H "Authorization: Bearer $MODELINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "授权真人形象",
    "description": "用于已授权的品牌视频",
    "type": "liveness_face",
    "model": "bytedance/doubao-seedance-2-0-260128",
    "callback_url": "https://your-domain.example/liveness/callback"
  }'

接口立即返回 qgroupid，初始状态为 pending。真人分组不会成为默认分组，is_default 始终为 false。

2. 获取活体认证链接

轮询分组详情：

export GROUP_ID="qgroup-<uid>-<timestamp>"

curl "$MODELINK_BASE_URL/v1/asset-groups/$GROUP_ID" \
  -H "Authorization: Bearer $MODELINK_API_KEY"

平台创建认证会话后，分组会进入 awaiting_auth，响应包含 h5_link：

{
  "qgroupid": "qgroup-<uid>-<timestamp>",
  "type": "liveness_face",
  "status": "awaiting_auth",
  "h5_link": "https://<liveness-provider>/...",
  "byted_token": "<one-time-token>"
}

警告

h5_link 和认证凭证的有效期约为 120 秒。进入 awaiting_auth 后应立即把链接交给需要认证的用户打开；超时后需要重新创建真人分组。

不要把 h5_link 或 byted_token 写入公开日志、前端埋点或错误上报。

3. 处理认证回调

用户完成刷脸后，浏览器会跳转到创建分组时提供的 callback_url，并携带类似以下查询参数：

https://your-domain.example/liveness/callback?bytedToken=...&resultCode=10000

你的服务应：

找到这次认证对应的 qgroupid。
检查 resultCode。
只有 resultCode == 10000 时，才触发下一步认证回查。
将这次回查记录为已处理，防止浏览器刷新导致重复调用。

回调来自用户浏览器跳转，不应仅凭回调参数认定分组已经激活；最终状态必须以 Modelink 分组查询结果为准。

4. 触发认证回查

确认刷脸成功后，调用：

curl "$MODELINK_BASE_URL/v1/asset-groups/$GROUP_ID/visual-validate-result" \
  -H "Authorization: Bearer $MODELINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "result_code": "10000"
  }'

接口返回 202 表示已受理，并不代表认证最终成功。继续轮询分组详情，直到进入 active 或 failed。

警告

认证回查会使用一次性凭证。务必在刷脸成功后调用，并由服务端保证同一分组只触发一次。提前调用或重复调用可能消耗凭证，使该分组只能废弃并重建。

分组已经进入 active 或 failed 后再次调用时，接口会直接返回当前终态，不再重新触发供应商回查。

5. 提交真人素材

真人素材不支持自动建组。必须显式传入已经 active 的真人分组 group_id：

curl "$MODELINK_BASE_URL/v1/assets" \
  -H "Authorization: Bearer $MODELINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "url": "https://example.com/authorized-person.png",
    "name": "授权真人正脸素材",
    "model": "bytedance/doubao-seedance-2-0-260128",
    "group_id": "qgroup-<uid>-<timestamp>"
  }'

保存返回的 qassetid，轮询素材详情到 approved 或 failed：

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

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

真人组会把后续素材与活体认证基准进行人脸一致性比对。多人脸、非同一人或不符合审核要求的素材会进入 failed，具体原因查看 fail_reason。

6. 在视频生成中引用

素材进入 approved 后，通过 qasset://{qassetid} 引用：

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 系列模型。素材、分组和视频任务的 model 必须一致。完整视频参数请参阅视频 / 火山格式 · Seedance 2.0。

状态与恢复策略

阶段	状态	处理方式
建认证会话	`pending`	继续轮询；长时间不变化时记录请求 ID
等待刷脸	`awaiting_auth`	立即打开 `h5_link`；超时后重建分组
认证完成	`active`	可以向该组提交真人素材
认证失败	`failed`	查看 `fail_reason`，重新创建分组并认证
素材等待处理	`pending` / `reviewing`	继续轮询
素材审核通过	`approved`	可以用于视频任务
素材审核失败	`failed`	根据 `fail_reason` 修正素材后重新提交

删除操作遵循以下约束：

pending、awaiting_auth、reviewing 等非终态记录不能删除。
只有 approved 或 failed 的素材可以删除。
删除真人分组前，先删除组内所有素材。
已失效、失败或凭证被消耗的真人分组不能恢复认证流程，应创建新分组。

接口字段和完整错误响应请参阅素材 / 素材分组与素材 / 素材管理。更多限制参阅 Seedance 2.0 产品 FAQ。