Asset Library V3 (Native Seedance V3)

The asset library for native Seedance V3 (doubao-seedance-*): create groups, upload reference assets, then reference them in video generation. Assets are strictly isolated per customer (enforced by the platform ownership table).

Two asset libraries (per model family)

• This page: native Seedance V3 (doubao-seedance-*), paths /v3/asset-groups & /v3/assets;
• Seedance_sup (seedance-2-0 family) has its own library at /v1/assets — see Asset Library.
• Assets from the two libraries cannot be referenced across.

Authentication

Authorization: Bearer $YOUR_API_KEY

Concepts

• Asset group: container of assets; returns a groupId on creation (e.g. group-20260802183721-1ceb5f);
• Asset: one reference image/video, referenced by a public URL (fetched upstream server-side); returns an id (e.g. asset-20260802183721-n4kcy);
• An asset must belong to a group. IDs are globally unique; ownership is recorded by the platform.

Endpoint Overview

Operation	Method & Path	Notes
Create group	POST $URL/v3/asset-groups	body {"name":"..."}
List groups	GET $URL/v3/asset-groups	own groups only
Upload asset	POST $URL/v3/assets	header group_id + body {"url":"..."}
List assets	GET $URL/v3/assets	own assets only
Asset detail	POST $URL/v3/assets/detail	header group_id + body {"assetId":"..."}
Delete asset	DELETE $URL/v3/assets/{assetId}	header group_id
Delete group	DELETE $URL/v3/asset-groups/{groupId}	fails if the group still has assets

1. Create Group POST /v3/asset-groups

Request

POST $URL/v3/asset-groups
Content-Type: application/json

{ "name": "My group" }

Response Fields

Field	Type	Description
code	integer	Status code (200 = success)
msg	string	Message
data.groupId	string	New group ID
data.name	string	Group name

Response Example

{ "code": 200, "msg": "ok", "data": { "groupId": "group-xxx", "name": "My group" } }

Upstream jitter

Creation may occasionally return 409 record already exists (~50% chance, upstream jitter) — just retry the same request. Group names are globally unique; duplicate names return 500 same-name group exists.

2. List Groups GET /v3/asset-groups

Request

GET $URL/v3/asset-groups

Response Fields

Field	Type	Description
code	integer	Status code
data.items	array	Group list
data.items[].groupId	string	Group ID
data.items[].name	string	Group name
data.items[].createTime	integer	Creation time (ms timestamp)

Response Example

{ "code": 200, "data": { "items": [ { "groupId": "group-xxx", "name": "My group", "createTime": 1785667041000 } ] } }

Served by the platform from its ownership table (the upstream has no list endpoint), isolated per customer; createTime in milliseconds.

3. Upload Asset POST /v3/assets

Request

POST $URL/v3/assets
Content-Type: application/json
group_id: {groupId}          ← required: the group this asset belongs to

{ "url": "https://example.com/ref.png" }

Response Fields

Field	Type	Description
code	integer	Status code
data.id	string	Asset ID
data.url	string	Asset URL
data.assetType	string	Image / Video
data.status	string	Processing / other
data.groupId	string	Owning group ID

Response Example

{ "code": 200, "data": { "id": "asset-xxx", "url": "https://...", "assetType": "Image", "status": "Processing", "groupId": "group-xxx" } }

Field notes

group_id goes in the Header (upstream contract); the body field name is snake_case group_id — camelCase groupId does not work. A fresh asset is Processing (upstream is fetching the URL) and cannot be deleted until processing finishes — retry later.

4. List Assets GET /v3/assets

Response Fields

Field	Type	Description
code	integer	Status code
data.items	array	Asset list
data.items[].assetId	string	Asset ID
data.items[].name	string	Asset name
data.items[].url	string	Asset URL
data.items[].groupId	string	Owning group ID
data.items[].status	string	Processing etc.
data.items[].createTime	integer	Creation time (ms timestamp)

Response Example

{ "code": 200, "data": { "items": [ { "assetId": "asset-xxx", "name": "", "url": "https://...", "groupId": "group-xxx", "status": "Processing", "createTime": 1785667041000 } ] } }

5. Asset Detail POST /v3/assets/detail

POST $URL/v3/assets/detail
Content-Type: application/json
group_id: {groupId}

{ "assetId": "asset-xxx" }

Returns the full asset info (including the latest status).

6. Delete Asset DELETE /v3/assets/{assetId}

DELETE $URL/v3/assets/{assetId}
group_id: {groupId}

• Deleting a Processing asset returns 500 asset is uploading/reviewing/in use, retry later — wait until processing finishes;
• After a successful delete the ownership record is cleared; a repeated delete returns 403.

7. Delete Group DELETE /v3/asset-groups/{groupId}

DELETE $URL/v3/asset-groups/{groupId}

• A group with assets cannot be deleted (500 group still has assets) — delete its assets first;
• After a successful delete the ownership record is cleared.

Referencing in Video Generation

Put the asset URL into the native Seedance V3 task content[] (image_url / video_url types):

{
  "model": "doubao-seedance-2.0",
  "content": [
    { "type": "text", "text": "Make the person in this photo wave their hand" },
    { "type": "image_url", "image_url": { "url": "https://example.com/ref.png" } }
  ],
  "resolution": "720p",
  "duration": 5
}

Isolation & Error Codes

The gateway enforces ownership: groups/assets are registered on creation/upload, and delete/detail requests are validated against the current customer — unauthorized access returns 403.

HTTP	code / message	Meaning / Handling
403	forbidden	Not your group/asset (or unregistered)
400	group_id_required	Upload missing group_id
500	asset URL required	Upload missing url
500	group name required	Create group missing name
500	same-name group exists	Group name is globally unique; rename
500	group_id required	Delete/detail missing header group_id
500	asset uploading... / group still has assets...	State restriction; retry or delete assets first
404	Invalid URL	Check the path (/v3/assets*, not /v1/assets)