Обзор интерфейсов библиотеки материалов

Интерфейсы библиотеки материалов используются для создания групп материалов, отправки изображений, запроса статуса материалов, синхронизации материалов и запуска авторизации образа реального человека по QR-коду. Все интерфейсы используют один и тот же платформенный API Key, не требуют дополнительной подписи и обращения к другим сервисам.

Общие соглашения (базовый адрес, способ аутентификации, ограничение частоты запросов, идемпотентность) см. в разделе Аутентификация и базовые соглашения.

Конкретные интерфейсы:

Перечень интерфейсов

Единая структура ответа

Успех:

{ "code": 0, "data": {}, "msg": "OK" }

При ошибке HTTP-код состояния совпадает с code, а data равно null:

{ "code": 404, "data": null, "msg": "素材不存在或无权访问" }

Фактическая структура data

data — это объект, а не массив; конкретные поля зависят от интерфейса. В интерфейсах списков коллекция находится под именованным ключом:

{
  "code": 0,
  "data": {
    "groups": [
      { "id": "group-1789069780-5762d1", "name": "我的角色素材", "type": "virtual" }
    ],
    "page": 1,
    "page_size": 20,
    "total": 4
  },
  "msg": "OK"
}

Не предполагайте, что data — это сразу массив. Список групп находится в data.groups, список материалов — в data.assets. При чтении коллекции используйте именованные ключи и проверяйте data.total, чтобы понять, есть ли следующая страница.

Внимание: у автоматически зарегистрированных ресурсов может не быть id

У автоматически зарегистрированных платформой групп материалов id и platform_group_id могут быть пустыми строками:

{ "id": "", "platform_group_id": "", "name": "自动登记素材", "type": "virtual" }

Не используйте id как уникальный ключ для хранения или объединения результатов списка, иначе несколько автоматически зарегистрированных записей перезапишут друг друга. Рекомендуется использовать комбинацию platform_group_id || id || name или просто пропускать записи, которые нельзя использовать в последующих вызовах интерфейсов. Единственное исключение — сбой аутентификации: если API Key отсутствует, неверен или истёк, возвращается HTTP 401, а тело ответа — {"error":{"code":"","message":"Invalid token (request id: ...)","type":"new_api_error"}}.

Подготовка переменных

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_BASE_URL="https://locopalai.com"
export LOCOPAL_IMAGE_URL="https://你的对象存储域名/person.png"

Описание ID материала

Возвращаемое интерфейсом data.asset_id (равное data.asset.id) — это уникальный ID материала. ID материала, отображаемый в списке «Управление материалами» консоли, имеет то же значение, и его можно использовать взаимозаменяемо, без необходимости сопоставления в программе.

Материалы принадлежат учётной записи, а не отдельному API Key. В рамках одной учётной записи можно менять Key, создавать новый Key или переключать группу вызовов — существующие материалы остаются доступными для запроса и использования; другие учётные записи их не видят и не могут на них ссылаться.

Модели и библиотека материалов

Материалы хранятся в единой библиотеке материалов платформы: достаточно добавить материал один раз, и перечисленные ниже модели напрямую используют один и тот же материал — не нужно готовить отдельную копию для какой-либо модели или повторно отправлять материал на проверку.

Следовательно:

• материал добавляется в библиотеку один раз; при смене модели меняется только поле model в запросе, ID материала менять не нужно;
• не нужно создавать отдельную группу для каждой модели и указывать, «в какую библиотеку материалов поместить материал»;
• материалы реальных людей хранятся в библиотеке материалов с поддержкой живой авторизации; модели, поддерживающие ссылки на них: doubao-seedance-2.0-D, doubao-seedance-2.0-D-fast, doubao-seedance-2.0-D-mini, doubao-seedance-2.5-D, seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, seedance-2.5; при отправке материалов реального человека в другие модели возвращается понятная ошибка — не заменяйте их обычным URL изображения, чтобы обойти ограничение.

После того как статус материала становится Active, его можно использовать в любой модели, поддерживающей ссылки на материалы, без ожидания повторной подготовки на стороне модели.

Существующие материалы, добавленные ранее, будут один раз подготовлены платформой при первом обращении со стороны какой-либо модели; после завершения подготовки они ведут себя так же, как материалы, на которые ссылаются напрямую; для новых материалов этот шаг больше не нужен.