# 发起真人活体认证会话

为终端用户发起一次 BytePlus/Volcengine Ark 真人活体认证。返回 H5 链接、轮询用的 BytedToken、回调地址，以及一个预渲染的 QR 码（PNG base64 data URL），集成方可以直接嵌入 `<img>` 展示给终端用户扫码完成活体。

调用前账户需满足：已开通可信创作者（trusted_creator）+ 已完成企业认证。

**第三方 SaaS 集成方** 可在 body 中带 `callback_url` + `external_user_id`：
- 带了 `callback_url` 后，end-user 完成时我们 302 跳转到你的 `callback_url`（带 `group_id` / `status` / `external_user_id`）。轮询仍可用作兜底。
- 创建时传的 `external_user_id` 不会自动绑到 BytedToken。走轮询时 `validate-result` 必须再传同一个值。
- 后续 list / get / update / delete 必须传同一个 `external_user_id`。完整说明见 [素材库 · external_user_id](/docs/asset-library#external-user-id)。

## POST /v1/asset-groups/validate-session

> 发起真人活体认证会话

为终端用户发起一次 BytePlus/Volcengine Ark 真人活体认证。返回 H5 链接、轮询用的 BytedToken、回调地址，以及一个预渲染的 QR 码（PNG base64 data URL），集成方可以直接嵌入 `<img>` 展示给终端用户扫码完成活体。

调用前账户需满足：已开通可信创作者（trusted_creator）+ 已完成企业认证。

**第三方 SaaS 集成方** 可在 body 中带 `callback_url` + `external_user_id`：
- 不再需要 `validate-result` 轮询 — 我们会在 end-user 完成时自动 302 跳转到你的 `callback_url`（带 `group_id` / `status` / `external_user_id`）。
- 把生成的 GroupId 绑定到你租户下的具体 end-user, 后续 list / get / update / delete 自动隔离。

### Authentication

`Authorization: Bearer tr-xxx`

### Request Body

Content-Type: `application/json`

- **callback_url** `string`  
  终端用户完成 H5 验证后跳转的目标地址。必须是 `http(s)` 且带 host。
- **external_user_id** `string`  
  第三方 SaaS 终端用户标识符（opaque 字符串，≤128 字符，可选）。跟随生成的 GroupId 一起持久化到 `user_asset_groups`，后续 CRUD 必须传同一个值才能看到这个 group。
- **model** `string`  
  可选。命中 explicit relay 渠道 (如 doubao-seedance-2-0-pro) 时,

### Response

- **ResponseMetadata** `object`  
  Ark 请求元数据
- **Result** `object`  
  
- **Result.H5Link** `string`  
  活体认证页面的 H5 链接，120 秒内有效。终端用户在手机浏览器中打开此链接完成面部识别。
- **Result.BytedToken** `string`  
  本次认证的唯一凭证标识。用于后续调用 validate-result 查询结果，120 秒有效。
- **Result.CallbackURL** `string`  
  活体认证完成后 H5 页面会跳转的回调 URL（XRToken 前端的 verify-callback 页）。
- **Result.QRCodeDataURL** `string`  
  H5Link 编码成的 QR 码，base64 编码的 PNG 图，512×512 像素，格式 `data:image/png;base64,...`。集成方可直接放入 `<img src={QRCodeDataURL}>` 展示给终端用户扫描。

### Error Codes

- `401`: 
- `403`: 权限不足（tier_insufficient / enterprise_required）
- `502`: