Skip to content

Vega Video liveness verification โ€‹

Updated

โ† 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.

StepEndpointKey output
โ‘  Start verificationPOST /v1/wand/vega-video-livenesstoken_id, h5_link
โ‘ก End user verifiesOpen h5_link on a phoneโ€” (offline action)
โ‘ข Query the resultGET /v1/wand/vega-video-liveness/{token_id}group_id once status=DONE
โ‘ฃ Create real-person materialPOST /v1/wand/vega-video-assetsMaterial id (see Material management)
โ‘ค Generate video from itPOST /v1/wand/vega-videos/tasksTask 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 โ€‹

OperationMethodPathDescription
Start verificationPOST/v1/wand/vega-video-livenessCreate a face check; returns token_id and h5_link
Query the resultGET/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-liveness

Request parameters โ€‹

Every body field is optional, and an empty body is allowed (send no body, or {}).

ParameterRequiredTypeDescription
callback_urlNoStringCallback 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 โ€‹

ParameterTypeDescription
token_idStringLiveness verification token; used as the path parameter of the query endpoint.
h5_linkStringFace-check link, to be opened on a phone. Present only when the upstream returns a non-empty value.
request_idStringEcho of the inbound X-Request-Id. Present only when the caller sent that header.

Request examples โ€‹

bash
curl -sS -X POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-liveness \
  -H 'Content-Type: application/json' \
  -d '{}'

With a callback address:

bash
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
HTTP/1.1 201 Created
Content-Type: application/json
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 โ€‹

ScenarioHTTPerror.code
X-Appid missing / not a positive integer400invalid_request_error
Request body JSON parse failure400invalid_request_error
callback_url not an http/https URL400invalid_request_error
Upstream rejection (no permission)403permission_denied
Internal service failure500internal_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 โ€‹

ParameterRequiredTypeDescription
token_idYesStringLiveness verification token (path parameter), i.e. the token_id returned when the verification was started.

Response parameters โ€‹

ParameterTypeDescription
token_idStringLiveness verification token.
statusStringVerification status: WAIT (in progress), DONE (verified), FAIL (failed).
group_idStringMaterial group ID, used only for uploading materials of the verified person. Appears after a successful verification; usually absent during WAIT.
messageStringError message or extra note. Present only when the upstream returns a non-empty value.
request_idStringEcho of the inbound X-Request-Id. Present only when the caller sent that header.

status reference โ€‹

statusMeaningRecommended handling
WAITIn progress; the end user has not finished the face checkPoll every 3โ€“5 seconds.
DONEVerifiedTake group_id and use it to create an is_real_person=true material.
FAILVerification failedRead 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 โ€‹

bash
curl -sS https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-liveness/20260928104501CF8D299E4E2FC3FAB

Response examples โ€‹

While polling you may see the following responses in sequence.

In progress:

json
{
  "token_id": "20260928104501CF8D299E4E2FC3FAB",
  "status": "WAIT",
  "request_id": "1985e859-2d86-47ce-913b-cd8cc27888bb"
}

Verified:

json
{
  "token_id": "20260928104501CF8D299E4E2FC3FAB",
  "status": "DONE",
  "group_id": "group-20260928104812-mfz6m",
  "message": "ok",
  "request_id": "2f7a8b3c-5e91-4d02-b643-de9ff134a77e"
}

Error codes โ€‹

ScenarioHTTPerror.code
X-Appid missing / not a positive integer400invalid_request_error
Path token_id empty (/v1/wand/vega-video-liveness or /v1/wand/vega-video-liveness/)400invalid_request_error
Upstream rejection (no permission)403permission_denied
Upstream reports the token does not exist404not_found
Internal service failure500internal_error

End-to-end example โ€‹

bash
# 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 โ€‹

ConstraintDetail
h5_link must be opened on a phoneThe face check needs a mobile camera; a desktop browser cannot complete it.
group_id exists only when DONEWhile 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 pollThe callback address is optional, but without it polling the query endpoint is the only way to observe status changes.
The capability must be enabled separatelyAn 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.

json
{
  "error": {
    "code": "<error code>",
    "message": "<error description>"
  },
  "request_id": "<echo of the inbound X-Request-Id; omitted when the header is absent>"
}
HTTP statuserror.codeTrigger
400invalid_request_errorMissing required field, JSON parse failure, invalid callback_url, empty path token_id, etc.
403permission_deniedUpstream reports "no permission" (the AppId lacks the capability)
404not_foundThe token does not exist
413request_too_largeRequest body over 1 MiB (POST routes), or upstream response body over 1 MiB
500internal_errorInternal service failure. message is always internal error, with no internal detail exposed
503service_unavailableService overloaded; message is service overloaded
DocumentDescription
Vega Video overviewVersion selection, integration paths, unified error codes
Material managementCreate / query / delete materials
Vega-Video 1.5 ProThe top-spec version with asset:// support
Vega-Video 1.0 Pro seriesThe 1.0-generation versions with asset:// support

Built with VitePress ยท Deployed on Tencent EdgeOne Pages