Virtual Portrait

What is Virtual Portrait

Token360 Virtual Portrait integrates with the BytePlus ModelArk AIGC asset library, allowing you to use AI-generated character images as references in video generation workflows without real-person verification.

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

Key Differences from RealFace

Supported Models

Virtual Portrait 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 Virtual Portrait Assets

Setting Up Virtual Portrait Assets in Assets page

Before you can use Virtual Portrait in the Playground, create a Virtual Portrait asset group on the Assets page 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 Virtual Portrait group

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

The group appears in the Asset groups table and becomes available immediately after creation. No H5 real-person verification step is required.

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 Virtual Portrait group, and click Upload. The Retention selector is locked for Virtual Portrait 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 Virtual Portrait 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 Virtual Portrait group can be used for Virtual Portrait. Generic uploads cannot be used directly for this scenario.

Setting Up Virtual Portrait Assets via API

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

1. Create a Virtual Portrait group

Create a Virtual Portrait group with POST /v1/asset-groups and groupKind=VIRTUAL_PORTRAIT. The response returns the public assetGroupId, and the group is active immediately.

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": "Virtual Portrait Name",
6    "groupKind": "VIRTUAL_PORTRAIT"
7  }'

2. Upload Virtual Portrait assets

Upload image files with POST /v1/assets using multipart form data. Set groupId to the Virtual Portrait group's assetGroupId.

1curl -X POST https://api.token360.ai/v1/assets \
2  -H "Authorization: Bearer sk-your-api-key" \
3  -F "groupId=your-virtual-portrait-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 Virtual Portrait video inputs.

3. Poll until the asset is active

Poll GET /v1/assets/{assetId} or GET /v1/assets?groupId=your-virtual-portrait-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 Virtual Portrait references. If an image was uploaded as a generic asset, upload it again into the active Virtual Portrait group.

Using Virtual Portrait

Using Virtual Portrait in the Playground

1. Select a Supported Model

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

2. Choose a Video Mode

Virtual Portrait assets can be used in the following video modes:

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

3. Select an 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 Virtual Portrait, 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 Virtual Portrait inputs are marked with an Asset badge in the Playground.

4. Generate the Video

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

Using Virtual Portrait via API

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

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

Use the same media input fields shown in each video model's input parameter schema:

• First frame or last frame: use frame_images[].image_url.url
• Reference images and other image references: use input_references[].image_url.url

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 stylized virtual character 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_virtual_portrait_asset_id" }
12      }
13    ],
14    "duration": 6,
15    "resolution": "720p",
16    "generate_audio": false
17  }'

Limitations

• Virtual Portrait assets are available only on video models whose parameter schema supports Virtual Portrait inputs
• Each asset must belong to an active Virtual Portrait 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}.