Nhóm tư liệu

Nhóm tư liệu là nơi chứa tư liệu. Trước khi gửi hình ảnh cần có một nhóm tư liệu ảo.

Tạo nhóm tư liệu

POST/api/v1/materials/groups

Cách xác thực

Authorization: Bearer <API_KEY>, dùng khóa API nền tảng được tạo trong「Khóa API」của bảng điều khiển.

Phần thân yêu cầu · application/json

Prop

Type

Trong cùng một tài khoản, nhóm cùng tên cùng loại sẽ không được tạo trùng; gọi lặp lại sẽ trả về trực tiếp nhóm đã có.

Ví dụ yêu cầu

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

Tạo nhóm người thật dùng cùng API, chỉ đổi type thành 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

Tham số phản hồi

Tham số	Kiểu	Mô tả
`code`	integer	Khi thành công là `0`
`msg`	string	Khi thành công là `素材分组已创建`
`data.group.id`	string	ID nhóm mà tài khoản hiện tại sử dụng, dùng làm `group_id` khi gửi tư liệu sau này
`data.group.platform_group_id`	string	ID nhóm nền tảng của dịch vụ tư liệu, dùng để khắc phục sự cố; triển khai hiện tại thường giống `id`
`data.group.name`	string	Tên nhóm
`data.group.type`	string	`virtual` hoặc `real`
`data.group.description`	string / null	Mô tả nhóm, khi chưa điền là `null`
`data.group.created_at`	integer	Thời gian tạo (giây Unix)
`data.group.updated_at`	integer	Thời gian cập nhật (giây Unix)

Nội dung phản hồi

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

Phản hồi lỗi

HTTP	msg	Mô tả
`400`	`请求体必须是 JSON 对象`	Phần thân yêu cầu không phải JSON hợp lệ
`400`	`type 只能是 virtual 或 real`	Giá trị `type` sai
`400`	`素材分组名称不能为空`	Thiếu `name`
`400`	`素材分组名称不能超过 64 个字符`	`name` quá dài
`400`	`素材分组说明不能超过 300 个字符`	`description` quá dài
`401`	`Invalid token`	Khóa API thiếu, sai hoặc đã hết hiệu lực
`502` / `503`	`素材服务暂不可用`	Dịch vụ tư liệu bất thường, giữ thông tin yêu cầu rồi thử lại

Truy vấn nhóm tư liệu

GET/api/v1/materials/groups

Cách xác thực

Authorization: Bearer <API_KEY>. Yêu cầu GET cũng bắt buộc phải mang theo.

Tham số yêu cầu · query

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`page`	integer	Không	`1`	Số trang, nhỏ hơn 1 sẽ được xử lý như 1
`page_size`	integer	Không	`20`	Số mục mỗi trang, tối đa 100; vượt phạm vi sẽ được xử lý như 20

Ví dụ yêu cầu

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

Tham số phản hồi

Tham số	Kiểu	Mô tả
`code`	integer	Khi thành công là `0`
`msg`	string	Khi thành công là `OK`
`data.total`	integer	Tổng số nhóm của tài khoản hiện tại
`data.page`	integer	Số trang lần này
`data.page_size`	integer	Số mục mỗi trang lần này
`data.groups`	array	Danh sách nhóm, trường giống API tạo; chỉ gồm nhóm của tài khoản hiện tại

Nội dung phản hồi

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

Phản hồi lỗi

HTTP	msg	Mô tả
`401`	`Invalid token`	Khóa API thiếu, sai hoặc đã hết hiệu lực
`500` / `502` / `503`	`素材服务暂不可用`	Dịch vụ tư liệu bất thường, giữ thông tin yêu cầu rồi thử lại

Trong trang này