素材分組

素材分組是素材的容器。提交圖片前需要先有一個虛擬素材分組。

建立素材分組

POST/api/v1/materials/groups

驗證方式

Authorization: Bearer <API_KEY>，使用主控台「API 金鑰」建立的平台 API Key。

請求內容 · application/json

Prop

Type

同一個帳號下同名同類型的分組不會重複建立，重複呼叫直接傳回已有分組。

請求範例

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/groups" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "品牌虚拟角色",
  "description": "电商视频人物设定图",
  "type": "virtual"
}
JSON

建立真人分組使用同一個介面，只把 type 換成 real：

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/groups" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "真人素材库",
  "description": "已完成授权的真人素材",
  "type": "real"
}
JSON

回應參數

參數	類型	說明
`code`	integer	成功時為 `0`
`msg`	string	成功時為 `素材分组已创建`
`data.group.id`	string	目前帳號使用的分組 ID，後續提交素材時作為 `group_id`
`data.group.platform_group_id`	string	素材服務的平台分組 ID，用於排查；目前部署通常與 `id` 相同
`data.group.name`	string	分組名稱
`data.group.type`	string	`virtual` 或 `real`
`data.group.description`	string / null	分組說明，未填寫時為 `null`
`data.group.created_at`	integer	建立時間（Unix 秒）
`data.group.updated_at`	integer	更新時間（Unix 秒）

回應內容

{
  "code": 0,
  "data": {
    "group": {
      "id": "group-1789069780-5762d1",
      "platform_group_id": "group-1789069780-5762d1",
      "name": "品牌虚拟角色",
      "type": "virtual",
      "description": "电商视频人物设定图",
      "created_at": 1789069780,
      "updated_at": 1789069780
    }
  },
  "msg": "素材分组已创建"
}

錯誤回應

HTTP	msg	說明
`400`	`请求体必须是 JSON 对象`	請求內容不是合法 JSON
`400`	`type 只能是 virtual 或 real`	`type` 取值錯誤
`400`	`素材分组名称不能为空`	缺少 `name`
`400`	`素材分组名称不能超过 64 个字符`	`name` 過長
`400`	`素材分组说明不能超过 300 个字符`	`description` 過長
`401`	`Invalid token`	API Key 缺少、錯誤或已失效
`502` / `503`	`素材服务暂不可用`	素材服務異常，保留請求資訊後重試

查詢素材分組

GET/api/v1/materials/groups

驗證方式

Authorization: Bearer <API_KEY>。GET 請求同樣必須攜帶。

請求參數 · query

參數	類型	必填	預設	說明
`page`	integer	否	`1`	頁碼，小於 1 時以 1 處理
`page_size`	integer	否	`20`	每頁筆數，最大 100，超出範圍時以 20 處理

請求範例

curl "$LOCOPAL_BASE_URL/api/v1/materials/groups?page=1&page_size=20" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

回應參數

參數	類型	說明
`code`	integer	成功時為 `0`
`msg`	string	成功時為 `OK`
`data.total`	integer	目前帳號的分組總數
`data.page`	integer	本次頁碼
`data.page_size`	integer	本次每頁筆數
`data.groups`	array	分組清單，欄位與建立介面一致；只包含目前帳號自己的分組

回應內容

{
  "code": 0,
  "data": {
    "groups": [
      {
        "id": "group-1789069780-5762d1",
        "platform_group_id": "group-1789069780-5762d1",
        "name": "品牌虚拟角色",
        "type": "virtual",
        "description": "电商视频人物设定图",
        "created_at": 1789069780,
        "updated_at": 1789069780
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  },
  "msg": "OK"
}

錯誤回應

HTTP	msg	說明
`401`	`Invalid token`	API Key 缺少、錯誤或已失效
`500` / `502` / `503`	`素材服务暂不可用`	素材服務異常，保留請求資訊後重試

本頁目錄