Real-person liveness flow

Real-person liveness is the gate for unlocking XRToken's digital-human capability: once an end user scans a QR and completes Volcengine's liveness capture, the resulting AssetGroup is bound to the caller's user account, and video-generation requests can then reference that person via asset://<groupId>.

The full flow is just the two Volcengine request endpoints below — call them in order.

Prerequisites

Calling these endpoints requires:

These are platform-side reviews, done once — no need to repeat them on every call.

Steps

1. Open a scan session

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
}

Drop QRCodeDataURL straight into an <img src>. The end user scans it on their phone and completes the liveness capture on Volcengine's H5.

2. Poll for the result

Using the BytedToken from step 1, poll every 5 s until a terminal state or the 120 s timeout:

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

Three terminal outcomes:

Once you see GroupId, the real-person group is already bound to the caller's user. Subsequent POST /v1/videos/generations calls can reference it via asset://<GroupId>.

If one API key serves many end-users, send the same external_user_id on both the session and every poll. Request examples: Asset library · external_user_id.

Common errors