Create a visual validation session

Availability

This page documents the Modelflare asset-management route. Calls require a valid media API key, an available media channel, and the required permission.

Note

The gateway records provider asset IDs, status, and user ownership. The Castaly local library remains separate from the provider asset namespace.

Endpoint

POST https://modelflare.dev/volc/asset/CreateVisualValidateSession

Authentication

Use a Modelflare API key:

bash

-H "Authorization: Bearer YOUR_MODELFLARE_API_KEY"

Send Idempotency-Key with create, update, and delete requests. Retrying the same key for the same user replays the saved response without repeating the mutation.

Request

Create a mobile liveness session. The user opens the returned H5Link to complete the identity check.

Field	Type	Required	Description	Example
CallbackURL	string	No	Optional callback URL for validation events.	https://example.com/callback

JSON example:

JSON

{
  "CallbackURL": "https://example.com/callback"
}

cURL example:

bash

curl --request POST https://modelflare.dev/volc/asset/CreateVisualValidateSession \
  --header "Authorization: Bearer YOUR_MODELFLARE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "CallbackURL": "https://example.com/callback"
}'

Response

The validation session was created.

Field	Type	Required	Description	Example
BytedToken	string	Yes	Temporary token used with GetVisualValidateResult.	2026070222152680501D985EA34A3BE3D8
CallbackURL	string	No	The callback URL supplied in the request.	https://example.com/callback
H5Link	string	Yes	Mobile liveness page URL.	https://example.com/liveness-session

Response example:

JSON

{
  "BytedToken": "2026070222152680501D985EA34A3BE3D8",
  "CallbackURL": "https://example.com/callback",
  "H5Link": "https://example.com/liveness-session"
}

Errors

Status	Meaning
400	The request is invalid.
401	The API key is missing or unauthorized.

Error body example (when returned):

JSON

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed."
  }
}

Image, video, and audio creation are asynchronous. After receiving an asset ID, call GetAsset and use the asset://<ID> reference only when the status is Active.