Библиотека материаловИнтерфейсы библиотеки материалов
Руководство
Группы материалов
Описание интерфейсов создания и запроса групп материалов
Группы материалов
Группа материалов — это контейнер для материалов. Перед отправкой изображения необходимо сначала создать группу виртуальных материалов.
Создание группы материалов
POST
/api/v1/materials/groupsАутентификация
Authorization: Bearer <API_KEY>, используется платформенный API Key, созданный в разделе «API-ключи» консоли.
Тело запроса · 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 | 素材服务暂不可用 | Сбой сервиса материалов; сохраните информацию о запросе и повторите попытку |
Эта страница была полезной?