Modelink

火山协议 · 真人人像素材管理

火山协议真人人像素材适用于需要由本人完成认证的真实形象。终端用户完成一次真人认证后，可以向认证产生的素材组持续上传同一人的不同妆造素材；素材审核通过后，通过 asset:// 在多个 Seedance 视频任务中复用。

若希望使用 Bearer 鉴权和 Modelink 资源 ID，请改用 Modelink API · 真人人像素材管理。无需真人认证的 AI 生成人像或素人照片，请参阅火山协议 · 虚拟人像素材管理。

警告

使用真人人像前，应确保已获得必要授权并满足适用的肖像权、隐私和内容合规要求。认证链接和凭据只能交给本次需要认证的用户。

流程概览

查询 ProjectName
  → CreateVisualValidateSession
  → 用户打开 H5Link 完成认证
  → 回调 resultCode=10000
  → GetVisualValidateResult 获取 GroupId
  → CreateAsset
  → GetAsset 轮询至 Active
  → asset://{AssetId} 引用

信息

本文说明认证和素材主链。完整字段、响应、错误码及 V4 签名规则以火山素材兼容接口为准。

准备接入点

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

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

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

CallbackURL 必须是你的服务提供的、可通过公网访问的 HTTP(S) 地址。生产环境建议只使用 HTTPS，并在服务端记录认证会话与业务用户的对应关系。

  1. 查询支持真人人像的 ProjectName

    先使用 Bearer 鉴权调用 GET /v1/asset-projects：

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

    选择 supported_asset_types 包含 liveness_face 的项目：

    {
  "data": [
    {
      "project_name": "cv1-bogic",
      "supported_asset_types": ["aigc", "liveness_face"]
    }
  ]
}
    export PROJECT_NAME="cv1-bogic"

    警告

    火山兼容 Action 的 ProjectName 必填，必须使用接口返回的 cv1-xxxxx；不支持 default。认证会话、真人素材组和素材必须始终使用同一个值。

  2. 为每个 Action 生成 V4 签名

    Action 请求固定发送到：

    POST /volcengine/assets/?Action=<Action>&Version=2024-01-01

    将同一个 Modelink API Key 同时作为 V4 Credential 中的 Access Key 和签名密钥。每个请求必须针对最终 URL 和请求体重新生成：

    Authorization: HMAC-SHA256 Credential=...
X-Date: 20260817T080000Z
X-Content-Sha256: <最终请求体原始字节的 SHA-256 小写十六进制值>
Content-Type: application/json

    下文用 $AUTHORIZATION、$X_DATE、$PAYLOAD_HASH 和 $BODY 表示当前请求对应的动态值。签名后不要重新序列化 $BODY，也不要在不同 Action 之间复用签名。

  3. 创建真人认证会话

    调用 CreateVisualValidateSession：

    {
  "CallbackURL": "https://your-domain.example/liveness/callback",
  "ProjectName": "cv1-bogic"
}
    curl "$MODELINK_BASE_URL/volcengine/assets/?Action=CreateVisualValidateSession&Version=2024-01-01" \
  -H "Authorization: $AUTHORIZATION" \
  -H "X-Date: $X_DATE" \
  -H "X-Content-Sha256: $PAYLOAD_HASH" \
  -H "Content-Type: application/json" \
  -d "$BODY"

    成功响应的 Result 包含：

    {
  "BytedToken": "replace-with-byted-token",
  "H5Link": "https://ark.volcengine.com/example-liveness-page",
  "CallbackURL": "https://your-domain.example/liveness/callback"
}

    立即把 H5Link 交给本次需要认证的用户，并在服务端安全保存 BytedToken 与业务会话的对应关系。

    警告

    BytedToken 是本次认证的唯一凭证，不得写入公开日志、前端埋点、分析系统或错误上报。不要把完整认证响应发送给无关客户端。

  4. 处理 H5 认证结果回调

    用户打开 H5Link，确认授权并完成真人认证。点击完成后，浏览器跳转到 CallbackURL，例如：

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

    服务端应执行：

    1. 根据本地会话定位对应的业务用户和 ProjectName。
    2. 检查 resultCode，只有 resultCode=10000 才进入下一步。
    3. 对同一会话做幂等保护，避免浏览器刷新触发重复业务操作。
    4. 不仅凭回调参数认定素材组已经可用，最终以查询 Action 的结果为准。

    如果真人认证失败，原 H5 链接会失效；重新调用 CreateVisualValidateSession 生成新的认证会话，不要继续使用旧凭据。

  5. 获取真人素材组 ID

    真人认证成功后，在 BytedToken 创建后的 30 分钟内调用 GetVisualValidateResult：

    {
  "BytedToken": "replace-with-byted-token",
  "ProjectName": "cv1-bogic"
}
    curl "$MODELINK_BASE_URL/volcengine/assets/?Action=GetVisualValidateResult&Version=2024-01-01" \
  -H "Authorization: $AUTHORIZATION" \
  -H "X-Date: $X_DATE" \
  -H "X-Content-Sha256: $PAYLOAD_HASH" \
  -H "Content-Type: application/json" \
  -d "$BODY"

    成功响应包含本次认证创建的素材组 ID：

    {
  "Result": {
    "GroupId": "group-20260817123000-example"
  }
}

    如果供应商尚未生成 GroupId，保持当前会话并在凭据有效期内重试。保存 GroupId，后续所有素材操作继续使用同一个 ProjectName。

  6. 向真人素材组上传素材

    使用认证得到的 GroupId 调用 CreateAsset：

    {
  "AssetType": "Image",
  "GroupId": "group-20260817123000-example",
  "Name": "授权真人正面素材",
  "ProjectName": "cv1-bogic",
  "URL": "https://example.com/authorized-person.png"
}
    curl "$MODELINK_BASE_URL/volcengine/assets/?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: $AUTHORIZATION" \
  -H "X-Date: $X_DATE" \
  -H "X-Content-Sha256: $PAYLOAD_HASH" \
  -H "Content-Type: application/json" \
  -d "$BODY"

    保存响应 Result.Id。真人组会对后续素材进行人脸一致性和内容审核；多人脸、非同一人或不符合要求的素材可能处理失败。

  7. 轮询素材处理状态

    使用素材 ID 和原 ProjectName 调用 GetAsset：

    {
  "Id": "asset-20260817123500-example",
  "ProjectName": "cv1-bogic"
}
    curl "$MODELINK_BASE_URL/volcengine/assets/?Action=GetAsset&Version=2024-01-01" \
  -H "Authorization: $AUTHORIZATION" \
  -H "X-Date: $X_DATE" \
  -H "X-Content-Sha256: $PAYLOAD_HASH" \
  -H "Content-Type: application/json" \
  -d "$BODY"
    Result.Status含义处理方式
    Processing处理中继续轮询
    Active已审核可用可以用于 Seedance 视频任务
    Failed处理失败查看错误信息，修正素材后重新上传

    只有 Status=Active 的素材可以用于视频生成。

  8. 在 Seedance 视频任务中引用真人素材

    将已激活的素材 ID 拼接为 asset://{AssetId}。视频任务使用 Modelink Bearer 鉴权：

    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": "asset://asset-20260817123500-example"
        },
        "role": "reference_image"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'

    素材必须来自当前 API Key 可用的项目，并与视频任务使用的素材/视频渠道关系匹配。完整视频参数见视频 / 火山格式 · Seedance。

查询、更新和删除

真人认证成功后，素材组可以复用通用管理 Action：

Action用途
ListAssetGroups使用 GroupType=LivenessFace 查询
GetAssetGroup查询指定真人素材组
ListAssets查询组内素材及状态
GetAsset查询单个素材和审核状态
UpdateAssetGroup更新素材组名称或描述
UpdateAsset更新素材名称
DeleteAsset删除不再使用的素材
DeleteAssetGroup删除真人素材组

删除不可恢复。删除素材组前先删除组内素材，并确保认证或素材处理操作已经结束。完整字段与删除约束见火山素材兼容接口。

状态与恢复策略

阶段现象处理方式
创建认证会话未返回有效链接或凭据保存请求 ID，不向用户展示不完整会话
H5 认证失败回调结果不是 10000重新创建认证会话，不复用旧链接和凭据
查询素材组过晚BytedToken 已超过 30 分钟重新创建认证会话并完成认证
查询不到素材组暂未返回 GroupId在有效期内重试，并保持原 ProjectName
素材审核失败Status=Failed查看错误信息，修正素材后重新上传
视频拒绝素材引用素材 ID 不可用检查是否 Active，以及素材项目和视频渠道关系是否一致

警告

认证回调来自用户浏览器，不能作为素材组已经创建成功的唯一依据。只有 GetVisualValidateResult 返回有效 GroupId，且后续素材达到 Active 后，才可以进入视频生成流程。

Last updated

© 2026 Modelink. All rights reserved.

构建来自Clarify