Vega Video liveness verification โ
โ Back to the Vega Video overview for version comparison and integration paths.
Endpoint: https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-livenessAuthentication: Tokenhub API Key / Bearer
Before generating video from a photograph of a real person, that person must pass liveness verification. A successful verification returns a group_id; use it to create a material with is_real_person=true, which is the only way such a material can be referenced in a video task.
Only real-person material needs this step
Non-real-person material (virtual humans, cartoon characters, illustrations, etc.) and general video generation (plain text / first-and-last frame / materials without faces) do not require liveness verification โ just create the material or submit the task directly.
How it closes the loop with materials and video generation โ
The full chain is start verification โ open h5_link on a phone and complete the face check โ query the result (wait for DONE, take group_id) โ create the material โ query the material โ create the video task โ query the result.
| Step | Endpoint | Key output |
|---|---|---|
| โ Start verification | POST /v1/wand/vega-video-liveness | token_id, h5_link |
| โก End user verifies | Open h5_link on a phone | โ (offline action) |
| โข Query the result | GET /v1/wand/vega-video-liveness/{token_id} | group_id once status=DONE |
| โฃ Create real-person material | POST /v1/wand/vega-video-assets | Material id (see Material management) |
| โค Generate video from it | POST /v1/wand/vega-videos/tasks | Task id |
Verification is per person, not per image
One verification yields one group_id, meaning "this real person has been verified". Multiple portrait materials of the same person can reuse that group_id โ there is no need to re-verify image by image.
Endpoints โ
| Operation | Method | Path | Description |
|---|---|---|---|
| Start verification | POST | /v1/wand/vega-video-liveness | Create a face check; returns token_id and h5_link |
| Query the result | GET | /v1/wand/vega-video-liveness/{token_id} | Get the verification status; returns group_id when DONE |
Start verification โ
Create one face check, returning a verification token and an H5 link. The h5_link must be opened on a mobile phone, where the end user performs the face-check actions.
POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-livenessRequest parameters โ
Every body field is optional, and an empty body is allowed (send no body, or {}).
| Parameter | Required | Type | Description |
|---|---|---|---|
callback_url | No | String | Callback address invoked when verification finishes; must be an http / https URL. An invalid URL returns 400 outright. Without it, polling the query endpoint is the only way to obtain the result. |
Response parameters โ
| Parameter | Type | Description |
|---|---|---|
token_id | String | Liveness verification token; used as the path parameter of the query endpoint. |
h5_link | String | Face-check link, to be opened on a phone. Present only when the upstream returns a non-empty value. |
request_id | String | Echo of the inbound X-Request-Id. Present only when the caller sent that header. |
Request examples โ
curl -sS -X POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-liveness \
-H 'Content-Type: application/json' \
-d '{}'With a callback address:
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"}'Response example โ
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"
}Error codes โ
| Scenario | HTTP | error.code |
|---|---|---|
X-Appid missing / not a positive integer | 400 | invalid_request_error |
| Request body JSON parse failure | 400 | invalid_request_error |
callback_url not an http/https URL | 400 | invalid_request_error |
| Upstream rejection (no permission) | 403 | permission_denied |
| Internal service failure | 500 | internal_error |
Query the verification result โ
Query the current status of one face check. Until the end user completes the check on the H5 page the status is WAIT; poll until DONE to obtain the group_id.
GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-liveness/{token_id}Request parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
token_id | Yes | String | Liveness verification token (path parameter), i.e. the token_id returned when the verification was started. |
Response parameters โ
| Parameter | Type | Description |
|---|---|---|
token_id | String | Liveness verification token. |
status | String | Verification status: WAIT (in progress), DONE (verified), FAIL (failed). |
group_id | String | Material group ID, used only for uploading materials of the verified person. Appears after a successful verification; usually absent during WAIT. |
message | String | Error message or extra note. Present only when the upstream returns a non-empty value. |
request_id | String | Echo of the inbound X-Request-Id. Present only when the caller sent that header. |
status reference โ
status | Meaning | Recommended handling |
|---|---|---|
WAIT | In progress; the end user has not finished the face check | Poll every 3โ5 seconds. |
DONE | Verified | Take group_id and use it to create an is_real_person=true material. |
FAIL | Verification failed | Read message to diagnose; start a new verification to get a fresh token_id and h5_link. |
A FAIL token cannot be retried
After a failure the original token_id and h5_link are void. Call the start endpoint again for a fresh pair โ do not ask the user to reopen the old link.
Request example โ
curl -sS https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-liveness/20260928104501CF8D299E4E2FC3FABResponse examples โ
While polling you may see the following responses in sequence.
In progress:
{
"token_id": "20260928104501CF8D299E4E2FC3FAB",
"status": "WAIT",
"request_id": "1985e859-2d86-47ce-913b-cd8cc27888bb"
}Verified:
{
"token_id": "20260928104501CF8D299E4E2FC3FAB",
"status": "DONE",
"group_id": "group-20260928104812-mfz6m",
"message": "ok",
"request_id": "2f7a8b3c-5e91-4d02-b643-de9ff134a77e"
}Error codes โ
| Scenario | HTTP | error.code |
|---|---|---|
X-Appid missing / not a positive integer | 400 | invalid_request_error |
Path token_id empty (/v1/wand/vega-video-liveness or /v1/wand/vega-video-liveness/) | 400 | invalid_request_error |
| Upstream rejection (no permission) | 403 | permission_denied |
| Upstream reports the token does not exist | 404 | not_found |
| Internal service failure | 500 | internal_error |
End-to-end example โ
# 1. Start verification
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"}'
# example response:
# {"token_id":"20260928104501CF8D299E4E2FC3FAB",
# "h5_link":"https://face-verify.example.com/h5?..."}
TOKEN=20260928104501CF8D299E4E2FC3FAB # replace with the token_id returned above
# 2. Open h5_link on a phone to complete the face check, polling until status=DONE
curl -sS https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-liveness/$TOKEN
# expect: {"token_id":"...","status":"DONE","group_id":"group-20260928104812-mfz6m"}
# 3. Create the real-person material with the returned 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
}'
# expect: {"id":"asset-...","group_id":"group-20260928104812-mfz6m"}Once you have the material id, reference it as asset://<id> in content[].image_url.url of the video request โ see Material management and the per-version references.
Things to watch out for โ
| Constraint | Detail |
|---|---|
h5_link must be opened on a phone | The face check needs a mobile camera; a desktop browser cannot complete it. |
group_id exists only when DONE | While verification is incomplete (WAIT) no group_id is returned, and creating an is_real_person=true material at that point is rejected upstream. |
Without callback_url you must poll | The callback address is optional, but without it polling the query endpoint is the only way to observe status changes. |
| The capability must be enabled separately | An AppId without it receives 403 permission_denied โ contact your WAND representative. |
Unified error codes โ
All request-level failures return the same error envelope, sharing one vocabulary with the material and video-generation endpoints โ see the unified error codes on the overview page.
{
"error": {
"code": "<error code>",
"message": "<error description>"
},
"request_id": "<echo of the inbound X-Request-Id; omitted when the header is absent>"
}| HTTP status | error.code | Trigger |
|---|---|---|
| 400 | invalid_request_error | Missing required field, JSON parse failure, invalid callback_url, empty path token_id, etc. |
| 403 | permission_denied | Upstream reports "no permission" (the AppId lacks the capability) |
| 404 | not_found | The token does not exist |
| 413 | request_too_large | Request body over 1 MiB (POST routes), or upstream response body over 1 MiB |
| 500 | internal_error | Internal service failure. message is always internal error, with no internal detail exposed |
| 503 | service_unavailable | Service overloaded; message is service overloaded |
Related documents โ
| Document | Description |
|---|---|
| Vega Video overview | Version selection, integration paths, unified error codes |
| Material management | Create / query / delete materials |
| Vega-Video 1.5 Pro | The top-spec version with asset:// support |
| Vega-Video 1.0 Pro series | The 1.0-generation versions with asset:// support |