真人扫码活体流程

API 配置

保存后下方「Try It」面板会自动携带此 API Key 发送真实请求。

Base: api.xrtoken.net

真人活体认证是开通"真人数字人"能力的前置步骤：终端用户扫码完成一次火山引擎的活体采集后，对应的 AssetGroup 会绑定到当前 API 调用方的用户下，后续视频生成接口就能通过 asset://<groupId> 引用这个真人。

整套流程涉及 4 个接口、1 次端侧扫码。按顺序调用即可。

前置要求

调用以下接口需满足：

条件	来源
账号开通可信创作者（trusted_creator）	控制台提交申请
账号通过企业认证	控制台提交企业资料
用户完成人脸信息处理同意	下文第一步

前两项由平台审核，一次性完成。第三项按 GDPR / 个人信息保护法要求，每次同意条款升级后都要重新签，接口会返回版本号让客户端比对。

时序

客户端            你的后端          XRToken API          火山 Ark
 │                   │                  │                   │
 │ 1.获取同意状态     │                  │                   │
 │──────────────────▶│  GET /v1/face-consent ──────────────▶│
 │◀───── valid? ─────│                  │                   │
 │                   │                  │                   │
 │ 2.(需要时)        │                  │                   │
 │   展示同意弹窗     │                  │                   │
 │   用户点同意       │                  │                   │
 │──────────────────▶│  POST /v1/face-consent ─────────────▶│
 │                   │   (policy_version, volc_rule_version)│
 │                   │                  │                   │
 │ 3.发起扫码会话     │                  │                   │
 │──────────────────▶│  POST /v1/asset-groups/             │
 │                   │        validate-session ────────────▶│
 │◀── QRCodeDataURL ─│     + BytedToken                     │
 │   + BytedToken    │                  │                   │
 │                   │                  │                   │
 │ 4.用户扫码         │                  │                   │
 │  （跳转火山 H5）   │                  │                   │
 │                   │                  │  ───────────────▶│ 活体采集
 │                   │                  │                   │
 │ 5.轮询结果         │                  │                   │
 │──────────────────▶│  POST /v1/asset-groups/             │
 │                   │        validate-result ─────────────▶│
 │                   │   (bytedToken)                       │
 │◀──── GroupId ─────│                  │                   │
 │  （绑定成功）      │                  │                   │

步骤

1. 查询同意状态

curl -H "Authorization: Bearer tr-xxx" \
  https://api.xrtoken.ai/v1/face-consent

{
  "valid": false,
  "need_versions": {
    "policy": "2025-03-01",
    "volc": "2025-01-15"
  }
}

若 valid=true，跳到步骤 3。否则客户端把 need_versions 展示在同意弹窗里。

2. 记录同意

用户点同意后，用拿到的版本号回调：

curl -X POST -H "Authorization: Bearer tr-xxx" \
  -H "Content-Type: application/json" \
  -d '{"policy_version":"2025-03-01","volc_rule_version":"2025-01-15"}' \
  https://api.xrtoken.ai/v1/face-consent

返回 204。版本和 GET 返回的不一致会 400（防止签在老条款上）。

3. 发起扫码会话

curl -X POST -H "Authorization: Bearer tr-xxx" \
  https://api.xrtoken.ai/v1/asset-groups/validate-session

{
  "BytedToken": "eyJhbGci...",
  "RedirectURL": "https://openspeech.bytedance.com/ark/liveness?...",
  "QRCodeDataURL": "data:image/png;base64,iVBOR...",
  "ExpiresIn": 120
}

把 QRCodeDataURL 直接塞到 <img src>。用户手机扫码后跳转到火山 H5 完成活体采集。

4. 轮询结果

用上一步拿到的 BytedToken，建议 每 5 秒 轮询一次，直到终态或 120 秒超时：

curl -X POST -H "Authorization: Bearer tr-xxx" \
  -H "Content-Type: application/json" \
  -d '{"bytedToken":"eyJhbGci..."}' \
  https://api.xrtoken.ai/v1/asset-groups/validate-result

三种终态：

终态	响应体
成功	包含 `GroupId` + `status: "active"`
失败	包含 `ResponseMetadata.Error`
进行中	无 `GroupId`，继续轮询

一旦拿到 GroupId，该真人组已绑定到当前用户，后续 POST /v1/videos/generations 里就能 asset://<GroupId> 引用了。

常见错误

错误码	原因	处理
403 `tier_insufficient`	未开通可信创作者	去控制台申请
403 `enterprise_required`	未完成企业认证	补交企业资料
403 `face_consent_required`	没有有效同意记录	先走步骤 1-2
400 `version_mismatch`	提交的版本号与服务端最新的不一致	重新拉取 `GET /v1/face-consent` 再弹框
502 `upstream_error`	火山侧临时故障	重试

真人扫码活体流程

On this page