AICC真人认证完整流程

从创建认证会话到用真人素材生成视频的完整调用示例，包含每一步的请求、响应与注意事项。

本文档演示从创建真人认证会话到用认证通过的真人素材生成视频的完整流程，共 5 个步骤。

在开始之前，你需要先拿到一对由平台分配的模型名：注意！！！:以下模型名只是举例使用,实际模型名以平台提供的为准!!!本文档所有模型名都是示例模型名,方便理解具体填写哪个模型名,实际以平台提供的为准!! 实际调用请替换所有示例模型名称sd2.0-260730-aicc和sd2.0-260730为实际模型名称!!!

用途	示例值
真人认证模型名	`sd2.0-260730-aicc` 说明:这里只是示例值,实际使用请将sd2.0-260730-aicc替换为平台提供的实际模型名称！
视频生成模型名	`sd2.0-260730` 说明:这里只是示例值,实际使用请将sd2.0-260730替换为平台提供的实际模型名称

这一对模型名对应同一个第三方账户，请求真人认证接口时通过 X-Realperson-Model 请求头传入认证模型名；请求视频生成接口时，模型名作为请求体的 model 字段传入。两者必须成对使用，否则生成视频时会找不到对应的真人素材。

第一步：创建认证会话

调用认证会话接口，获取用于活体检测的 H5 链接。

curl -X POST https://api域名/v1/aicc/real-person-auth/sessions \
  -H "Authorization: Bearer 用户Key" \
  -H "X-Realperson-Model: sd2.0-260730-aicc" \
  -H "Content-Type: application/json" \
  -d '{}'

将返回的 h5Link 发给用户，引导用户在手机上打开完成活体认证。链接有效期 120 秒，请提示用户尽快完成。

返回示例：

{
    "result": {
        "bytedToken": "202607071613390F4443FDA6379BA15B1F",
        "h5Link": "https://ark.volcengine.com/region:cn-beijing/mobile/livenees-face-manage/authorization?pl=...",
        "expiresIn": 120
    }
}

请妥善保存返回的 bytedToken，下一步会用到。

第二步：查询 groupId

用户在手机端完成 H5 认证后，用第一步拿到的 bytedToken 换取该用户对应的真人素材组 groupId。

curl -X POST https://api域名/v1/aicc/real-person-auth/asset-group/by-byted-token \
  -H "Authorization: Bearer 用户Key" \
  -H "X-Realperson-Model: sd2.0-260730-aicc" \
  -H "Content-Type: application/json" \
  -d '{"bytedToken": "填写第一步返回的 bytedToken"}'

返回示例：

{
    "result": "group-20260707161432-8n5sj"
}

第三步：上传真人素材

拿到 groupId 后，上传一张真人图片或视频作为素材，素材需来自已通过第一、二步认证的同一个人。

curl -X POST https://api域名/v1/aicc/asset/ \
  -H "Authorization: Bearer 用户Key" \
  -H "X-Realperson-Model: sd2.0-260730-aicc" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "第二步返回的 groupId",
    "assetName": "我的素材",
    "assetUrl": "https://你的真人照片URL.jpg",
    "assetType": "Image"
  }'

返回示例：

{
    "result": "asset-20260707161843-sh5x9"
}

返回的 assetId 就是后续生成视频时要引用的素材标识。

第四步：轮询素材状态

素材上传后需要经过审核，审核期间请轮询查询接口，直到 status 变为 ACTIVE。

curl -X GET https://api域名/v1/aicc/asset/asset-xxx \
  -H "Authorization: Bearer 用户Key" \
  -H "X-Realperson-Model: sd2.0-260730-aicc"

返回示例（status = ACTIVE 即为审核通过）：

{
    "result": {
        "assetId": "asset-20260707161843-sh5x9",
        "groupId": "group-20260707161432-8n5sj",
        "assetName": "人物001",
        "assetType": "Image",
        "assetUrl": "https://ark-media-asset.tos-cn-beijing.volces.com/....png?X-Tos-Algorithm=...",
        "status": "ACTIVE",
        "createdTime": "2026-07-07 16:18:43",
        "updatedTime": "2026-07-07 16:18:47"
    }
}

status 为 ACTIVE 且返回了 assetUrl 时，说明素材已经审核通过，可以进入下一步。

第五步：用真人素材生成视频

调用视频生成接口时，model 字段填第一步对应的视频生成模型名（不是认证模型名），并在 content 数组中通过 asset:// 协议引用第三步拿到的 assetId 作为参考图片或参考视频。

curl -X POST https://api域名/v1/video/generations \
  -H "Authorization: Bearer 用户Key" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "sd2.0-260730",
  "prompt": "一位刚刚完成认证的真人在舞剑，电影质感，近景",
  "metadata": {
    "ratio": "16:9",
    "duration": 6,
    "generate_audio": false,
    "resolution": "720p",
    "watermark": false,
    "content": [
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://asset-20260729093252-cpbm8"
        },
        "role": "reference_image"
      }
    ]
  }
}'

注意

这一步不需要再传 X-Realperson-Model 请求头，因为视频生成走的是模型名而非请求头路由。
asset:// 后面跟的是第三步返回的 assetId，请勿替换成 assetUrl 里那个带签名参数的真实地址——asset:// 引用会由平台在生成时自动解析到正确的素材。
真人认证模型名与视频生成模型名必须是成对分配的同一账户组合，混用不同账户的认证模型名和视频生成模型名会导致生成失败或找不到素材。

流程速览

POST /v1/aicc/real-person-auth/sessions → 拿到 bytedToken 和 h5Link
用户完成 H5 活体认证
POST /v1/aicc/real-person-auth/asset-group/by-byted-token → 拿到 groupId
POST /v1/aicc/asset/ → 上传素材，拿到 assetId
GET /v1/aicc/asset/{assetId} → 轮询直到 status = ACTIVE
POST /v1/video/generations → 用 asset://{assetId} 作为参考图片/视频生成视频