Материалы

После отправки материал обрабатывается платформой асинхронно; использовать его в видеозадачах можно только после смены статуса с Processing на Active.

Отправка материала-изображения

Аутентификация

Authorization: Bearer <API_KEY>.

Тело запроса · application/json

image_url и data_url — можно передать только одно. image_url также может быть data:image/...;base64,..., и платформа обработает его как встроенное изображение. При использовании удалённого URL адрес должен быть http(s)://-адресом, который платформа может публично скачать (поддерживаются и http, и https), не зависеть от Cookie, Referer, страницы входа или сессии браузера и оставаться действительным на протяжении всей обработки на платформе.

Удалённый image_url сначала проходит через быстрый промежуточный кеш платформы, а затем зеркалируется библиотекой материалов; для обычных изображений это обычно занимает секунды. Платформа также поддерживает встроенные изображения: можно записать значение image_url как data:image/...;base64,... или использовать отдельное поле data_url. Для изображений, уже находящихся на стороне клиента, встроенная отправка позволяет дополнительно избежать одной внешней загрузки.

data_url загружает всё изображение в base64 (объём примерно в 1,33 раза больше оригинала); используйте его только тогда, когда действительно невозможно предоставить публичный адрес изображения: например, изображение находится за адресом, требующим входа, во внутренней сети или существует только как локальный файл. При использовании data_url время загрузки зависит от размера изображения и пропускной способности вызывающей стороны; платформа записывает изображение в краткосрочное временное промежуточное хранилище, а не в постоянное хранилище материалов платформы. После того как библиотека материалов завершит зеркалирование и материал перейдёт в Active, для превью в первую очередь используется preview_url, возвращённый библиотекой материалов, а временные файлы автоматически удаляются сервисом промежуточного хранения.

Материалы-изображения можно отправлять только в группы virtual; материалы группы real создаются в процессе авторизации образа реального человека по QR-коду.

request_id также можно передать через заголовок запроса Idempotency-Key. При повторной отправке в рамках одной учётной записи с тем же request_id платформа вернёт тот же материал, успешно созданный в первый раз, и не будет повторно создавать материал на стороне вышестоящего сервиса. Если request_id не передан, платформа автоматически сформирует стабильное значение на основе учётной записи, группы, названия и исходных данных изображения; повторные попытки с тем же изображением и названием также можно безопасно переиспользовать.

Пример запроса

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/assets" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "group_id": "group-1789069780-5762d1",
  "request_id": "brand-character-front-001",
  "title": "角色正面定妆图",
  "image_url": "$LOCOPAL_IMAGE_URL",
  "tags": ["人物", "正面"]
}
JSON

При использовании локального изображения вместо этого передайте data_url:

{
  "group_id": "group-1789069780-5762d1",
  "request_id": "brand-character-front-001",
  "title": "角色正面定妆图",
  "file_name": "person.png",
  "data_url": "data:image/png;base64,iVBORw0KGgo..."
}

Если клиент хочет продолжать использовать поле image_url, можно также передать встроенное изображение:

{
  "group_id": "group-1789069780-5762d1",
  "request_id": "brand-character-front-001",
  "title": "角色正面定妆图",
  "image_url": "data:image/png;base64,iVBORw0KGgo..."
}

Параметры ответа

Тело ответа

{
  "code": 0,
  "data": {
    "asset_id": "asset-20260911035115-etexu",
    "asset": {
      "id": "asset-20260911035115-etexu",
      "platform_asset_id": "asset-20260911035115-etexu",
      "kind": "image",
      "title": "角色正面定妆图",
      "group_id": "group-1789069780-5762d1",
      "status": "Processing",
      "error_message": null,
      "note": null,
      "tags": [],
      "mime_type": null,
      "bytes": null,
      "created_at": 1789069876,
      "updated_at": 1789069876
    }
  },
  "msg": "图片素材已提交"
}

Успешная отправка означает лишь то, что материал принят; перед отправкой видеозадачи всё равно необходимо запросить статус.

Ответы с ошибками

Запрос одного материала

Аутентификация

Authorization: Bearer <API_KEY>.

Параметры запроса · path

Пример запроса

curl "$LOCOPAL_BASE_URL/api/v1/materials/assets/asset-20260911035115-etexu" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

Параметры ответа

Значения data.asset.status и способы обработки:

Тело ответа

{
  "code": 0,
  "data": {
    "asset": {
      "id": "asset-20260911035115-etexu",
      "platform_asset_id": "asset-20260911035115-etexu",
      "kind": "image",
      "title": "角色正面定妆图",
      "group_id": "group-1789069780-5762d1",
      "status": "Active",
      "error_message": null,
      "note": null,
      "tags": [],
      "mime_type": null,
      "bytes": null,
      "created_at": 1789069876,
      "updated_at": 1789069877
    }
  },
  "msg": "OK"
}

При сбое проверки также возвращается HTTP 200, а причина сбоя находится в error_message:

{
  "code": 0,
  "data": {
    "asset": {
      "id": "asset-20260911035115-etexu",
      "status": "Failed",
      "error_message": "素材处理失败"
    }
  },
  "msg": "OK"
}

Ответы с ошибками

Запрос списка материалов

Аутентификация

Authorization: Bearer <API_KEY>.

Параметры запроса · query

Пример запроса

curl "$LOCOPAL_BASE_URL/api/v1/materials/assets?page=1&page_size=20&group_id=group-1789069780-5762d1" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

Параметры ответа

Тело ответа

{
  "code": 0,
  "data": {
    "assets": [
      {
        "id": "asset-20260911035115-etexu",
        "platform_asset_id": "asset-20260911035115-etexu",
        "kind": "image",
        "title": "角色正面定妆图",
        "group_id": "group-1789069780-5762d1",
        "status": "Active",
        "error_message": null,
        "note": null,
        "tags": [],
        "mime_type": null,
        "bytes": null,
        "created_at": 1789069876,
        "updated_at": 1789069877
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  },
  "msg": "OK"
}

Ответы с ошибками