跳至主要內容
LocoPal AiLocoPal Ai
素材庫素材庫介面

使用指南

素材

提交圖片素材、查詢審核狀態與查詢素材清單

檢視 Markdown

素材

素材提交後由平台非同步處理，狀態從 Processing 變為 Active 後才能用於影片任務。

提交圖片素材

POST/api/v1/materials/assets

驗證方式

Authorization: Bearer <API_KEY>。

請求內容 · application/json

Prop

Type

image_url 與 data_url 只能提交一個。image_url 也可以是 data:image/...;base64,...，平台會把它當作內嵌圖片處理。使用遠端 URL 時，位址必須是平台可以公開下載的 http(s):// 位址（http 和 https 都支援），並且不依賴 Cookie、Referer、登入頁面或瀏覽器工作階段，在平台處理期間保持有效。

遠端 image_url 會先經過平台的快速中轉快取，再由素材庫鏡像，一般圖片通常可以在秒級完成。平台也支援內嵌圖片：可以把 image_url 的值寫成 data:image/...;base64,...，或使用單獨的 data_url 欄位。對於已經在用戶端本機的圖片，內嵌提交可以進一步減少一次外部下載。

data_url 會把整張圖以 base64 上傳（大小約為原圖的 1.33 倍），只在圖片確實無法提供公網位址時使用：例如圖片在需要登入的位址後面、在內網、或只有本機檔案。使用 data_url 時上傳耗時取決於圖片大小和呼叫方頻寬，平台會將圖片寫入短期暫存中轉，而不是永久平台素材儲存。素材庫完成鏡像並進入 Active 後，預覽優先使用素材庫傳回的 preview_url，暫存檔案由中轉服務自動清理。

圖片素材只能提交到 virtual 分組；real 分組的素材由真人掃碼授權流程產生。

request_id 也可以透過 Idempotency-Key 請求標頭提交。相同帳號使用同一個 request_id 重複提交時，平台會傳回第一次建立成功的同一個素材，不會再次建立上游素材。未提交 request_id 時，平台會依帳號、分組、標題和原始圖片酬載自動產生穩定值；同一圖片和標題的重試仍然可以安全重複使用。

請求範例

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/assets" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "group_id": "group-1789069780-5762d1",
  "request_id": "brand-character-front-001",
  "title": "角色正面定妆图",
  "image_url": "$LOCOPAL_IMAGE_URL",
  "tags": ["人物", "正面"]
}
JSON

使用本機圖片時改為提交 data_url：

{
  "group_id": "group-1789069780-5762d1",
  "request_id": "brand-character-front-001",
  "title": "角色正面定妆图",
  "file_name": "person.png",
  "data_url": "data:image/png;base64,iVBORw0KGgo..."
}

如果用戶端希望繼續使用 image_url 欄位，也可以直接提交內嵌圖片：

{
  "group_id": "group-1789069780-5762d1",
  "request_id": "brand-character-front-001",
  "title": "角色正面定妆图",
  "image_url": "data:image/png;base64,iVBORw0KGgo..."
}

回應參數

參數類型說明
codeinteger成功時為 0
msgstring成功時為 图片素材已提交
data.asset_idstring素材 ID，等於 data.asset.id
data.asset.idstring素材 ID，影片任務用 asset://<id> 引用
data.asset.kindstring素材類型，圖片為 image
data.asset.titlestring素材名稱（自動補全後的最終值）
data.asset.request_idstring / null本次上傳使用的冪等請求 ID
data.asset.platform_asset_idstring素材服務的平台素材 ID，用於排查；目前部署通常與 id 相同
data.asset.group_idstring所屬分組 ID
data.asset.statusstring受理後為 Processing
data.asset.error_messagestring / null處理失敗原因，正常為 null
data.asset.notestring / null備註，未提交時為 null
data.asset.tagsstring[]標籤清單，未提交時通常為空陣列
data.asset.mime_typestring / null素材服務傳回的 MIME 類型，未傳回時為 null
data.asset.bytesinteger / null素材檔案大小，素材服務未傳回時為 null
data.asset.created_atinteger建立時間（Unix 秒）
data.asset.updated_atinteger更新時間（Unix 秒）

回應內容

{
  "code": 0,
  "data": {
    "asset_id": "asset-20260911035115-etexu",
    "asset": {
      "id": "asset-20260911035115-etexu",
      "platform_asset_id": "asset-20260911035115-etexu",
      "kind": "image",
      "title": "角色正面定妆图",
      "group_id": "group-1789069780-5762d1",
      "status": "Processing",
      "error_message": null,
      "note": null,
      "tags": [],
      "mime_type": null,
      "bytes": null,
      "created_at": 1789069876,
      "updated_at": 1789069876
    }
  },
  "msg": "图片素材已提交"
}

提交成功只表示素材已受理，提交影片任務前仍要查詢狀態。

錯誤回應

HTTPmsg說明
400缺少 group_id未提供分組
400image_url 必须是可公开下载的 http(s) 地址，当前为 …位址協定不是 http / https，或位址不完整；改用公網 http(s) 位址，或改用 data_url
400image_url 与 data_url 只能提交一个兩個欄位同時提交或都未提交
400data_url 必须是 data:image/...;base64,... 格式data_url 格式錯誤
400图片数据无效或超过 20MB圖片資料為空或超過 20 MB
400素材名称不能为空 / 素材名称不能超过 64 个字符title 驗證失敗
401Invalid tokenAPI Key 缺少、錯誤或已失效
404素材分组不存在或不属于当前账号group_id 錯誤或不屬於目前帳號
404素材分组不存在或不是虚拟素材分组向 real 分組提交圖片
502 / 503素材服务暂不可用素材服務異常，保留請求資訊後重試

查詢單一素材

GET/api/v1/materials/assets/{asset_id}

驗證方式

Authorization: Bearer <API_KEY>。

請求參數 · path

Prop

Type

請求範例

curl "$LOCOPAL_BASE_URL/api/v1/materials/assets/asset-20260911035115-etexu" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

回應參數

參數類型說明
codeinteger成功時為 0
msgstring成功時為 OK
data.assetobject素材物件，欄位同提交介面

data.asset.status 的取值與處理方式：

狀態含義程式行為
Processing素材仍在處理或審核儲存 asset_id，稍後查詢，不要重複提交
Active素材可用於支援該素材類型的任務在影片 content 中使用 asset://<asset_id>
Failed素材處理失敗讀取 error_message，修正來源圖片後建立新的素材

回應內容

{
  "code": 0,
  "data": {
    "asset": {
      "id": "asset-20260911035115-etexu",
      "platform_asset_id": "asset-20260911035115-etexu",
      "kind": "image",
      "title": "角色正面定妆图",
      "group_id": "group-1789069780-5762d1",
      "status": "Active",
      "error_message": null,
      "note": null,
      "tags": [],
      "mime_type": null,
      "bytes": null,
      "created_at": 1789069876,
      "updated_at": 1789069877
    }
  },
  "msg": "OK"
}

審核失敗同樣傳回 HTTP 200，失敗原因在 error_message：

{
  "code": 0,
  "data": {
    "asset": {
      "id": "asset-20260911035115-etexu",
      "status": "Failed",
      "error_message": "素材处理失败"
    }
  },
  "msg": "OK"
}

錯誤回應

HTTPmsg說明
401Invalid tokenAPI Key 缺少、錯誤或已失效
404素材不存在或无权访问素材 ID 錯誤、已刪除或不屬於目前帳號
502 / 503素材服务暂不可用素材服務異常，保留請求資訊後重試

查詢素材清單

GET/api/v1/materials/assets

驗證方式

Authorization: Bearer <API_KEY>。

請求參數 · query

參數類型必填預設說明
pageinteger否1頁碼
page_sizeinteger否20每頁筆數，最大 100
group_idstring否—只傳回該分組下的素材

請求範例

curl "$LOCOPAL_BASE_URL/api/v1/materials/assets?page=1&page_size=20&group_id=group-1789069780-5762d1" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

回應參數

參數類型說明
codeinteger成功時為 0
msgstring成功時為 OK
data.totalinteger符合條件的素材總數
data.page / data.page_sizeinteger本次分頁參數
data.assetsarray素材清單，欄位同提交介面

回應內容

{
  "code": 0,
  "data": {
    "assets": [
      {
        "id": "asset-20260911035115-etexu",
        "platform_asset_id": "asset-20260911035115-etexu",
        "kind": "image",
        "title": "角色正面定妆图",
        "group_id": "group-1789069780-5762d1",
        "status": "Active",
        "error_message": null,
        "note": null,
        "tags": [],
        "mime_type": null,
        "bytes": null,
        "created_at": 1789069876,
        "updated_at": 1789069877
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  },
  "msg": "OK"
}

錯誤回應

HTTPmsg說明
401Invalid tokenAPI Key 缺少、錯誤或已失效
404素材分组不存在或无权访问指定的 group_id 不存在或不屬於目前帳號
500 / 502 / 503素材服务暂不可用素材服務異常，保留請求資訊後重試
這一頁有幫助嗎？

素材分組

建立與查詢素材分組的介面說明

同步素材狀態

依目前帳號重新整理分組與素材的名稱、狀態、錯誤資訊和存取位址

本頁目錄

素材提交圖片素材驗證方式請求內容 · application/json請求範例回應參數回應內容錯誤回應查詢單一素材驗證方式請求參數 · path請求範例回應參數回應內容錯誤回應查詢素材清單驗證方式請求參數 · query請求範例回應參數回應內容錯誤回應