API — Предметка

Начало

Все запросы отправляются на адрес:

https://nanobanana.neuroseti.info/api/v1

API доступен на тарифах «Магазин» и «Каталог». Обработка асинхронная: запрос ставит кадр в очередь и сразу возвращает его id, а результат вы забираете запросом статуса или получаете уведомлением.

Официальных библиотек нет — API достаточно простого HTTP-клиента. Примеры ниже на cURL.

Ключи

Ключ создаётся в студии: Настройки → API → Новый ключ. Боевые ключи начинаются с pk_live_, тестовые — с pk_test_: они возвращают заглушку и не списывают кадры.

Передавайте ключ в заголовке Authorization:

Authorization: Bearer pk_live_3f9c…

Без ключа или с отозванным ключом сервер отвечает 401:

{ "detail": "Not authenticated" }

Не вставляйте ключ в код сайта или мобильного приложения. Запросы к API должны идти с вашего сервера.

Обработать кадр

POST/api/v1/shots

Тело — multipart/form-data с файлом в поле image (JPEG, PNG, WebP или HEIC до 30 МБ) и параметрами кадра. Вместо файла можно передать image_url — публичную ссылку на изображение.

запрос

curl https://nanobanana.neuroseti.info/api/v1/shots \
  -H "Authorization: Bearer $PREDMETKA_KEY" \
  -F image=@art-10482.jpg \
  -F sku=art-10482 \
  -F backdrop=mint \
  -F light=right-soft \
  -F shadow=contact \
  -F format=3x4

202 Accepted

{
  "id": "sh_7Kq2mX0f",
  "status": "queued",
  "sku": "art-10482",
  "created_at": "2026-11-05T10:42:17+03:00",
  "eta_seconds": 26
}

Результат

GET/api/v1/shots/{id}

Статусы по порядку: queued → cutting → rendering → done. При ошибке — failed с полем error. Опрашивайте не чаще раза в 2 секунды или подключите уведомления.

{
  "id": "sh_7Kq2mX0f",
  "status": "done",
  "sku": "art-10482",
  "result": {
    "url": "https://nanobanana.neuroseti.info/files/sh_7Kq2mX0f/art-10482.jpg",
    "width": 900, "height": 1200, "bytes": 214388,
    "expires_at": "2026-12-05T10:42:44+03:00"
  },
  "mask_url": "https://nanobanana.neuroseti.info/files/sh_7Kq2mX0f/mask.png"
}

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

GET/api/v1/backdrops

Список доступных фонов: идентификатор, название и HEX. Сюда же попадают ваши сохранённые пресеты с префиксом my_.

Параметры кадра

Поле	Значения	По умолчанию
backdrop	id фона из `/backdrops`, `#RRGGBB` или `transparent`	white
light	`left-soft`, `right-soft`, `top-soft`, `left-hard`, `right-hard`, `none`	left-soft
shadow	`cast`, `contact`, `reflection`, `none`	cast
format	`3x4`, `1x1`, `4x5`, `16x9` или `WxH` в пикселях	3x4
padding	поля вокруг товара, 0–40 % стороны кадра	12
output	`jpg`, `png`, `webp`	jpg
sku	артикул, до 64 символов: станет именем файла	имя загруженного файла
callback_url	HTTPS-адрес для уведомления	—

Архивы

POST/api/v1/batches

ZIP до 2 ГБ и 500 изображений. Параметры кадра применяются ко всем файлам, артикулом становится имя файла без расширения. В ответе — batch_id; прогресс отдаёт GET /api/v1/batches/{batch_id}, готовый архив — поле archive_url.

Одновременно обрабатывается до двух архивов на аккаунт, остальные ждут в очереди.

Уведомления

Если передан callback_url, после завершения кадра или архива мы отправим туда POST с тем же JSON, что возвращает запрос статуса. Запрос подписан: заголовок X-Predmetka-Signature содержит HMAC-SHA256 тела, ключ подписи показан в настройках API.

Ответьте кодом 2xx в течение 10 секунд. Если не получилось, повторим через 1, 5 и 30 минут.

Ошибки

Ошибки возвращаются с кодом HTTP и телом {"detail": "…", "code": "…"}.

HTTP	code	Что делать
400	invalid_image	Файл повреждён или формат не поддерживается
400	no_object	Не нашли на фото товар: переснимите крупнее
401	—	Нет ключа или ключ отозван
402	quota_exceeded	Закончились кадры и достигнут лимит расходов
413	too_large	Файл больше 30 МБ или архив больше 2 ГБ
422	rejected_content	На фото люди, документы или деньги
429	rate_limited	Превышен лимит запросов, см. заголовок `Retry-After`

Лимиты

Тариф	Запросов в секунду	Кадров в обработке
Магазин	5	20
Каталог	20	100

Опрос статуса в лимит запросов не входит. Если нужен лимит выше, напишите в поддержку из студии.

Изменения

5 ноября 2026. Параметр shadow=reflection для глянцевых фонов.
14 октября 2026. Поддержка HEIC: фото с iPhone можно загружать без конвертации.
22 сентября 2026. Поле mask_url в ответе статуса.
1 сентября 2026. Запуск API v1.

API Предметки