Liveness Verification

SilvaMux provides the same "real-person verification" face liveness API as Volcengine. Customers can launch the Volcengine H5 liveness page, and after the user verifies in person, their front-face asset is ingested as a real-person asset (LivenessFace), then referenced in video generation via asset://<Id> — closing the loop of a private real-person likeness library:

Launch liveness H5 → user completes verification → callback → get real-person asset group → upload real-person assets → generate video

The API behaves the same as Volcengine's "manage private asset libraries" (Launch real-person verification H5 (CreateVisualValidateSession)); only the endpoint points at this platform, and authentication uses platform-issued AK/SK.

Preparation

1. Console → Credentials → create a Volcengine compatible (AK/SK) credential; the AK and SK are returned once (the SK is visible only then).
2. AK/SK are bound to the organization; the project is selected via the ProjectName field (empty or default uses the default project).
3. Use the official Volcengine SDK or a custom V4 signature, sending requests to this platform:

Overall Flow

① Create a Verification Session — CreateVisualValidateSession

POST /api/ark?Action=CreateVisualValidateSession&Version=2024-01-01

Request body:

{
  "CallbackURL": "https://your-host.example/callback",
  "ProjectName": "default"
}

The request is signed with platform-issued AK/SK using Volcengine V4 signing (Service=ark, Region=cn-beijing, Version=2024-01-01); see the integration notes in Asset Management for signing details.

Response:

{
  "ResponseMetadata": {
    "RequestId": "3f2f8b4d1a6e4c5b9a7d0e2f1c3b4a5d",
    "Action": "CreateVisualValidateSession",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "H5Link": "https://... (the Volcengine H5 liveness page)",
    "BytedToken": "VVS-01JXXXXXXXXXXXXXX"
  }
}

The H5 link is single-use and the session is valid for 30 minutes.

② Verification Callback

After the user completes liveness actions (blinking, head turns, etc.) on H5Link, Volcengine redirects their browser to the platform callback; the platform records the result, then serves an HTML page that automatically forwards the browser to your CallbackURL with these parameters appended:

Your callback service can show the "verification result" and then call GetVisualValidateResult to formally obtain the asset group.

③ Get the Real-Person Asset Group — GetVisualValidateResult

POST /api/ark?Action=GetVisualValidateResult&Version=2024-01-01

Request body:

{
  "BytedToken": "VVS-01JXXXXXXXXXXXXXX"
}

Response:

{
  "ResponseMetadata": { "Action": "GetVisualValidateResult", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" },
  "Result": { "GroupId": "group-01JXXXXXXXXXXXXXX" }
}

On success the platform creates and returns a LivenessFace real-person asset group (GroupId); the group is backed by a real upstream real-person group whose id clients never need to know.

④ Upload Real-Person Assets — CreateAsset

POST /api/ark?Action=CreateAsset&Version=2024-01-01

Request body:

{
  "GroupId": "group-01JXXXXXXXXXXXXXX",
  "URL": "https://your-host.example/face.jpg",
  "AssetType": "Image",
  "Name": "my-face"
}

Response:

{
  "ResponseMetadata": { "Action": "CreateAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" },
  "Result": { "Id": "<real upstream asset id>" }
}

The platform routes the upstream group automatically by the target group's type: pointing at a LivenessFace group uploads to the real-person upstream — you don't need to (and shouldn't) pass GroupType. Pointing at a normal AIGC group ingests into the organization-level AIGC group; the two never mix. The organization needs the AVGV2 capability, otherwise the call returns 403 SubscriptionRequired.

⑤ Manage Real-Person Assets

Query Status — GetAsset

POST /api/ark?Action=GetAsset&Version=2024-01-01

Request body: { "Id": "<asset id>", "ProjectName": "default" }

Result.Status: Processing / Active / Failed. Assets usually start as Processing; poll until Active before using them in video generation.

List Assets — ListAssets

POST /api/ark?Action=ListAssets&Version=2024-01-01

The request body supports Filter (GroupIds, GroupType, Statuses, Name), pagination (PageNumber/PageSize, max 100), and sorting (SortBy/SortOrder, e.g. SortBy=CreateTime&SortOrder=Desc). Passing LivenessFace as Filter.GroupType lists only real-person assets.

Delete Assets — DeleteAsset

POST /api/ark?Action=DeleteAsset&Version=2024-01-01

Request body: { "Id": "<asset id>", "ProjectName": "default" }. Deletes both the Volcengine upstream asset and the local record synchronously.

Referencing in Video Generation

Once a real-person asset is Active, reference it in video generation's content via asset://<asset id>:

{
  "model": "<MODEL_CALL_NAME>",
  "content": [
    {"type": "image_url", "image_url": {"url": "asset://<asset id>"}, "role": "reference_image"},
    {"type": "text", "text": "Make the character in the frame dance"}
  ]
}

Video generation uses the platform's own API + API key (sk_live_), not AK/SK signing; model uses the real call name from the Model Plaza. See Video Generation API.

Error Codes

Notes

• H5 is single-use with a 30-minute validity: H5Link can be used once and the session lives 30 minutes; create a new session after timeout.
• The callback URL must be publicly reachable: Volcengine calls back via browser redirects; localhost/intranet addresses do not work.
• Asset URLs must be publicly accessible: the platform fetches assets to ingest them; localhost/intranet addresses do not work.
• Assets must be your own front face: comply with applicable laws, regulations, and the platform's terms of service; do not upload other people's likenesses.
• Assets are isolated per project: upload and query must use the same ProjectName; video generation must use the project the asset belongs to.

References

• This platform's Asset Management and Video Generation API
• Volcengine official docs: Launch real-person verification H5 (CreateVisualValidateSession), Private real-person likeness asset usage guide