素材庫介面概覽

素材庫介面用於建立素材分組、提交圖片、查詢素材狀態、同步素材和發起真人掃碼授權。所有介面使用同一把平台 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 後即可在任意支援素材引用的模型中使用，不需要等待模型端再次準備。

在此之前的存量素材會在首次被某個模型引用時由平台準備一次，準備完成後與直接引用的素材行為一致；新入庫的素材不再需要這一步。