Real-Person Asset Library Integration

The real-person asset library uses LivenessFace groups. The person first completes H5 verification, which creates a group. Add assets to that group, wait for processing, and then reference their platform IDs in video generation.

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.

Integration Steps

1. Choose Standard Verification or Custom Callback Verification, supplying a group name and optional description.
2. Save the returned session ID and ask the person to open h5Link. Sessions currently expire 120 seconds after creation; use expiresAt as the deadline.
3. Query Verification Session until status=Succeeded and obtain the platform groupId. Custom callback mode redirects the browser to your application.
4. Create Real-Person Asset with that groupId, groupType=LivenessFace, the asset URL, and its type.
5. Query Real-Person Asset Detail until status=Active and assetStatus=1, then reference asset://<platform asset ID> in the Volcengine Video Generation API. The model must support the relevant asset type and role.

Create session -> Person completes H5 -> Platform creates a LivenessFace group
                                                             |
Query groupId -> Create asset -> Wait for Active -> Generate video using asset://

Differences from Virtual Avatar Assets

Item	Real-Person	Virtual Avatar
groupType	LivenessFace	AIGC
Group creation	Created after successful H5 verification; use the verification flow	Standard group creation endpoint
Asset creation	Requires a verified groupId; URL only	URL or multipart file
Verification and review	Assets still need to become Active after verification	Wait for assets to become Active after creation

Verification currently requires an official Volcengine channel configured by the platform and available to the user. Requests do not select channelId, channelConfigId, or projectName; the platform selects them. Verification cannot start without an available official channel.

Session Status

Status	Meaning and Action
Pending	Waiting for H5 verification; h5Link is returned while unexpired
Processing	Processing state in the session status enum; keep polling if returned
Succeeded	Verification succeeded and a platform group was created; deleted groups are omitted from queries
Failed	Verification or processing failed; inspect errorCode/errorMessage and create a new session after resolving the cause
Expired	Expired while waiting for verification; create a new session

Session status and the asset processing states Processing / Active / Failed are separate. resultCode=10000 only indicates H5 verification success; use the session status and groupId to determine whether the group is available.

Endpoints

Method	Endpoint
POST	Create Verification Session
POST	Create Verification Session (Custom Callback)
GET	Query Verification Session
GET	List Verification Sessions
POST	Create Real-Person Asset
GET	List Real-Person Assets
GET	Query Real-Person Asset Detail
PUT	Update Real-Person Asset
DELETE	Delete Real-Person Asset
GET	List Real-Person Asset Groups
GET	Query Real-Person Asset Group Detail
PUT	Update Real-Person Asset Group
DELETE	Delete Real-Person Asset Group

Result Fields and Error Handling

• Standard creation returns sessionId, while custom callback creation returns platformSessionId. Both queries return sessionId.
• Session groupId, customer redirect parameter assetGroupId, and group detail id refer to the same platform group ID. Do not substitute upstream Volcengine IDs.
• JSON examples in this section use top-level request fields without a body wrapper. Lists use pageNumber / pageSize.
• Success responses contain success=true, message="", and data. Business failures usually still return HTTP 200 with success=false. Missing authentication can return HTTP 401. Check both HTTP status and success.
• H5 uses the verification callback endpoints with URLs generated by the platform; applications do not call them directly. Validate customer redirect parameters through an authenticated session query.

{
  "success": false,
  "message": "Specific error message"
}

Common causes include missing parameters, no available official channel, invalid callback URLs, expired sessions, missing or inaccessible resources, and upstream processing failures. Inspect message or session/asset error fields.