素材分组

素材分组是素材的容器。提交图片前需要先有一个虚拟素材分组。

创建素材分组

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`	`素材服务暂不可用`	素材服务异常，保留请求信息后重试

本页目录