Seedance Materials and Real-Person Verification

Seedance materials let you reuse an image, video, or audio file without importing it for every generation. References to a real person require consent and visual verification; virtual people, products, and styles do not.

Choose a material typeCopy Anchor Link

Groups and materialsCopy Anchor Link

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.

Material RetentionCopy Anchor Link

TokenLab keeps every material asset until you delete the asset or its group. It is not cleaned up for inactivity on TokenLab's side.

The upstream Seedance provider may remove its own working copy of an asset after 30 days without use. This does not delete your asset or change its ID: the next time you use it in a generation request, TokenLab automatically prepares a new upstream copy from the stored original.

• The first generation after a cleanup can take a little longer while the new copy is prepared. If it is not ready yet, the request returns seedance_material_preparing; retry shortly.
• Deleting an asset or group is permanent and cannot be undone.

Image URLs and reusable materialsCopy Anchor Link

Send public HTTP(S) URLs or supported data URLs in the image fields accepted by your selected model. These inputs follow the normal media path and do not automatically create reusable material IDs.

For reusable materials, create an asset through the material API, wait for ACTIVE, then use material_asset_id, material_asset_ids, or asset://<id> in a supported media field. Keep the intended first-frame, last-frame, or reference-image role.

When an explicit material is still preparing, POST /v1/videos/generations returns 409 seedance_material_preparing with inactive_asset_ids. Poll those assets until ACTIVE, then retry with the same material IDs. If an asset is FAILED, inspect error_message and correct or reimport it before retrying.

Virtual-Avatar MaterialsCopy Anchor Link

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:

• List Material Asset Groups
• Get Material Asset Group
• Update Material Asset Group
• Delete Material Asset Group

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

Real-Person VerificationCopy Anchor Link

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

1. Call Create Visual Validation Session with CallbackURL; save Result.BytedToken and open Result.H5Link for the person being verified.
2. After the H5 flow redirects to the callback, poll Get Visual Validation Result with the same BytedToken and ProjectName.
3. Store the returned Result.GroupId. TokenLab creates and binds the LivenessFace group during this step.
4. 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.

Open the returned H5Link immediately after creation. The token validity does not mean the verification page can be opened for the first time at any point in that window.

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 AssetCopy Anchor Link

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

These are file-import limits. A successful import request does not guarantee that media or real-person validation will pass. Wait for ACTIVE; if the asset becomes FAILED, use error_message to correct the source before importing again.

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. The upstream copy is re-created automatically if it is cleaned up; see the retention section above.

Use An Asset In Video GenerationCopy Anchor Link

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 ActionCopy Anchor Link

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 AssetCopy Anchor Link

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 AssetCopy Anchor Link

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).