Asset Groups

An asset group is a container for assets. Before submitting images, you need a virtual asset group.

Create an Asset Group

POST/api/v1/materials/groups

Authentication

Authorization: Bearer <API_KEY>, using a platform API key created under "API Keys" in the console.

Request Body · application/json

Prop

Type

Within the same account, a group with the same name and type is not created again; repeated calls return the existing group directly.

Request Example

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

To create a portrait group, use the same API and just change type to 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

Response Parameters

Parameter	Type	Description
`code`	integer	`0` on success
`msg`	string	`素材分组已创建` on success
`data.group.id`	string	The group ID used by the current account; used as `group_id` when submitting assets later
`data.group.platform_group_id`	string	The platform group ID in the asset service, used for troubleshooting; in the current deployment it is usually the same as `id`
`data.group.name`	string	Group name
`data.group.type`	string	`virtual` or `real`
`data.group.description`	string / null	Group description, `null` when not provided
`data.group.created_at`	integer	Creation time (Unix seconds)
`data.group.updated_at`	integer	Update time (Unix seconds)

Response Body

{
  "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": "素材分组已创建"
}

Error Responses

HTTP	msg	Description
`400`	`请求体必须是 JSON 对象`	The request body is not valid JSON
`400`	`type 只能是 virtual 或 real`	Invalid `type` value
`400`	`素材分组名称不能为空`	`name` is missing
`400`	`素材分组名称不能超过 64 个字符`	`name` is too long
`400`	`素材分组说明不能超过 300 个字符`	`description` is too long
`401`	`Invalid token`	The API key is missing, wrong, or expired
`502` / `503`	`素材服务暂不可用`	The asset service is abnormal; keep the request information and retry

Query Asset Groups

GET/api/v1/materials/groups

Authentication

Authorization: Bearer <API_KEY>. GET requests must also include it.

Request Parameters · query

Parameter	Type	Required	Default	Description
`page`	integer	No	`1`	Page number; values less than 1 are treated as 1
`page_size`	integer	No	`20`	Items per page, maximum 100; out-of-range values are treated as 20

Request Example

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

Response Parameters

Parameter	Type	Description
`code`	integer	`0` on success
`msg`	string	`OK` on success
`data.total`	integer	Total number of groups in the current account
`data.page`	integer	Current page number
`data.page_size`	integer	Items per page for this request
`data.groups`	array	Group list; fields are the same as the create API; contains only the current account's own groups

Response Body

{
  "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"
}

Error Responses

HTTP	msg	Description
`401`	`Invalid token`	The API key is missing, wrong, or expired
`500` / `502` / `503`	`素材服务暂不可用`	The asset service is abnormal; keep the request information and retry

On this page