API для генерации фото товаров
Обновлено: 23 сентября 2026
Учётная программа ломбарда, витрина магазина или CRM присылает фото вещи и выбранную сцену. banan.wtf ставит задачу в ту же очередь, что и студия, а по готовности отдаёт постоянные ссылки на кадры, вебхук и фид для Авито Автозагрузки. Лимиты тарифа, общий пул организации и метки точек работают так же, как для человека за прилавком.
Подключить организацию Тарифы и цены
Что умеет API
- Задача по фото и сцене. Исходник — ссылкой или в base64, сцена — из каталога готовых сцен, либо своё описание задачи.
- Постоянные ссылки на кадры. Готовые кадры доступны по прямым ссылкам без авторизации: их забирают Авито и сайт клиента.
- Фид Авито Автозагрузки. Готовые задачи с полями объявления собираются в XML-фид; в кабинете Авито достаточно указать его адрес.
- Вебхуки. События job.completed и job.failed с подписью HMAC-SHA256 и повторами доставки.
- Безопасные повторы. Заголовок Idempotency-Key или externalId: повтор запроса возвращает ту же задачу без второго списания.
- Точки и пул. Метка точки в каждой задаче для отчёта по точкам; задачи участников организации списываются с общего пула.
Как получить ключ
Ключ выпускается в студии: «Настройки» → «API для интеграции». Раздел доступен бизнес-аккаунтам и участникам организации. Секрет ключа и секрет подписи вебхуков показываются один раз, у нас хранится только их хэш. На аккаунт — до 10 активных ключей, отзыв действует сразу. Для сети точек подойдёт командное подключение с оплатой по счёту.
Методы
Базовый адрес: https://banan.wtf/api/integration/v1, авторизация: Authorization: Bearer bnk_….
| Метод | Путь | Что делает |
|---|---|---|
| GET | /me | аккаунт, пул организации и сведения о ключе |
| GET | /scenes | группы готовых сцен с полями и форматами |
| POST | /jobs | создать задачу (ответ 202) |
| GET | /jobs/:id | статус задачи и ссылки на кадры |
| GET | /feeds/avito.xml | фид Авито Автозагрузки из готовых задач |
Пример
curl -X POST https://banan.wtf/api/integration/v1/jobs \
-H "Authorization: Bearer bnk_…" \
-H "Idempotency-Key: INV-2026-000123" \
-H "Content-Type: application/json" \
-d '{
"imageUrl": "https://cdn.example.com/items/123.jpg",
"sceneId": "resale_clean_asis",
"aspectRatio": "4:3",
"branch": "Ленина, 12",
"externalId": "INV-2026-000123",
"webhookUrl": "https://erp.example.com/hooks/banan",
"listing": { "Title": "Кольцо 585, 3,2 г", "Price": 12000 }
}'
Ответ 202 содержит задачу со статусом queued. Когда статус станет completed, в поле frames появятся ссылки на кадры:
{
"id": "66f…",
"status": "completed",
"scene": { "id": "resale_clean_asis", "variantId": null },
"externalId": "INV-2026-000123",
"frames": [{ "index": 0, "url": "https://studio.banan.wtf/f/<token>.jpg" }]
}
Лимиты и вебхуки
- До 600 запросов в минуту на чтение и до 60 новых задач в минуту на ключ.
- Исходное фото — до 25 МБ; ссылки на фото и адреса вебхуков принимаются только публичные.
- Когда объём тарифа исчерпан, API отвечает
402 limit_reached. - Вебхук приходит POST-запросом с заголовками
X-Banan-EventиX-Banan-Signature. Если ваш сервер не ответил, доставка повторяется через 30 секунд, 2 минуты, 10 минут и час.
Интеграторам
Если вы подключаете клиентов через свою учётную программу, регистрируйте их по своей партнёрской ссылке: партнёрская программа платит 30% с каждой их оплаты пожизненно.
Частые вопросы
Нужна ли подписка, чтобы работать через API?
Задачи из API списываются из объёма тарифа или общего пула организации так же, как генерации из студии. Без платной подписки на кадрах остаётся метка сервиса. Цены тарифов и комплектов — на странице banan.wtf/tarify/.
Как передать кадры в Авито?
Укажите в кабинете Авито Автозагрузки адрес фида /api/integration/v1/feeds/avito.xml с вашим ключом. В фид попадают готовые задачи, для которых вы передали поля объявления: заголовок, описание, цену, категорию.
Что будет, если запрос отправится дважды?
Передайте заголовок Idempotency-Key или externalId: повтор вернёт ту же задачу с ответом 200, второго списания не будет. Одновременные дубли тоже схлопываются в одну задачу.
Можно ли описать задачу своими словами вместо сцены?
Да. В задаче нужно указать sceneId или prompt, достаточно одного из них. Список сцен отдаёт метод /scenes, те же сцены доступны в студии и на странице готовых сцен.
Сколько запросов можно отправлять?
До 600 запросов в минуту на чтение и до 60 новых задач в минуту на один ключ. Исходное фото — до 25 МБ по ссылке или в base64. Когда объём тарифа исчерпан, API отвечает 402 limit_reached.
О сервисе · Тарифы · Готовые сцены · Для ломбардов и Авито · Оферта · Конфиденциальность