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

# Virtual portrait assets

> Create a virtual portrait asset group under video generation. name is required and description is optional. This endpoint does not accept avatarType.

Virtual portrait assets do not require liveness verification. `name` is required and `description` is optional. Your integration only needs an AiToEarn `X-Api-Key`; no Volcengine access key or secret key is required.

> [!NOTE]
>
> If you do not have an API Key yet, read [Get API Key](https://docs.aitoearn.ai/en/use/api-key.md) first. Use the same API key to create the group, create assets, and generate video.

> [!NOTE]
>
> See [Real-person verification](https://docs.aitoearn.ai/en/use/video-generation/real-person-assets.md) for that flow.
> If generating a video with a real-person asset fails, use [Create virtual portrait group](https://docs.aitoearn.ai/en/api-reference/post-api-ai-volcengine-assets-groups.md) on this page.

## Integration flow

**1. Create a virtual portrait group**

Send `name` and optional `description`, then store `groupId`. The returned `avatarType` is `Virtual`.

**2. Prepare a public media URL**

The source file must be reachable from the public internet. For a local or private file, use [Asset upload](https://docs.aitoearn.ai/en/use/asset-upload.md) and keep the confirmed `data.url`.

**3. Create an asset**

Register the image, video, or audio in that group and store `assetId`.

**4. Wait until the asset is ready**

Query the asset until `status` is `Active`.

**5. Generate video**

Pass `asset://{assetId}` in the Seedance reference field.

## Create a virtual portrait group

Call [Create virtual portrait group](https://docs.aitoearn.ai/en/api-reference/post-api-ai-volcengine-assets-groups.md). The request has only these fields. Do not add real-person verification fields:

| Parameter | Required | Meaning |
| - | - | - |
| `name` | Yes | Virtual portrait group name |
| `description` | No | Group description |

Volcengine `CreateAssetGroup` has no `avatarType` field. `Name` is required, `Description` is optional, and `GroupType` is optional with a default of `AIGC` (virtual portrait assets). This endpoint does not accept `GroupType` or `avatarType`. It always creates a virtual portrait group, and the response `avatarType` is `Virtual`. `avatarType` is optional only when listing groups.

```bash theme={null}
curl --request POST 'https://aitoearn.ai/api/ai/volcengine/assets/groups' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <API_KEY>' \
  --data '{
    "name": "product-avatar",
    "description": "Product avatar assets"
  }'
```

`name` is required. `description` is optional. Store `data.groupId`:

```json theme={null}
{
  "code": 0,
  "message": "Request succeeded",
  "data": {
    "groupId": "group_xxx",
    "name": "product-avatar",
    "description": "Product avatar assets",
    "avatarType": "Virtual",
    "createdAt": "2026-07-02T12:00:00.000Z",
    "updatedAt": "2026-07-02T12:00:00.000Z"
  }
}
```

`avatarType` is always `Virtual`. Use this `groupId` when you create, query, or delete assets.

## Create an asset

The source URL must be publicly accessible while the asset is created and processed. If the file is local or private, use [Asset upload](https://docs.aitoearn.ai/en/use/asset-upload.md) first. Do not pass the object-storage `uploadUrl` as the asset URL.

Then call [Create asset](https://docs.aitoearn.ai/en/api-reference/post-api-ai-volcengine-assets-items.md):

```bash theme={null}
curl --request POST 'https://aitoearn.ai/api/ai/volcengine/assets/items' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <API_KEY>' \
  --data '{
    "groupId": "group_xxx",
    "url": "https://assets.example.com/product-reference.jpg",
    "assetType": "Image",
    "name": "product-reference"
  }'
```

`assetType` can be `Image`, `Video`, or `Audio`. `name` is optional. Store `data.assetId`. The initial status is usually `Processing`.

## Wait until the asset is Active

[Asset details](https://docs.aitoearn.ai/en/api-reference/get-api-ai-volcengine-assets-items-asset-id.md) refreshes the upstream processing status:

```bash theme={null}
curl --request GET \
  'https://aitoearn.ai/api/ai/volcengine/assets/items/<ASSET_ID>' \
  --header 'X-Api-Key: <API_KEY>'
```

| status | Meaning | What to do |
| - | - | - |
| `Processing` | The asset is still processing | Query the asset again later |
| `Active` | The asset is ready | Use it in Seedance |
| `Failed` | Processing failed | Check the source file and create a new asset |

The asset list stores the local registration record. Query a single asset to read the latest status.

## Use the asset in Seedance

After the status becomes `Active`, write the asset ID as `asset://{assetId}` and send it to `POST /api/ai/video/generations`:

```bash theme={null}
curl --request POST 'https://aitoearn.ai/api/ai/video/generations' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <API_KEY>' \
  --data '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "Keep the reference styling and clothing, and generate a natural speaking shot",
    "mode": "multi-ref",
    "images": ["asset://<ASSET_ID>"],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'
```

Call [Video generation models](https://docs.aitoearn.ai/en/api-reference/get-api-ai-models-video-generation.md) first and choose a Seedance model available on the current site that supports the input mode you need.

## Limits

* Use the same API key for the group, the asset, and video generation.
* Keep the source URL publicly accessible while the asset is processing.
* Put only the asset ID after `asset://`. Do not append a path, query string, or fragment.
* Match the asset type to the field: images in `images`, videos in `videos`, and audio in `audios`.
* Use only `Active` assets.

> **[Create a virtual portrait group](https://docs.aitoearn.ai/en/api-reference/post-api-ai-volcengine-assets-groups.md)**
>
> Send `name` and optional `description` only.

> **[Manage assets](https://docs.aitoearn.ai/en/api-reference/post-api-ai-volcengine-assets-items.md)**
>
> Create an asset and check its processing status.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.