> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedance Materials and Real-Person Verification

> Create reusable Seedance materials, verify real people, and use active assets in video generation.

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](/api-reference/video/volc-compatible-material-actions) |

## 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](/api-reference/video/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](/api-reference/video/list-material-asset-groups)
* [Get Material Asset Group](/api-reference/video/get-material-asset-group)
* [Update Material Asset Group](/api-reference/video/update-material-asset-group)
* [Delete Material Asset Group](/api-reference/video/delete-material-asset-group)

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.

1. Call [Create Visual Validation Session](/api-reference/video/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](/api-reference/video/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.

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](/api-reference/video/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](/api-reference/video/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](/api-reference/video/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)](/api-reference/video/volc-compatible-material-actions). Both interfaces operate on the same organization- and project-scoped material data.

## REST Example: Virtual-Avatar Asset

```bash theme={null}
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:

```bash theme={null}
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`:

```bash theme={null}
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)](/api-reference/video/volc-compatible-material-actions).