Vega Video 活体认证
← 返回 Vega Video 概览,查看版本对比与接入场景。
Endpoint: https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-liveness认证: Tokenhub API Key / Bearer
用现实真人人像作为素材生成视频前,必须先对该人像完成活体认证。认证通过后会返回一个 group_id,用它创建 is_real_person=true 的素材,才能在生视频任务中引用。
只有真人素材需要走这一步
非真人素材(虚拟人、卡通角色、插画等)与通用生视频(纯文本 / 首尾帧 / 不含人脸的素材)都不需要活体认证,直接建素材或直接提交任务即可。
与素材、生视频的闭环关系
完整链路:发起认证 → 手机打开 h5_link 完成人脸验证 → 查认证结果(等 DONE,拿 group_id)→ 建素材 → 查素材 → 创建生视频任务 → 查询任务结果。
| 步骤 | 接口 | 关键产出 |
|---|---|---|
| ① 发起认证 | POST /v1/wand/vega-video-liveness | token_id、h5_link |
| ② 终端用户验证 | 手机打开 h5_link | —(线下动作) |
| ③ 查认证结果 | GET /v1/wand/vega-video-liveness/{token_id} | status=DONE 时返回 group_id |
| ④ 建真人素材 | POST /v1/wand/vega-video-assets | 素材 id(见素材库管理) |
| ⑤ 引用素材生视频 | POST /v1/wand/vega-videos/tasks | 任务 id |
认证针对「人」,不针对「单张图」
一次认证产出一个 group_id,代表「这个真人已通过验证」。同一个人的多张人像素材可以复用同一个 group_id,不必逐张重新认证。
接口列表
| 接口 | 方法 | 路径 | 说明 |
|---|---|---|---|
| 发起认证 | POST | /v1/wand/vega-video-liveness | 创建人脸验证,返回 token_id 与 h5_link |
| 查询认证结果 | GET | /v1/wand/vega-video-liveness/{token_id} | 获取认证状态,DONE 时返回 group_id |
发起认证
创建一次人脸验证,返回验证 Token 与 H5 链接。h5_link 需在手机上打开,由终端用户完成人脸验证动作。
POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-liveness请求参数
请求体所有字段均为可选,允许空体(不传 body,或传 {})。
| 参数名 | 必选 | 类型 | 描述 |
|---|---|---|---|
callback_url | 否 | string | 认证完成后的回调地址,须为 http / https URL。传入非法 URL 直接返回 400。不传则只能通过轮询查询接口获取结果。 |
响应参数
| 参数名 | 类型 | 说明 |
|---|---|---|
token_id | string | 活体验证 Token,作为查询接口的路径参数,用于后续查询认证结果。 |
h5_link | string | 人脸验证链接,需用手机打开完成验证。仅在上游返回非空值时出现。 |
request_id | string | 回显入站 X-Request-Id。仅在调用方传了该请求头时出现。 |
请求示例
curl -sS -X POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-liveness \
-H 'Content-Type: application/json' \
-d '{}'带回调地址:
curl -sS -X POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-liveness \
-H 'Content-Type: application/json' \
-d '{"callback_url":"https://your.service/liveness/callback"}'响应示例
HTTP/1.1 201 Created
Content-Type: application/json{
"token_id": "20260928104501CF8D299E4E2FC3FAB",
"h5_link": "https://face-verify.example.com/h5?accessKeyId=A****V8amxFATDZB4p2zHK4vjnDk****g",
"request_id": "1985e859-2d86-47ce-913b-cd8cc27888bb"
}错误码
| 错误场景 | HTTP | error.code |
|---|---|---|
X-Appid 缺失 / 非正整数 | 400 | invalid_request_error |
| 请求体 JSON 解析失败 | 400 | invalid_request_error |
callback_url 非 http/https URL | 400 | invalid_request_error |
| 上游拒绝(无操作权限) | 403 | permission_denied |
| 服务内部故障 | 500 | internal_error |
查询认证结果
查询一次人脸验证的当前状态。终端用户在 H5 页面完成验证前状态为 WAIT,需轮询至 DONE 才能拿到 group_id。
GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-liveness/{token_id}请求参数
| 参数名 | 必选 | 类型 | 描述 |
|---|---|---|---|
token_id | 是 | string | 活体验证 Token(路径参数),即发起认证时返回的 token_id。 |
响应参数
| 参数名 | 类型 | 说明 |
|---|---|---|
token_id | string | 活体验证 Token。 |
status | string | 认证状态。取值:WAIT(认证中)、DONE(认证成功)、FAIL(认证失败)。 |
group_id | string | 素材组 ID,仅用于上传已通过认证的人物相关素材。认证成功后出现;WAIT 期间通常不出现。 |
message | string | 错误信息或附加说明。仅在上游返回非空值时出现。 |
request_id | string | 回显入站 X-Request-Id。仅在调用方传了该请求头时出现。 |
status 状态说明
status | 含义 | 处理建议 |
|---|---|---|
WAIT | 认证中,终端用户尚未完成人脸验证 | 每 3~5 秒轮询一次。 |
DONE | 认证成功 | 取 group_id,用于创建 is_real_person=true 的真人素材。 |
FAIL | 认证失败 | 读取 message 定位原因;重新发起认证获取新的 token_id 与 h5_link。 |
FAIL 不可重试同一个 token
认证失败后原 token_id 与 h5_link 作废,必须重新调用发起认证接口拿一组新的,不能让用户重新打开旧链接。
请求示例
curl -sS https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-liveness/20260928104501CF8D299E4E2FC3FAB响应示例
轮询期间可能依次拿到以下响应。
认证中:
{
"token_id": "20260928104501CF8D299E4E2FC3FAB",
"status": "WAIT",
"request_id": "1985e859-2d86-47ce-913b-cd8cc27888bb"
}认证成功:
{
"token_id": "20260928104501CF8D299E4E2FC3FAB",
"status": "DONE",
"group_id": "group-20260928104812-mfz6m",
"message": "ok",
"request_id": "2f7a8b3c-5e91-4d02-b643-de9ff134a77e"
}错误码
| 错误场景 | HTTP | error.code |
|---|---|---|
X-Appid 缺失 / 非正整数 | 400 | invalid_request_error |
路径 token_id 为空(/v1/wand/vega-video-liveness 或 /v1/wand/vega-video-liveness/) | 400 | invalid_request_error |
| 上游拒绝(无操作权限) | 403 | permission_denied |
| 上游报 Token 不存在 | 404 | not_found |
| 服务内部故障 | 500 | internal_error |
完整调用示例
# 1. 发起认证
curl -sS -X POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-liveness \
-H 'Content-Type: application/json' \
-d '{"callback_url":"https://your.service/liveness/callback"}'
# 响应示例:
# {"token_id":"20260928104501CF8D299E4E2FC3FAB",
# "h5_link":"https://face-verify.example.com/h5?..."}
TOKEN=20260928104501CF8D299E4E2FC3FAB # 替换为上一步返回的 token_id
# 2. 用手机打开 h5_link 完成人脸验证,同时轮询直至 status=DONE
curl -sS https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-liveness/$TOKEN
# 期望:{"token_id":"...","status":"DONE","group_id":"group-20260928104812-mfz6m"}
# 3. 用认证返回的 group_id 建真人素材
curl -sS -X POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets \
-H 'Content-Type: application/json' \
-d '{
"action": "create",
"url": "https://example.com/real-person.jpg",
"asset_type": "Image",
"group_id": "group-20260928104812-mfz6m",
"is_real_person": true
}'
# 期望:{"id":"asset-...","group_id":"group-20260928104812-mfz6m"}拿到素材 id 后,在生视频请求的 content[].image_url.url 里填 asset://<id> 即可引用,详见素材库管理与各版本接口文档。
注意事项
| 约束 | 说明 |
|---|---|
h5_link 须在手机上打开 | 人脸验证依赖移动端摄像头,桌面浏览器无法完成。 |
group_id 只有 DONE 才有 | 认证未完成(WAIT)时不返回 group_id,此时创建 is_real_person=true 的素材会被上游拒绝。 |
不传 callback_url 只能轮询 | 回调地址非必填,但不传时只能靠轮询查询接口感知状态变化。 |
| 认证能力需单独开通 | 未开通的 AppId 调用返回 403 permission_denied,请联系对接人。 |
统一错误码
所有请求级失败均返回同一套错误信封,词表与素材接口、生视频接口共用,见概览页的统一错误码。
{
"error": {
"code": "<错误码>",
"message": "<错误描述>"
},
"request_id": "<回显入站 X-Request-Id;未传该请求头时字段缺省>"
}| HTTP 状态码 | error.code | 触发条件 |
|---|---|---|
| 400 | invalid_request_error | 缺少必填项、JSON 解析失败、callback_url 非法、路径 token_id 为空等 |
| 403 | permission_denied | 上游报「无操作权限」(AppId 未开通相应能力) |
| 404 | not_found | Token 不存在 |
| 413 | request_too_large | 请求体超过 1 MiB(POST 路由),或上游响应体超过 1 MiB |
| 500 | internal_error | 服务内部故障。message 固定为 internal error,不透出内部细节 |
| 503 | service_unavailable | 服务过载;message 为 service overloaded |
相关文档
| 文档 | 说明 |
|---|---|
| Vega Video 概览 | 版本选型、接入场景、统一错误码 |
| 素材库管理 | 建素材 / 查素材 / 删素材 |
| Vega-Video 1.5 Pro | 支持 asset:// 引用的最高规格版本 |
| Vega-Video 1.0 Pro 系列 | 支持 asset:// 引用的 1.0 代版本 |