Asset Library API Overview

The asset library APIs are used to create asset groups, submit images, query asset status, sync assets, and initiate portrait QR code authorization. All APIs use the same platform API key; no extra signing is required, and no other service needs to be called.

For common conventions (base URL, authentication, rate limiting, idempotency), see Authentication and Common Conventions.

Specific APIs:

API List

Unified Response Structure

Success:

{ "code": 0, "data": {}, "msg": "OK" }

On failure, the HTTP status code matches code, and data is null:

{ "code": 404, "data": null, "msg": "素材不存在或无权访问" }

The Actual Structure of data

data is an object, not an array; the specific fields depend on the API. Collections returned by list APIs are under named keys:

{
  "code": 0,
  "data": {
    "groups": [
      { "id": "group-1789069780-5762d1", "name": "我的角色素材", "type": "virtual" }
    ],
    "page": 1,
    "page_size": 20,
    "total": 4
  },
  "msg": "OK"
}

Do not assume data is directly an array. The group list is in data.groups, and the asset list is in data.assets. When reading collections, go through the named keys, and use data.total to determine whether there is a next page.

Note: Automatically Registered Resources May Not Have an id

For asset groups registered automatically by the platform, id and platform_group_id may be empty strings:

{ "id": "", "platform_group_id": "", "name": "自动登记素材", "type": "virtual" }

Do not use id as a unique key to store or merge list results; otherwise multiple automatically registered entries will overwrite each other. It is recommended to use a platform_group_id || id || name combination instead, or simply skip entries that cannot be used in subsequent API calls. The only exception is authentication failure: when the API key is missing, wrong, or expired, HTTP 401 is returned with the response body {"error":{"code":"","message":"Invalid token (request id: ...)","type":"new_api_error"}}.

Prepare Variables

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_BASE_URL="https://locopalai.com"
export LOCOPAL_IMAGE_URL="https://你的对象存储域名/person.png"

Asset ID

The data.asset_id returned by the API (equal to data.asset.id) is the asset's unique ID. The asset ID shown in the console's "Asset Management" list is the same value; the two can be used interchangeably, with no need for mapping in your program.

Assets belong to the account rather than to a particular API key. Within the same account, changing the key, recreating the key, or switching calling groups still lets you query and use existing assets; other accounts cannot see or reference them.

Models and the Asset Library

Assets are hosted by the platform's unified asset library: add an asset once, and the following models all use the same copy directly, with no need to prepare a separate copy for a particular model or resubmit it for review.

Therefore:

• Assets are added to the library only once; when switching models, only the model field in the request changes, and the asset ID does not need to change;
• You do not need to create a separate group for each model, nor specify "which asset library to put the asset in";
• Portrait assets are hosted by the asset library that supports liveness authorization, and the models that support referencing them are doubao-seedance-2.0-D, doubao-seedance-2.0-D-fast, doubao-seedance-2.0-D-mini, doubao-seedance-2.5-D, seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, and seedance-2.5; submitting portrait assets to other models returns a readable error; do not bypass the restriction by changing them into ordinary image URLs.

Once the asset status becomes Active, it can be used in any model that supports asset references, without waiting for the model side to prepare it again.

Existing assets created before this are prepared once by the platform when a model first references them; after preparation they behave the same as directly referenced assets. Newly added assets no longer need this step.