API генерации фото товаров

Учётная программа, витрина или CRM присылает фото и сцену. Обратно приходят готовые кадры по постоянным ссылкам, вебхук и XML-фид для Авито Автозагрузки.

Обновлено: 24 сентября 2026

Слева исходник, справа кадр. Один запрос POST /jobs — один кадр.

Кому подходит

Что умеет API

• Задача по фото и сцене. Фото — ссылкой или в base64. Сцена — одна из 60 в каталоге, из них 7 для б/у вещей. Можно описать задачу своими словами.
• Постоянные прямые ссылки на кадры. Вида https://banan.it.com/f/<token>.jpg, без авторизации. Их забирают Авито и сайт клиента.
• Готовый XML-фид Авито Автозагрузки. Серия кадров одной вещи собирается в одно объявление. Подробно — фид Авито с готовыми фото.
• Вебхуки с подписью HMAC-SHA256. События job.completed и job.failed, 4 повтора доставки.
• Безопасные повторы. С заголовком Idempotency-Key повтор запроса вернёт ту же задачу без второго списания.
• Точки сети. Метка точки branch в задаче — расход по филиалам виден в отчёте.

Цена

Задачи API списываются с рублёвого баланса API по цене за кадр.

• Списываем только за готовый кадр: упавшая задача возвращается на баланс.
• Тестовый ключ бесплатный: модель не вызывается, в ответ приходит тестовый кадр с вашим Idempotency-Key. До 200 тестовых задач в сутки.
• Пополнение картой или СБП — от 500 ₽. Бонус +5 % от 20 000 ₽ и +10 % от 50 000 ₽.
• Баланс API отдельный от тарифа студии.
• Компаниям — по счёту, от 10 000 ₽.

Все цены и примеры расчёта →

Как получить ключ

1. В студии: «Настройки» → «API для интеграции». Ключ выпускает владелец организации или одиночный аккаунт — селлер, магазин или ломбард.
2. Боевой ключ bnk_live_… списывает баланс API. Тестовый bnk_test_… бесплатный и отвечает тестовым кадром.
3. Ключ показывается один раз. У нас хранится только его хэш.
4. Секрет подписи вебхуков тоже показывается один раз. Его можно перевыпустить в тех же настройках.

До 10 активных ключей на аккаунт, отзыв действует сразу. Участники организации ключей не выпускают.

Методы

Базовый адрес https://banan.it.com/api/integration/v1, заголовок Authorization: Bearer bnk_live_…

Полный справочник — документация API. Для генераторов клиентов — openapi.yaml.

Пример

curl -X POST https://banan.it.com/api/integration/v1/jobs \
  -H "Authorization: Bearer bnk_live_…" \
  -H "Idempotency-Key: INV-2026-000123-1" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://cdn.example.com/items/123.jpg",
    "sceneId": "resale_clean_asis",
    "externalId": "INV-2026-000123",
    "branch": "Ленина, 12",
    "webhookUrl": "https://erp.example.com/hooks/banan",
    "listing": { "Title": "Кольцо 585, 3,2 г", "Price": 12000 }
  }'

Ответ 202 — задача в статусе queued. Когда статус станет completed, в frames появятся ссылки:

{
  "success": true,
  "job": {
    "id": "66f…",
    "status": "completed",
    "mode": "live",
    "quality": "standard",
    "priceRub": 19,
    "scene": { "id": "resale_clean_asis", "variantId": null },
    "externalId": "INV-2026-000123",
    "frames": [{ "index": 0, "url": "https://banan.it.com/f/<token>.jpg" }]
  }
}

Лимиты

• На один ключ — до 600 запросов на чтение и до 60 новых задач в минуту.
• Без действующего ключа — до 120 запросов в минуту с одного IP.
• При превышении — ответ 429 rate_limited с заголовком Retry-After.
• Исходное фото — до 25 МБ. Ссылки на фото и адреса вебхуков принимаются только публичные.

Интеграторам

Подключаете клиентов через свою учётную программу — регистрируйте их по своей партнёрской ссылке. Партнёрская программа платит 30 % с каждой их оплаты пожизненно, пополнения баланса API тоже считаются.

Частые вопросы

Нужна ли подписка, чтобы работать через API?

Нет. Задачи API списываются с отдельного рублёвого баланса по цене за кадр: 19 ₽ в качестве «Стандарт», 49 ₽ в «Высоком». Тариф студии и баланс API друг друга не расходуют.

Что будет, если задача не выполнится?

Цена кадра резервируется при создании задачи. Если задача упала, деньги возвращаются на баланс. Списываем только за готовый кадр.

Можно ли попробовать бесплатно?

Да. Тестовый ключ бесплатный: модель не вызывается, задача сразу приходит с тестовым кадром и вашим Idempotency-Key. Вебхук, ссылки и фид работают, пополнять баланс не нужно.

Как передать кадры в Авито?

Передайте в задаче externalId и поля объявления listing. Готовые задачи собираются в XML-фид Авито Автозагрузки, его адрес с токеном только для чтения вставляется в кабинет Авито. Задачи с одним externalId становятся одним объявлением с серией фото.

Что будет, если запрос отправится дважды?

Передайте заголовок Idempotency-Key. Повтор с тем же телом вернёт ту же задачу с ответом 200, второго списания не будет. Тот же ключ с другим телом вернёт ошибку 422.

Сколько запросов можно отправлять?

На один ключ — до 600 запросов на чтение и до 60 новых задач в минуту. Без ключа — до 120 запросов в минуту с одного IP. Исходное фото — до 25 МБ.

Кто может выпустить ключ?

Владелец организации или одиночный аккаунт: селлер маркетплейса, магазин, ломбард. Участники организации ключей не выпускают.

Документация · Цены API · Фид Авито · Готовые сцены · Для ломбардов и Авито · Тарифы студии · О сервисе · Оферта · Конфиденциальность