Seedance Asset Library

The asset library lets you upload images, videos, or audio in advance and reference them in Seedance video generation requests through asset URIs (asset://<asset_id>). Uploads are processed asynchronously: create the asset to obtain its Id, then poll its status; only assets whose Status is Active can be used for generation.

This API is fully wire-compatible with the Volcengine Ark Assets API, so the official SDK calling conventions apply. The only differences are:

• Authentication: use a platform API key (Bearer token); no AK/SK signing required
• Base URL: https://api.tokenhub.belivestudios.com
• Isolation: assets are scoped to the user that owns the API key; you can only query and use assets uploaded by the current user

Endpoints

All operations are invoked through a unified Action form:

POST https://api.tokenhub.belivestudios.com/?Action=<Action>&Version=2024-01-01
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Version is fixed at 2024-01-01. Request bodies are JSON, and responses are wrapped in a ResponseMetadata + Result envelope (see Responses and errors).

Resource model

• Asset Group: a container for grouping assets, e.g. keeping all assets of one virtual person in a single group. You must create a group before uploading assets.
• Asset: a single media file (image, video, or audio) belonging to a group; an asset that Seedance 2.0 / 2.5 can directly use for inference.

ProjectName isolates resources across projects. It is optional on every endpoint and defaults to default. Creating, querying, and using the same asset must use the same ProjectName; leaving it unset everywhere is recommended.

Asset requirements

Asset URLs must be publicly accessible HTTP/HTTPS addresses; the download cap is 200 MB. Each request uploads exactly one file.

Asset group endpoints

Create an asset group

Action=CreateAssetGroup

curl -X POST "https://api.tokenhub.belivestudios.com/?Action=CreateAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "figure_group_1",
    "Description": "Virtual figure assets"
  }'

{
  "ResponseMetadata": {
    "RequestId": "20260915103000abcdef",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260915103000-a1b2c"
  }
}

List asset groups

Action=ListAssetGroups

curl -X POST "https://api.tokenhub.belivestudios.com/?Action=ListAssetGroups&Version=2024-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Filter": {"GroupType": "AIGC", "Name": "figure"},
    "MaxResults": 10,
    "SortBy": "CreateTime",
    "SortOrder": "Desc"
  }'

{
  "ResponseMetadata": {"RequestId": "...", "Action": "ListAssetGroups", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing"},
  "Result": {
    "Items": [
      {
        "Id": "group-20260915103000-a1b2c",
        "Name": "figure_group_1",
        "Description": "Virtual figure assets",
        "GroupType": "AIGC",
        "ProjectName": "default",
        "CreateTime": "2026-09-15T10:30:00Z",
        "UpdateTime": "2026-09-15T10:30:00Z"
      }
    ],
    "NextToken": "eyJWZXJzaW9uIjox..."
  }
}

A returned NextToken means more results are available; pass it back unchanged to fetch the next page.

Get one asset group

Action=GetAssetGroup

Result contains a single group object with the fields shown above.

Update an asset group

Action=UpdateAssetGroup

Only the provided fields are updated. On success, Result returns {"Id": "<group ID>"}.

Delete an asset group

Action=DeleteAssetGroup

On success, Result is an empty object. Assets in a deleted group become unusable; the operation cannot be undone.

Asset endpoints

Upload an asset

Action=CreateAsset

Upload is asynchronous and may be queued; no upload-time SLA is promised, and video assets take longer. The returned asset ID only means the task was created. Poll GetAsset until Status becomes Active before using the asset.

curl -X POST "https://api.tokenhub.belivestudios.com/?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId": "group-20260915103000-a1b2c",
    "URL": "https://example.com/reference.png",
    "AssetType": "Image",
    "Name": "character reference"
  }'

{
  "ResponseMetadata": {"RequestId": "...", "Action": "CreateAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing"},
  "Result": {
    "Id": "asset-20260915103100-d3e4f"
  }
}

Get one asset

Action=GetAsset

curl -X POST "https://api.tokenhub.belivestudios.com/?Action=GetAsset&Version=2024-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Id": "asset-20260915103100-d3e4f"}'

{
  "ResponseMetadata": {"RequestId": "...", "Action": "GetAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing"},
  "Result": {
    "Id": "asset-20260915103100-d3e4f",
    "Name": "character reference",
    "GroupId": "group-20260915103000-a1b2c",
    "ProjectName": "default",
    "AssetType": "Image",
    "Status": "Active",
    "Moderation": {"Strategy": "Default"},
    "URL": "https://example.com/reference.png",
    "CreateTime": "2026-09-15T10:31:00Z",
    "UpdateTime": "2026-09-15T10:31:04Z",
    "LastInferenceTime": "2026-09-15T11:02:00Z"
  }
}

Asset object fields:

List assets

Action=ListAssets

curl -X POST "https://api.tokenhub.belivestudios.com/?Action=ListAssets&Version=2024-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Filter": {
      "GroupType": "AIGC",
      "GroupIds": ["group-20260915103000-a1b2c"],
      "Statuses": ["Active"]
    },
    "MaxResults": 20,
    "SortBy": "CreateTime",
    "SortOrder": "Desc"
  }'

Result.Items is an array of asset objects (same fields as GetAsset); Result.NextToken is used for pagination.

Update an asset

Action=UpdateAsset

On success, Result returns {"Id": "<asset ID>"}.

Delete an asset

Action=DeleteAsset

On success, Result is an empty object. Deletion cannot be undone. Check LastInferenceTime via GetAsset or ListAssets and proactively delete assets you no longer need.

Pagination

ListAssets and ListAssetGroups support two pagination modes, which cannot be mixed:

Page-number responses additionally return PageNumber, PageSize, and TotalCount (total matching records). Token pagination only returns NextToken when more results exist.

A NextToken is bound to the filter and sort options; keep all other parameters unchanged while paging, or token validation fails.

Use an asset for video generation

In the video generation API, build asset://<asset_id> from the asset ID and place it in the image_url.url, video_url.url, or audio_url.url field of the matching modality in content. Plain HTTP/HTTPS URLs can still be mixed in.

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "The girl in image 1 wears the outfit from image 2 and tidies items on the counter, with audio 1 as background music."
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {"url": "asset://asset-20260915103100-d3e4f"}
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {"url": "asset://asset-20260915103200-f5a6b"}
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": {"url": "asset://asset-20260915103300-c7d8e"}
    }
  ],
  "generate_audio": true,
  "ratio": "16:9",
  "duration": 11
}

Notes:

• Before calling the upstream model, the platform resolves asset URIs owned by the current user into real asset URLs. The request fails if an asset does not exist, belongs to another user, is not yet Active, or its type does not match the modality.
• In the prompt, refer to assets as "image 1", "video 1", "audio 1" (图片1 / 视频1 / 音频1); numbering starts at 1 within each modality in request-body order. Never write asset IDs in the prompt.
• Asset URIs must carry the asset:// prefix; a bare asset ID is not accepted.

Simple query endpoints

In addition to the Action form, the platform provides these REST aliases for quick queries:

curl "https://api.tokenhub.belivestudios.com/api/assets?status=Active&limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "items": [
    {
      "Id": "asset-20260915103100-d3e4f",
      "Name": "character reference",
      "GroupId": "group-20260915103000-a1b2c",
      "ProjectName": "default",
      "AssetType": "Image",
      "Status": "Active",
      "Moderation": {"Strategy": "Default"},
      "URL": "https://example.com/reference.png",
      "CreateTime": "2026-09-15T10:31:00Z",
      "UpdateTime": "2026-09-15T10:31:04Z"
    }
  ],
  "data": ["same as items"],
  "total": 1
}

items and data are identical; read either one. total is the number of assets matching the filters, and the list is sorted by creation time descending.

Responses and errors

Every Action endpoint returns the same envelope:

{
  "ResponseMetadata": {
    "RequestId": "request ID",
    "Action": "action name",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing",
    "Error": {"Code": "error code", "Message": "error message"}
  },
  "Result": {}
}

On success there is no Error field and Result carries the payload. On failure the HTTP status is non-200, Result is omitted, and Error describes the problem. Common error codes:

When asynchronous processing fails, GetAsset returns Status: Failed with an Error.Code such as AssetURLUnavailable (URL could not be downloaded), AssetTooLarge (over the 200 MB download cap), InvalidAsset (violates the asset requirements), or AssetTypeMismatch (AssetType does not match the detected file type).

FAQ

Why can't I use an asset for video generation right after uploading it?

Processing is asynchronous; poll GetAsset until Status becomes Active. You also will not find the asset if CreateAsset and GetAsset were called with different ProjectName values. The field defaults to default when omitted, so leaving it unset everywhere is recommended.

How should the prompt refer to assets?

Use the "asset type + index" format, such as "image 1", "video 1", "audio 1" (图片1 / 视频1 / 音频1). The index is the asset's position among assets of the same modality in the request body, starting at 1. Never use asset IDs in the prompt.

Are there capacity or rate limits?

Assets are isolated and managed per API key owner. Endpoint calls follow the platform's global rate-limit policy; requests that exceed the limit are rejected, so control your call frequency and retry with backoff.