Seedance Materials and Real-Person Verification

Seedance materials are organization-scoped image, video, or audio references that can be reused across video tasks. Choose the workflow first; virtual-avatar materials and verified real-person materials do not have the same creation path.

Choose A Material Workflow

Goal	Required flow
Use a one-off image URL	Send the URL in the video request; compatible Seedance models prepare it automatically
Reuse a virtual person, product, or style	Create an `aigc_avatar` group, create an asset, wait for `ACTIVE`, then use the asset ID
Reuse a real person	Complete visual validation, receive its `GroupId`, create an asset in that group, wait for `ACTIVE`, then use the asset ID
Migrate an existing Volcengine material client	Keep the Action request shape and use the Volc-compatible material reference

Material Concepts

Concept	REST field	Action field	What it means
Material group	`group_id`	`GroupId`	Owns related Seedance materials; use it when creating or filtering assets
Material asset	`id`	`Id`	One imported image, video, or audio file; use it for generation after it becomes active
Virtual-avatar group	`library_type: "aigc_avatar"`	`GroupType: "AIGC"`	Does not require real-person verification
Real-person group	`library_type: "liveness_face"`	`GroupType: "LivenessFace"`	Created only by a successful visual-validation flow
Project boundary	`project_name`	`ProjectName`	Isolates groups and assets inside the authenticated organization; defaults to `default`

Keep group IDs and asset IDs separate. A group organizes uploads; an asset ID is the reference used by video generation. Public IDs look like group-20260720123456-vrt01 and asset-20260720123457-def45.

Automatic Image Materials

When the selected Seedance model can use the TokenLab material library, you may send image URLs or supported inline data URLs directly in image, image_url, image_urls, reference_images, start_image, or end_image. TokenLab imports them into the organization’s default virtual-avatar group and preserves their first-frame, last-frame, or reference-image role. If preparation finishes within 60 seconds, video generation continues in the same request. Otherwise the API returns 409 seedance_material_preparing with auto_material_asset_ids. Poll those assets until they are ACTIVE, then retry with material_asset_id, material_asset_ids, or an asset://<id> URI in the appropriate media field. Existing material IDs are used as-is and are not imported again. If the selected model cannot use the material library, ordinary URL and data URL inputs continue on the regular media path; explicit material IDs return a material-availability error.

Virtual-Avatar Materials

Use Create Material Asset Group to create an aigc_avatar group. For REST asset creation, group_id is optional; TokenLab uses or creates the organization’s default virtual-avatar group when it is omitted. After a group exists, manage it with:

Deleting a group also deletes the TokenLab materials it contains and cannot be undone.

Real-Person Verification

Use this flow when your product must collect consent and verify a face before reusing a real person as a Seedance reference.

Call Create Visual Validation Session with CallbackURL; save Result.BytedToken and open Result.H5Link for the person being verified.
After the H5 flow redirects to the callback, poll Get Visual Validation Result with the same BytedToken and ProjectName.
Store the returned Result.GroupId. TokenLab creates and binds the LivenessFace group during this step.
Create an asset with that group ID, then poll the asset until it becomes ACTIVE.

BytedToken is valid for 30 minutes. A client cannot create a LivenessFace group with CreateAssetGroup; this prevents an unverified group from being presented as verified. For a real-person group, uploads are checked against the verified face. An asset can fail if it contains multiple faces or the face does not match. For best results, upload a full-body front reference and a clear front-facing close-up.

Create And Prepare An Asset

Use Create Material Asset to import one publicly reachable URL at a time.

Type	Supported input
Image	`jpeg`, `png`, `webp`, `bmp`, `tiff`, `gif`, `heic`, `heif`; aspect ratio `(0.4, 2.5)`; width and height `(300, 6000)` px; under 30 MB
Video	`mp4`, `mov`; `480p`, `720p`, or `1080p`; 2-15 seconds; aspect ratio `[0.4, 2.5]`; width and height `[300, 6000]` px; total pixels between 409600 and 2068676; up to 200 MB; 24-60 FPS
Audio	`aac`, `wav`, `mp3`; 2-15 seconds; up to 15 MB

Material ingestion is asynchronous. Poll Get Material Asset until status becomes ACTIVE. HTTP success means the import was accepted, not that the asset is ready. If the asset becomes FAILED, inspect error_message, correct the source, and create a new asset. The source URL is only used for import. TokenLab returns its own asset ID and keeps the asset in your organization’s material library until you delete the asset or its group.

Use An Asset In Video Generation

After an asset is ACTIVE, choose one of these forms when calling Create Video:

material_asset_id for one generic material reference
material_asset_ids for multiple generic references
asset://<asset-id> in start_image, end_image, or reference_images when the media role must be explicit

Material references count toward the selected model’s Seedance reference limits. If the API returns Seedance material asset not found or not accessible, confirm that the value is an asset ID rather than a group ID, belongs to the same organization and project, is not deleted, and is ACTIVE.

REST Or Volcengine Action

TokenLab-native integrations can continue to use the snake_case /v1/videos/assets* REST endpoints. Existing Volcengine clients can retain PascalCase bodies with Material Actions (Volc Compatible). Both interfaces operate on the same organization- and project-scoped material data.

REST Example: Virtual-Avatar Asset

curl https://api.tokenlab.sh/v1/videos/assets/groups \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"library_type":"aigc_avatar","group_name":"Product references","project_name":"default"}'

curl https://api.tokenlab.sh/v1/videos/assets \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_id":"group-20260720123456-abc12","asset_url":"https://example.com/reference.png","asset_name":"Front view","asset_type":"Image","project_name":"default"}'

curl https://api.tokenlab.sh/v1/videos/assets/asset-20260720123457-def45?project_name=default \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

Action Example: Verified Real-Person Asset

First create and complete visual validation:

curl 'https://api.tokenlab.sh/?Action=CreateVisualValidateSession&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"CallbackURL":"https://yourapp.example.com/seedance/callback","ProjectName":"default"}'

curl 'https://api.tokenlab.sh/?Action=GetVisualValidateResult&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"BytedToken":"<BYTED_TOKEN>","ProjectName":"default"}'

Then pass the returned GroupId to CreateAsset:

curl 'https://api.tokenlab.sh/?Action=CreateAsset&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId":"group-20260720123456-real1",
    "URL":"https://example.com/person-front.png",
    "Name":"Verified front view",
    "AssetType":"Image",
    "ProjectName":"default"
  }'

Poll with GetAsset until its status is Active, then pass the returned asset ID to video generation. For all 10 Action operations, filters, pagination, response shapes, and errors, see Material Actions (Volc Compatible).

Getting Started

Core Guides

Media Guides

Seedance Materials and Real-Person Verification

Choose A Material Workflow

Material Concepts

Automatic Image Materials

Virtual-Avatar Materials

Real-Person Verification

Create And Prepare An Asset

Use An Asset In Video Generation

REST Or Volcengine Action

REST Example: Virtual-Avatar Asset

Action Example: Verified Real-Person Asset

​Choose A Material Workflow

​Material Concepts

​Automatic Image Materials

​Virtual-Avatar Materials

​Real-Person Verification

​Create And Prepare An Asset

​Use An Asset In Video Generation

​REST Or Volcengine Action

​REST Example: Virtual-Avatar Asset

​Action Example: Verified Real-Person Asset

Choose A Material Workflow

Material Concepts

Automatic Image Materials

Virtual-Avatar Materials

Real-Person Verification

Create And Prepare An Asset

Use An Asset In Video Generation

REST Or Volcengine Action

REST Example: Virtual-Avatar Asset

Action Example: Verified Real-Person Asset