MaiToken
Login/Register

Seedance Real-Person Avatar Assets

The person completes H5 liveness verification first, then assets are submitted to the group created by the verification

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

Unlike virtual avatars, real-person assets require identity verification: the person being filmed completes liveness verification and authorization in a mobile H5 flow. Only then do you get an asset group to submit into. The API uses the same native Volcengine Ark Action protocol (POST /?Action=...&Version=2024-01-01, JSON body, PascalCase fields) with Bearer authentication.

Full flow:

  • Create a verification session, obtaining a BytedToken and an H5 verification link
  • The person opens the H5 link and completes liveness verification
  • Query the verification result to obtain the asset group Id (the group is claimed to your account)
  • Submit real-person assets to that group, poll status, then use in generation

Authorizations

AuthorizationstringRequired

Bearer Token authentication. Get an API Key at the API Key console

Authorization: Bearer YOUR_API_KEY

Flow

sequenceDiagram    participant Client    participant MaiToken    participant Person     Client->>MaiToken: 1. CreateVisualValidateSession    MaiToken-->>Client: Result.BytedToken + H5 link     Person->>Person: 2. Complete H5 liveness verification     Client->>MaiToken: 3. GetVisualValidateResult (BytedToken)    MaiToken-->>Client: Result.GroupId     Client->>MaiToken: 4. CreateAsset (GroupId + asset URL)    MaiToken-->>Client: Result.Id (asset-*)     loop until usable      Client->>MaiToken: 5. GetAsset (Id)      MaiToken-->>Client: Result.Status    end

Step 1: Create a verification session

Call CreateVisualValidateSession. The Result contains a BytedToken (the credential for querying the result, valid for 30 minutes) and the H5 verification link for the person.

Body fields:

  • CallbackURL (optional): callback after verification; resultCode=10000 in the callback parameters means success

Step 2: The person completes H5 verification

Send the H5 link to the person; they complete liveness verification and portrait authorization on mobile. With CallbackURL configured, resultCode=10000 indicates success.

Step 3: Query the result and claim the group

Call GetVisualValidateResult with the BytedToken. On success it returns the real-person asset group Id — this call also claims the group to your account.

Note: the BytedToken must come from a session you created; using someone else's token returns 404 asset_not_found.

Step 4: Submit real-person assets

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

With the GroupId, use the same CreateAsset / GetAsset as for virtual avatars. Every submission goes through face-consistency checks against the verified person; only assets of the same person can enter the group.

Status values

  • Processing — under review / consistency check.
  • Active — usable; reference via asset://<ASSET_ID> (same as virtual avatars).
  • Failed — common causes: asset doesn't match the verified person, blurry/occluded/multiple people, inaccessible URL.

Common failure causes

  • H5 link expired (session valid for 30 minutes)
  • Querying the result before the person finished verification
  • Using a BytedToken from someone else's session (404 asset_not_found)
  • Submitted asset fails the consistency check against the verified person
  • Asset URL inaccessible or low quality