Virtual portrait assets

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.

If you do not have an API Key yet, read Get API Key first. Use the same API key to create the group, create assets, and generate video.

See Real-person verification for that flow. If generating a video with a real-person asset fails, use Create virtual portrait group on this page.

Integration flow

Create a virtual portrait group

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

Prepare a public media URL

The source file must be reachable from the public internet. For a local or private file, use Asset upload and keep the confirmed data.url.

Create an asset

Wait until the asset is ready

Query the asset until status is Active.

Generate video

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

Create a virtual portrait group

Call Create virtual portrait group. 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.

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:

{
  "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 first. Do not pass the object-storage uploadUrl as the asset URL. Then call Create asset:

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 refreshes the upstream processing status:

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:

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

Send name and optional description only.

Manage assets

Create an asset and check its processing status.

Getting Started

Publishing

Assets

AI Generation

AI Tool Integration

Deployment

Integration flow

Create a virtual portrait group

Create an asset

Wait until the asset is Active

Use the asset in Seedance

Limits

Create a virtual portrait group

Manage assets

​Integration flow

​Create a virtual portrait group

​Create an asset

​Wait until the asset is Active

​Use the asset in Seedance

​Limits

Create a virtual portrait group

Manage assets

Integration flow

Create a virtual portrait group

Create an asset

Wait until the asset is Active

Use the asset in Seedance

Limits