素材库接口概览

素材库接口用于创建素材分组、提交图片、查询素材状态、同步素材和发起真人扫码授权。所有接口使用同一把平台 API Key，不需要额外签名，也不需要调用其他服务。

公共约定（基础地址、认证方式、限流、幂等）见认证与基础规范。

具体接口：

接口一览

统一响应结构

成功：

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

失败时 HTTP 状态码与 code 一致，data 为 null：

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

data 的实际结构

data 是对象而不是数组，具体字段取决于接口。列表接口的集合放在具名键下：

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

不要假设 data 直接就是数组。 分组列表在 data.groups、素材列表在 data.assets。 读取集合时请走具名键，并用 data.total 判断是否还有下一页。

注意：自动登记的资源可能没有 id

平台自动登记的素材分组，id 与 platform_group_id 可能是空字符串：

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

不要用 id 作为唯一键去存储或合并列表结果，否则多个自动登记条目会互相覆盖。 建议改用 platform_group_id || id || name 组合，或直接跳过无法用于后续接口调用的条目。 唯一例外是鉴权失败：API Key 缺失、错误或已失效时返回 HTTP 401，响应体为 {"error":{"code":"","message":"Invalid token (request id: ...)","type":"new_api_error"}}。

准备变量

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

素材 ID 说明

接口返回的 data.asset_id（等于 data.asset.id）就是素材的唯一 ID。控制台「素材管理」列表里显示的素材 ID 与它是同一个值，两处可以互换使用，不需要在程序里做映射。

素材属于账号而不是某一把 API Key。同一账号下更换 Key、重新创建 Key 或切换调用分组，都可以继续查询和使用原有素材；其他账号看不到也无法引用。

模型与素材库

素材由平台统一素材库承载：入库一次，下列模型都直接使用同一份素材，不需要为某个模型单独准备副本，也不需要重新提交审核。

因此：

• 素材只入库一次，换模型时只改请求里的 model 字段，素材 ID 不用变；
• 不需要为每个模型单独建分组，也不需要指定「把素材放进哪个素材库」；
• 真人素材由支持活体授权的素材库承载，支持引用的模型为 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、seedance-2.5；把真人素材提交到其他模型会返回可读错误，不要改成普通图片 URL 绕过限制。

素材状态变为 Active 后即可在任意支持素材引用的模型中使用，不需要等待模型侧再次准备。

在此之前的存量素材会在首次被某个模型引用时由平台准备一次，准备完成后与直接引用的素材行为一致；新入库的素材不再需要这一步。