Asset Library API

Upload, query, and reference image / video / audio assets for use with Seedance video generation.

The asset library centrally manages reusable reference assets. Upload once, then reference them by official_id in video generation requests, avoiding embedding large files or re-uploading on every request.

Basic Info

Item	Value
Endpoint Prefix	`https://qfzyapi.qfzy.art/api/asset-library`
Authentication	See "Authentication" below

Authentication

Method	Usage	Scenario
API token	`Authorization: Bearer sk-xxx`	Server-side integration
User Access Token	`Authorization: Bearer {access_token}`	Platform calling on behalf of a user
Session Cookie	Cookie carries the session	Browser-side debugging

Some endpoints also require the New-Api-User request header to identify the user.

Field Conventions

Field	Description
`library_id`	Asset library ID
`official_id`	The asset's official ID upstream; used when referencing
`group_id`	Owning group
`asset_type`	Asset type: `image` / `video` / `audio`
`status`	Asset status

Endpoint Overview

Method	Path	Description
GET	`/api/asset-library/libraries`	List asset libraries
POST	`/api/asset-library/libraries`	Create an asset library
GET	`/api/asset-library/libraries/{library_id}`	Get asset library details
GET	`/api/asset-library/assets`	List assets
POST	`/api/asset-library/assets`	Upload an asset
GET	`/api/asset-library/assets/{official_id}`	Get asset details
DELETE	`/api/asset-library/assets/{official_id}`	Delete an asset
POST	`/api/asset-library/assets/{official_id}/refresh`	Refresh asset status
GET	`/api/asset-library/assets/{official_id}/download`	Download / get the asset URL

Upload Asset Example

curl -X POST "https://qfzyapi.qfzy.art/api/asset-library/assets" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "library_id": "2",
    "asset_type": "image",
    "url": "https://example.com/source.png",
    "name": "reference-image-01"
  }'

Referencing in Video Generation

After a successful upload, put the returned official_id into the video generation content:

{
  "model": "doubao-seedance-2-5-260628",
  "content": [
    { "type": "text", "text": "Generate a walking animation of the subject in the reference asset" },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://official/{official_id}" }
    }
  ]
}

Asset State Machine

State	Description
`processing`	Processing (upload / transcode / moderation)
`active`	Available
`failed`	Processing failed

Only assets in the active state can be used for video generation.

Validity and Cleanup

Asset validity is controlled by config.valid_hours. Expired assets are cleaned up by a scheduled task at 3 AM daily. Do not use the asset library as long-term storage.

The asset library must match the channel family. Assets from the BytePlus family cannot be used with Kuaikuai group families, and vice versa. Cross-family references return asset-not-found or unavailable.

On this page