Create Verification Session (Custom Callback)

POST /api/volc-user/visual-validate-sessions/custom-callback

Create an H5 verification link. Once the platform processes the result, the browser is redirected to your application with HTTP 302.

Authentication

Use a logged-in session Cookie or the Authorization: <access_token> header. Obtain the access token through Generate Access Token. It is different from the sk- key used for model requests.

Request Parameters

Name	Type	Required	Description
name	string	Required	Asset group name after verification; must not be blank after trimming
description	string	Optional	Asset group description after verification
customCallbackURL	string	Required	Absolute http/https URL of the receiving endpoint; it may share the platform hostname and must still pass platform URL access rules

Request Example

POST /api/volc-user/visual-validate-sessions/custom-callback
Authorization: <access_token>
Content-Type: application/json

{
  "name": "Performer Asset Group",
  "description": "For authorized video generation",
  "customCallbackURL": "https://customer.example.com/verification/done?orderId=demo-001"
}

Response Fields (200)

Name	Type	Description
success	boolean	Business success flag; check it even for HTTP 200
message	string	Message; empty on success
data	object	Response data on success
data.platformSessionId	string	Platform session ID used to query the result
data.status	string	Pending, Processing, Succeeded, Failed, or Expired; see Integration Guide
data.h5Link	string	Returned only while Pending and unexpired; the person being verified must open it
data.expiresAt	integer	Link expiry time in Unix seconds; sessions currently expire 120 seconds after creation
data.groupId	string	Platform asset group ID after success; omitted when absent or, for queries, when the group has been deleted
data.resultCode	string	H5 verification result code, if present; 10000 indicates verification success
data.errorCode	string	Error code, if present
data.errorMessage	string	Error message, if present
data.createTime	integer	Creation time in Unix seconds
data.updateTime	integer	Update time in Unix seconds
data.customerRedirectURL	string	Customer redirect URL after completion; omitted while Pending

Response Example

{
  "success": true,
  "message": "",
  "data": {
    "platformSessionId": "vvs-example",
    "status": "Pending",
    "expiresAt": 1792022520,
    "createTime": 1792022400,
    "updateTime": 1792022400,
    "h5Link": "https://example.com/visual-validate?token=example"
  }
}

Customer Callback Parameters

The current implementation sends the following Query parameters through a browser HTTP 302 redirect. It does not send a server-side Webhook. Existing Query parameters are preserved; avoid predefining the reserved names below.

Name	Description
platformSessionId	Platform session ID returned at creation
status	Succeeded on success or Failed on verification/processing failure
resultCode	H5 result code; 10000 on verification success, but it may remain on later processing failure, so also check status
assetGroupId	Platform group ID appended on success; corresponds to groupId in session queries
errorCode / errorMessage	Error code and message appended on failure

GET /verification/done?orderId=demo-001&platformSessionId=vvs-example&status=Succeeded&resultCode=10000&assetGroupId=group-example

Creation returns platformSessionId; the detail and list queries both return sessionId. Save the ID at creation and use it with Query Verification Session to confirm the result. Queries do not return customerRedirectURL.

Browser URL parameters can be modified. Treat the authenticated session query as authoritative and process each session ID idempotently. A closed browser, interrupted network, or invalid callback rejected by the platform can prevent the redirect; query the session to recover its result.