Real Face

What is Real Face

Token360 RealFace integrates with the BytePlus ModelArk real-human asset library. Images uploaded to a verified Real Face group can be referenced in video generation tasks to produce consistent character appearances.

Each asset is identified by a Token360 asset ID in the format ta_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

Supported Models

RealFace assets are supported only by compatible video models. Before using asset:// inputs, call GET /v1/models/{model_id} and confirm the required media fields and allowed parameter values in parameter_schema.

The API examples below use seedance-2.0 to show the request shape for a BytePlus-backed video model. For other models, use the field names and parameter values exposed by that model's schema.

Setting Up Real Face Assets

Setting Up Real Face Assets in Assets page

Before you can use RealFace in the Playground, create a Real Face asset group on the Assets page, complete real-person verification, and upload images into that group.

1. Open Assets

Click your avatar in the top-right corner and select Assets from the dropdown menu.

2. Create a Real Face group

In the Asset groups section, click New group. In the Create asset group dialog, select Real Face, enter a Group name, and click Create. Uploads to Real Face groups do not use a per-file expiry; No fixed expiry is selected and read-only in the dialog.

After creation, the dialog shows a verification link and QR code. Send either one only to the person being verified. The link is valid for 2 minutes (120 seconds). If it expires before verification is completed, open the group details again to obtain a fresh link. Obtain the person's permission before verification, upload, or use, and do not publish, forward, or log the verification link or QR code.

The group appears in the Asset groups table. Use the Status column to confirm the group is active before uploading images into it.

3. Upload assets

In the Assets section, click Upload and choose an image file. In the Upload file dialog, enter a Display name, set Asset group to the active Real Face group, and click Upload. The Retention selector is locked for Real Face groups because these uploads do not use a per-file expiry date.

• The asset appears in the Assets table under the selected group
• Each asset has a unique Asset ID in the format ta_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
• Click the Asset ID to copy it for API usage
• Assets may show Processing and cannot be used until their status becomes Active

Use the Asset group filter in the Assets table when you want to show only one Real Face group. The filter changes the visible rows only; the upload destination is selected in the Upload file dialog.

Only assets with Active status in a Real Face group can be used for RealFace. Generic uploads cannot be used directly for this scenario.

Setting Up Real Face Assets via API

Use the Assets API when you need to create and prepare RealFace assets outside the UI.

1. Create a Real Face group

Create a RealFace group with POST /v1/asset-groups and groupKind=REAL_FACE. The response includes the public assetGroupId and may include an h5Link verification URL.

1curl -X POST https://api.token360.ai/v1/asset-groups \
2  -H "Authorization: Bearer sk-your-api-key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Real Face Group",
6    "groupKind": "REAL_FACE"
7  }'

Send the h5Link only to the person being verified. The link is valid for 2 minutes (120 seconds). If it expires before verification is completed, call GET /v1/asset-groups/{assetGroupId} to get a fresh link. Obtain the person's permission before verification, upload, or use, and do not publish, forward, or log the verification link.

2. Get the verified asset group ID

After verification is complete, use the returned assetGroupId as the upload groupId. You can also call GET /v1/asset-groups with groupKind=REAL_FACE to find active RealFace groups.

1curl "https://api.token360.ai/v1/asset-groups?groupKind=REAL_FACE&status=active&current=1&size=100" \
2  -H "Authorization: Bearer sk-your-api-key"

3. Upload RealFace assets

Upload image files with POST /v1/assets using multipart form data. Set groupId to the active Real Face group assetGroupId.

1curl -X POST https://api.token360.ai/v1/assets \
2  -H "Authorization: Bearer sk-your-api-key" \
3  -F "groupId=your-asset-group-id" \
4  -F "file=@your-image-file.jpg" \
5  -F "name=Asset Name"

The upload response returns a public assetId with the ta_ prefix. Use it in the format asset://{assetId} for RealFace video inputs.

4. Poll until the asset is active

Poll GET /v1/assets/{assetId} or GET /v1/assets?groupId=your-asset-group-id until the asset status is active.

After the asset becomes active, use its public assetId in the format asset://{assetId}.

Do not use generic user-upload asset IDs, such as IDs with the ua_ prefix, as RealFace references. If an image was uploaded as a generic asset, upload it again into the active Real Face group.

Using Real Face

Using RealFace in the Playground

1. Select a Supported Model

In the Playground, choose a video model whose parameter schema supports RealFace image inputs.

2. Choose a Video Mode

RealFace can be used in the following video modes:

• First-frame I2V
• First & last frame
• Reference images
• Multimodal reference
• Edit video
• Extend video

3. Select a RealFace Asset

For supported video modes, each compatible media block, such as First frame, Last frame, or Reference images, has source buttons in its header:

• Click the upload icon to add a local file from your device
• Click the library icon, labeled From assets, to open Choose from your library

In Choose from your library, set the type dropdown to Real Face, or search by asset name or asset ID. Image slots are locked to images, and you can also filter by group. The picker only allows active, non-expired assets.

For single-image slots such as first frame or last frame, click an asset card to use it immediately. For multi-image slots such as reference images, select one or more asset cards and click Use selected. Selected RealFace inputs are marked with an Asset badge in the Playground.

4. Generate the Video

After selecting the RealFace asset(s), fill in the prompt and other parameters, then click Generate.

Using RealFace via API

You can find the asset ID on the Assets page. Filter by the Real Face group, then click the Asset ID to copy it.

Reference a RealFace asset with the public assetId in the format asset://{assetId}, for example asset://ta_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

1curl -X POST https://api.token360.ai/v1/videos \
2  -H "Authorization: Bearer sk-your-api-key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model": "seedance-2.0",
6    "prompt": "A verified person smiles and turns toward the camera in soft studio light",
7    "frame_images": [
8      {
9        "type": "image_url",
10        "frame_type": "first_frame",
11        "image_url": { "url": "asset://ta_first_frame_asset_id" }
12      }
13    ],
14    "duration": 5,
15    "resolution": "720p",
16    "generate_audio": false
17  }'

Limitations

• RealFace assets are available only on video models whose parameter schema supports RealFace inputs
• Each asset must belong to an active Real Face group and itself be in active status
• Asset availability is subject to BytePlus ModelArk service status

Quota, usage protection, and deletion

Virtual Portrait and Real Face assets share the managed-asset quota of the current personal or tenant scope. The default limit is 50,000 for a personal scope and 500,000 for a tenant scope. Call GET /v1/assets/quota before a large upload and while monitoring automation.

After upload, poll the asset until status is active before using asset://ta_... in video generation. A video request protects every referenced managed asset while the video task is in progress. Deleting a protected asset returns ASSET_DELETE_USAGE_ACTIVE; retry after the video task reaches a terminal state.

• Single asset: DELETE /v1/assets/{assetId}, then poll GET /v1/assets/operations/{operationId} when an operation ID is returned.
• Selected assets: create a deletion job with selectionType=ASSET_IDS and 1–20 public asset IDs.
• All eligible managed assets: preview ALL_OWNED_BY_ME or ALL_IN_CURRENT_SCOPE, then submit the returned confirmation token.
• JWT sessions and sk-* API keys are supported for the deletion-job APIs.

Use only the public assetId returned by Token360, in the format asset://{assetId}.