Skip to main content
POST
/
api
/
v1
/
client
/
job
/
visual-validate-session
Create a real-person H5 validation session
curl --request POST \
  --url https://api.crun.ai/api/v1/client/job/visual-validate-session \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "callback_url": "https://example.com/callback/seedance-visual-validation"
}
'
{
  "code": 200,
  "message": "success",
  "data": {
    "BytedToken": "202603311449168C23BA26**************",
    "H5Link": "https://visual.volcengine.com/validate?...&bytedToken=202603311449168C23BA26**************&lng=zh",
    "CallbackURL": "https://example.com/callback/seedance-visual-validation"
  }
}

​
Overview

Use this flow when you need to upload real-person portrait assets into a private Seedance asset group. The validation step creates an Asset Group ID that is bound to one real person. After you get the GroupId, upload the person’s image, video, or audio assets with Seedance Asset Upload API by passing group_id.

​
Flow

  1. Call POST /api/v1/client/job/visual-validate-session with your callback_url.
  2. Open the returned H5Link for the end user and complete real-person face validation.
  3. After validation, the H5 page redirects to your callback_url with result parameters such as bytedToken and resultCode.
  4. When resultCode is 10000, call GET /api/v1/client/job/visual-validate-result with the byted_token to obtain GroupId.
  5. Call Seedance Asset Upload API and pass the returned GroupId as group_id. The upload flow is then the same as regular asset upload.
  6. Poll Seedance Asset Info API until Status becomes Active, then use the returned AssetId in Seedance generation requests.
The H5 validation link is valid for 120 seconds. If validation fails or the link expires, create a new validation session.
You can set the page language by appending or updating the lng parameter in H5Link. Supported values are zh, en, and zh-Hant; the default is zh.

​
Step 1: Create Validation Session

Call this endpoint to create a Volcengine H5 validation link.

​
Request Body

​
callback_url
string
required
Callback URL opened after the end user completes the H5 validation page. The callback receives validation result parameters.

​
Request Example

{
  "callback_url": "https://example.com/callback/seedance-visual-validation"
}

​
Response Example

{
  "code": 200,
  "message": "success",
  "data": {
    "BytedToken": "202603311449168C23BA26**************",
    "H5Link": "https://visual.volcengine.com/validate?...&bytedToken=202603311449168C23BA26**************&lng=zh",
    "CallbackURL": "https://example.com/callback/seedance-visual-validation"
  }
}

​
Callback Parameters

After the user completes validation, the H5 page redirects to your callback URL. A successful callback commonly looks like: 
https://example.com/callback/seedance-visual-validation?bytedToken=********&resultCode=10000&algorithmBaseRespCode=0&reqMeasureInfoValue=1&verify_type=real_time
ParameterDescription
bytedTokenUnique credential for this validation. Use it as byted_token when querying the validation result.
resultCodeValidation result. 10000 means validation passed.
algorithmBaseRespCodeService-side sub error code. Check it when resultCode indicates a server-side error.
verify_typeValidation type. Current value is real_time.

​
Step 2: Get Validation Result

Call this endpoint after the callback indicates that validation passed. It returns the GroupId created for this real person.

​
Query Parameters

​
byted_token
string
required
BytedToken returned by the validation session endpoint or bytedToken received in your callback URL.

​
Request Example

curl -X GET "https://api.crun.ai/api/v1/client/job/visual-validate-result?byted_token=202603311449168C23BA26**************" \
  -H "X-API-KEY: YOUR_API_KEY"

​
Response Example

{
  "code": 200,
  "message": "success",
  "data": {
    "GroupId": "group-20260331145705-*****"
  }
}

​
Step 3: Upload Assets To Group

Use the returned GroupId as group_id when uploading assets: 
{
  "name": "fashion-model-front",
  "asset_type": "Image",
  "asset_url": "https://example.com/assets/fashion-model-front.jpg",
  "group_id": "group-20260331145705-*****"
}
Each real-person Asset Group is bound to one real face. When an asset is uploaded to the group, the upstream service compares the uploaded face with the baseline face collected during validation. The upload may fail if the asset is not the same person or if multiple faces are detected.

Asset Upload

Upload image, video, and audio assets, including real-person assets with group_id

Asset Info

Query upload status and wait for the asset to become active

Authorizations

​
x-api-key
string
header
required

All APIs require authentication via API Key.

Get API Key:

  1. Visit API Key Management Page to get your API Key

Usage: Add to request header:

x-api-key: YOUR_API_KEY

Note:

  • Keep your API Key secure and do not share it with others
  • If you suspect your API Key has been compromised, reset it immediately in the management page

Body

application/json
​
callback_url
string<uri>
required

Callback URL opened after the end user completes H5 validation. The callback receives validation result parameters such as bytedToken and resultCode.

Example:

"https://example.com/callback/seedance-visual-validation"

Response

Validation session created

​
code
enum<integer>

Response status code

  • 200: Success - Request has been processed successfully
  • 401: Unauthorized - Authentication credentials are missing or invalid
  • 402: Insufficient Credits - Account does not have enough credits to perform the operation
  • 404: Not Found - The requested resource or endpoint does not exist
  • 422: Validation Error - The request parameters failed validation checks
  • 429: Rate Limited - Request limit has been exceeded for this resource
  • 455: Service Unavailable - System is currently undergoing maintenance
  • 500: Server Error - An unexpected error occurred while processing the request
  • 501: Generation Failed - Content generation task failed
  • 505: Feature Disabled - The requested feature is currently disabled
Available options:
200,
401,
402,
404,
422,
429,
455,
500,
501,
505
​
message
string

Response message, error description when failed

Example:

"success"

​
data
object