Virtual Avatar Assets

• Private-domain virtual avatar asset submission API
• Supports batch submission, up to 20 assets per request
• Automatically creates or reuses asset groups; returns a task ID for status polling
• Approved assets can be used directly in Seedance 2.0 video generation

POST /v1/seedance2/private-avatar

cURL (Batch submit · new group)

curl --request POST \
  --url https://api.apimart.ai/v1/seedance2/private-avatar \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "group": {
      "name": "virtual-avatar-group",
      "description": "demo group"
    },
    "project_name": "default",
    "asset_type": "Image",
    "assets": [
      {
        "url": "https://example.com/avatar-a.png",
        "name": "avatar-a"
      },
      {
        "url": "https://example.com/avatar-b.png",
        "name": "avatar-b"
      }
    ]
  }'

200

{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "object": "seedance.avatar.asset.task",
    "status": "processing",
    "progress": 10,
    "model": "seedance-2.0"
  }
}

cURL (Batch submit · new group)

curl --request POST \
  --url https://api.apimart.ai/v1/seedance2/private-avatar \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "group": {
      "name": "virtual-avatar-group",
      "description": "demo group"
    },
    "project_name": "default",
    "asset_type": "Image",
    "assets": [
      {
        "url": "https://example.com/avatar-a.png",
        "name": "avatar-a"
      },
      {
        "url": "https://example.com/avatar-b.png",
        "name": "avatar-b"
      }
    ]
  }'

200

{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "object": "seedance.avatar.asset.task",
    "status": "processing",
    "progress": 10,
    "model": "seedance-2.0"
  }
}

Authentication

Authorization · string · required

All requests require Bearer Token authentication

Get your API Key:

Visit the API Key Management page to obtain your API Key

Add the following header to each request:

Authorization: Bearer YOUR_API_KEY

Request Parameters

group · object

Asset group information

If group_id is not provided, the server will automatically create an AIGC asset group based on this field

Show Fields

name · string

Asset group name

description · string

Asset group description

Example:

{
  "group": {
    "name": "virtual-avatar-group",
    "description": "demo group"
  }
}

Mutually exclusive with group_id — do not provide both at the same time

group_id · string

Existing asset group ID

When provided, skips group creation and submits assets directly to the specified group

Mutually exclusive with group — do not provide both at the same time

project_name · string · default: "default"

Project name

Default: default

asset_type · string · default: "Image"

Asset type

Options:

• Image - Image asset (default)
• Video - Video asset
• Audio - Audio asset

Default: Image

assets · array

Asset list, supports submitting multiple assets in one request

Maximum 20 assets per submission

Show Fields

url · string · required

Asset URL — must be publicly accessible

name · string · required

Asset name

Example:

{
  "assets": [
    {
      "url": "https://example.com/avatar-a.png",
      "name": "avatar-a"
    },
    {
      "url": "https://example.com/avatar-b.png",
      "name": "avatar-b"
    }
  ]
}

url · string

Single-asset shorthand: asset URL

Use either assets array or this field — not both. Suitable for submitting a single asset.

name · string

Single-asset shorthand: asset name

Use either assets array or this field — not both. Suitable for submitting a single asset.

Response

code · integer

Response status code, 200 on success

data · object

Task information

Show Fields

id · string

Local task ID, used to query asset review status

object · string

Task object type, always seedance.avatar.asset.task

status · string

Initial task status, processing after submission

progress · integer

Task progress (0 ~ 100)

model · string

Model name in use

Examples

Example 1: Batch submit (auto-create group)

When group_id is not provided, the server automatically creates an AIGC asset group before submitting.

{
  "group": {
    "name": "virtual-avatar-group",
    "description": "demo group"
  },
  "project_name": "default",
  "asset_type": "Image",
  "assets": [
    {
      "url": "https://example.com/avatar-a.png",
      "name": "avatar-a"
    },
    {
      "url": "https://example.com/avatar-b.png",
      "name": "avatar-b"
    }
  ]
}

Example 2: Append assets to an existing group

Provide group_id to skip group creation and submit directly.

{
  "group_id": "group_xxx",
  "project_name": "default",
  "asset_type": "Image",
  "assets": [
    {
      "url": "https://example.com/avatar-a.png",
      "name": "avatar-a"
    }
  ]
}

Example 3: Single-asset shorthand

For a single asset, use the top-level url and name fields directly.

{
  "group_id": "group_xxx",
  "url": "https://example.com/avatar.png",
  "asset_type": "Image",
  "name": "avatar-1"
}

Query Review Result

Asset submission is an asynchronous task. Use the Get Task Status endpoint to poll:

GET /v1/tasks/{id}

All Approved

{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "progress": 100,
    "result": {
      "assets": [
        {
          "asset_id": "asset_a",
          "asset_url": "asset://asset_a",
          "status": "Active"
        },
        {
          "asset_id": "asset_b",
          "asset_url": "asset://asset_b",
          "status": "Active"
        }
      ],
      "usable_assets": [
        {
          "asset_id": "asset_a",
          "asset_url": "asset://asset_a",
          "status": "Active"
        },
        {
          "asset_id": "asset_b",
          "asset_url": "asset://asset_b",
          "status": "Active"
        }
      ],
      "failed_assets": []
    }
  }
}

Partial Failure

If any asset fails review, the task status becomes failed. Successfully approved assets remain usable and appear in result.usable_assets.

{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "failed",
    "progress": 100,
    "result": {
      "assets": [
        {
          "asset_id": "asset_a",
          "asset_url": "asset://asset_a",
          "status": "Active"
        },
        {
          "asset_id": "asset_b",
          "asset_url": "asset://asset_b",
          "status": "Failed"
        }
      ],
      "usable_assets": [
        {
          "asset_id": "asset_a",
          "asset_url": "asset://asset_a",
          "status": "Active"
        }
      ],
      "failed_assets": [
        {
          "asset_id": "asset_b",
          "asset_url": "asset://asset_b",
          "status": "Failed"
        }
      ]
    },
    "error": {
      "code": "task_failed",
      "message": "Some assets failed review"
    }
  }
}

• result.usable_assets[].asset_url can be used directly in Seedance 2.0 video generation
• Assets in result.failed_assets must be replaced or resubmitted
• Single-asset tasks also return result.asset_url for compatibility

Using Approved Assets

Pass the asset://... URL directly to the Seedance 2.0 Video Generation endpoint:

{
  "model": "seedance-2.0",
  "prompt": "The character walks naturally along a city street",
  "image_urls": ["asset://asset_a"],
  "duration": 5,
  "resolution": "720p"
}

Once the server detects the asset:// prefix, it submits the generation task directly without triggering another asset review.