Документация API

Справочник на одной странице: ключи, методы, ошибки, вебхуки, фид Авито и сцены.

Обновлено: 24 сентября 2026 · Описание для генераторов клиентов — openapi.yaml

1. Быстрый старт
2. Ключи и авторизация
3. Тестовый ключ
4. Формат ответов
5. Методы
6. Баланс
7. POST /jobs
8. Объект задачи
9. Идемпотентность
10. Опрос статуса
11. Вебхуки и подпись
12. Фид Авито
13. Ссылки на кадры
14. Ошибки
15. Лимиты
16. Цены
17. Сцены
18. Файлы для машин

Быстрый старт

1. Выпустите тестовый ключ в студии: «Настройки» → «API для интеграции». Он бесплатный и сразу отвечает тестовым кадром.
2. Создайте задачу:

curl -X POST https://banan.wtf/api/integration/v1/jobs \
  -H "Authorization: Bearer $BANAN_API_KEY" \
  -H "Idempotency-Key: demo-0001" \
  -H "Content-Type: application/json" \
  -d '{ "imageUrl": "https://cdn.example.com/items/123.jpg", "sceneId": "white_main" }'

3. Заберите результат: GET /jobs/{id} или вебхук. Готовые кадры — в job.frames[].url.
4. Для боевых кадров выпустите ключ bnk_live_… и пополните баланс API. Цены — на странице цен.

Ключи и авторизация

Каждый запрос несёт заголовок:

Authorization: Bearer bnk_live_…   # боевой ключ
Authorization: Bearer bnk_test_…   # тестовый ключ

• Боевой ключ списывает рублёвый баланс API по цене за кадр. Без денег на балансе — 402 insufficient_balance, фото при этом не скачивается.
• Тестовый ключ бесплатный и модель не вызывает. До 200 тестовых задач в сутки на аккаунт, дальше — 429 test_daily_limit.
• Задачи, ссылки и фид видны только в режиме своего ключа. Тестовый ключ не видит боевые задачи, и наоборот.
• Ключ выпускает владелец организации или одиночный аккаунт. Участник организации ключей не выпускает и не использует: 403 api_key_member_forbidden.
• Ключ показывается один раз. У нас хранится только хэш ключа.
• Секрет подписи вебхуков показывается один раз при выпуске. Его можно перевыпустить в настройках, старый перестаёт работать.
• До 10 активных ключей на аккаунт. Отзыв действует сразу.

Тестовый ключ

• POST /jobs сразу отвечает 202: задача уже completed, в ней один тестовый кадр.
• На кадре метка «ТЕСТ» и ваш Idempotency-Key, без него — id задачи.
• Фото всё равно скачивается и проверяется. Вебхук, ссылки и фид работают, баланс не тратится.

Формат ответов

Базовый адрес: https://banan.wtf/api/integration/v1. Тела запросов и ответов — JSON в UTF-8.

// успех
{ "success": true, "job": { … } }

// ошибка: code всегда на верхнем уровне
{ "success": false, "code": "scene_unknown", "message": "Неизвестная сцена." }

Коды ошибок — в таблице ниже. Текст message — для человека, решения принимайте по code.

Методы

GET /pricing

Цены за кадр, пороги пополнения, бонусы, условия тестового ключа и правила списания. Ключ не нужен. Содержимое совпадает с pricing.json.

curl https://banan.wtf/api/integration/v1/pricing

GET /me

Кто вы для API: аккаунт и аудитория, режим ключа (live или test), остаток баланса API, сколько тестовых задач уже было сегодня, текущие цены. Удобно для проверки ключа при подключении.

curl https://banan.wtf/api/integration/v1/me -H "Authorization: Bearer $BANAN_API_KEY"

{
  "success": true,
  "account": { "userId": 123456, "audience": { "id": "resale", "label": "…" } },
  "key": { "id": "66f0a1…", "prefix": "bnk_test_a1b2c3", "label": "Учётная программа", "mode": "test" },
  "balance": { "rub": 0, "kopecks": 0 },
  "framesLeft": { "standard": 0, "high": 0 },
  "test": { "static": true, "jobsPerDay": 200, "usedToday": 3 },
  "pricing": { "currency": "RUB", "defaultTier": "standard", "tiers": [ … ] },
  "topupUrl": "https://banan.wtf/profile/settings?section=api"
}

GET /balance

Остаток баланса API и сколько кадров на него выйдет в каждом качестве. Вызывайте перед ночной пачкой и по расписанию, чтобы заранее узнать о низком остатке.

curl https://banan.wtf/api/integration/v1/balance -H "Authorization: Bearer $BANAN_API_KEY"

{
  "success": true,
  "balance": { "rub": 5000, "kopecks": 500000 },
  "framesLeft": { "standard": 263, "high": 102 },
  "topupUrl": "https://banan.wtf/profile/settings?section=api"
}

Остаток после каждой задачи приходит и в ответе POST /jobs, поле balance.

GET /scenes

Группы сцен каталога с полями inputs, вариантами и форматом. Группы аудитории вашего аккаунта идут первыми и помечены "audience": true. Внутренние инструкции модели наружу не отдаются. Таблица всех сцен — ниже.

{
  "success": true,
  "audience": "resale",
  "groups": [
    {
      "id": "resale",
      "title": "Ресейл и ломбарды",
      "audience": true,
      "scenes": [
        {
          "id": "resale_condition_card",
          "groupId": "resale",
          "title": "Карточка состояния",
          "subtitle": "Проба, вес, состояние, комплектность подписями",
          "aspectRatio": "4:3",
          "fidelity": null,
          "inputs": [{ "id": "facts", "label": "Что написать на карточке", "hint": "…", "maxLength": 240, "required": true }],
          "variants": []
        }
      ]
    }
  ]
}

POST /jobs

Создаёт задачу: одно исходное фото → один кадр. Ответ 202 с задачей в статусе queued, без кадров, и остатком баланса после резерва. У тестового ключа задача сразу completed.

curl -X POST https://banan.wtf/api/integration/v1/jobs \
  -H "Authorization: Bearer $BANAN_API_KEY" \
  -H "Idempotency-Key: INV-2026-000123-hallmark" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://cdn.example.com/items/123.jpg",
    "sceneId": "resale_condition_card",
    "inputs": { "facts": "Золото 585, 3,2 г, состояние хорошее" },
    "quality": "standard",
    "fidelity": "preserve_condition",
    "aspectRatio": "4:3",
    "branch": "Ленина, 12",
    "externalId": "INV-2026-000123",
    "webhookUrl": "https://erp.example.com/hooks/banan",
    "listing": {
      "Title": "Кольцо 585, 3,2 г",
      "Price": 12000,
      "Category": "Часы и украшения",
      "Description": "Золото 585, гранат. Состояние хорошее."
    }
  }'

Порядок проверок. Ключ → тело запроса → идемпотентность → деньги или дневной лимит тестового ключа → скачивание фото → резерв и постановка в очередь. Ошибка в теле не тратит ни денег, ни времени на скачивание.

HTTP/1.1 202 Accepted

{
  "success": true,
  "job": {
    "id": "66f2c1…",
    "status": "queued",
    "mode": "live",
    "quality": "standard",
    "priceRub": 19,
    "refunded": false,
    "scene": { "id": "resale_condition_card", "variantId": null },
    "fidelity": "preserve_condition",
    "branch": "Ленина, 12",
    "externalId": "INV-2026-000123",
    "createdAt": "2026-09-24T21:04:03.000Z",
    "completedAt": null,
    "error": null,
    "frames": []
  },
  "balance": { "rub": 1462, "kopecks": 146200 }
}

GET /jobs

Задачи API этого аккаунта в режиме ключа, новые первыми. Параметры, все необязательные:

• externalId — все кадры одной вещи;
• status — queued, processing, completed или failed;
• since — дата ISO 8601, задачи с этого момента;
• limit — от 1 до 100, по умолчанию 50;
• cursor — значение nextCursor из прошлого ответа.

Ответ — { "success": true, "jobs": [ … ], "nextCursor": "…" }. Когда задач больше нет, nextCursor равен null.

curl "https://banan.wtf/api/integration/v1/jobs?externalId=INV-2026-000123&status=completed" \
  -H "Authorization: Bearer $BANAN_API_KEY"

GET /jobs/{id}

Статус задачи и кадры. Видны только задачи API этого аккаунта в режиме ключа: работы из студии через API не читаются. Чужой или несуществующий id — 404 job_not_found.

Объект задачи

Один и тот же объект отдают POST /jobs, GET /jobs, GET /jobs/{id} и вебхук.

{
  "id": "66f2c1…",
  "status": "completed",
  "mode": "live",
  "quality": "standard",
  "priceRub": 19,
  "refunded": false,
  "scene": { "id": "resale_condition_card", "variantId": null },
  "fidelity": "preserve_condition",
  "branch": "Ленина, 12",
  "externalId": "INV-2026-000123",
  "createdAt": "2026-09-24T21:04:03.000Z",
  "completedAt": "2026-09-24T21:05:11.000Z",
  "error": null,
  "frames": [{ "index": 0, "url": "https://banan.wtf/f/Qm9v….jpg" }]
}

Идемпотентность

Сеть оборвалась, ERP повторила запрос — второй задачи и второго списания не будет, если передан заголовок Idempotency-Key.

• Ключ — до 128 символов из A-Za-z0-9_.:-. Другие символы — 400 idempotency_key_invalid.
• Тот же ключ и то же тело — та же задача: ответ 200, поле "replayed": true и заголовок Idempotent-Replayed: true.
• Тот же ключ с другим телом — 422 idempotency_key_reused.
• Задача по ключу упала и деньги вернулись — повтор с тем же ключом создаёт новую попытку.
• Ключ действует в пределах одного API-ключа. Для серии кадров одной вещи давайте каждой задаче свой ключ, например INV-2026-000123-1, …-2.

Опрос статуса

Если вебхук не подходит, опрашивайте GET /jobs/{id} раз в несколько секунд. Для пачки удобнее GET /jobs?status=completed&since=… — один запрос вместо сотни.

const API = 'https://banan.wtf/api/integration/v1';
const headers = { Authorization: `Bearer ${process.env.BANAN_API_KEY}` };
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function waitForJob(id) {
  for (let attempt = 0; attempt < 120; attempt += 1) {
    const res = await fetch(`${API}/jobs/${id}`, { headers });
    if (res.status === 429) {
      await sleep(Number(res.headers.get('Retry-After') || 5) * 1000);
      continue;
    }
    const body = await res.json();
    if (!body.success) throw new Error(body.code);
    if (body.job.status === 'completed' || body.job.status === 'failed') return body.job;
    await sleep(5000);
  }
  throw new Error('job_timeout');
}

Вебхуки

Когда задача завершилась или упала, на её webhookUrl уходит POST:

POST /hooks/banan HTTP/1.1
Content-Type: application/json
X-Banan-Event: job.completed
X-Banan-Signature: sha256=5f1c…e9

{ "event": "job.completed", "occurredAt": "2026-09-24T21:05:12.000Z", "attempt": 1, "job": { … } }

• События: job.completed и job.failed. В job — тот же объект задачи.
• Ответьте любым кодом 2xx в пределах 10 секунд. Иначе доставка повторится через 30 секунд, 2 минуты, 10 минут и 1 час — 4 повтора. После пятой неудачной попытки доставка прекращается.
• Редиректы не выполняются.
• Одно событие может прийти повторно, если ваш ответ потерялся в сети. Отбрасывайте дубли по паре job.id + event.
• Задачи API не шлют уведомления «готово» в студию, пуш и Telegram: для этого у интеграции есть вебхук.

Проверка подписи

Заголовок X-Banan-Signature — это sha256= и HMAC-SHA256 от сырого тела запроса в hex. Ключ HMAC — секрет подписи вашего API-ключа. Считайте подпись по байтам тела до разбора JSON и сравнивайте за постоянное время.

Node.js (Express)

const crypto = require('node:crypto');
const express = require('express');

const app = express();
const SECRET = process.env.BANAN_WEBHOOK_SECRET;

// express.raw: подпись считается по сырому телу, а не по разобранному JSON
app.post('/hooks/banan', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');
  const received = req.get('X-Banan-Signature') || '';
  const valid = received.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).end();

  const { event, job } = JSON.parse(req.body.toString('utf8'));
  // event: job.completed | job.failed; кадры — job.frames[].url
  res.status(204).end();
});

Python (Flask)

import hashlib
import hmac
import os

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["BANAN_WEBHOOK_SECRET"].encode()

@app.post("/hooks/banan")
def banan_hook():
    body = request.get_data()  # сырые байты тела
    expected = "sha256=" + hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    received = request.headers.get("X-Banan-Signature", "")
    if not hmac.compare_digest(expected, received):
        abort(401)
    payload = request.get_json()
    # payload["event"]: job.completed | job.failed
    return "", 204

PHP

<?php
$secret = getenv('BANAN_WEBHOOK_SECRET');
$body = file_get_contents('php://input'); // сырое тело
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
$received = $_SERVER['HTTP_X_BANAN_SIGNATURE'] ?? '';

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

$payload = json_decode($body, true);
// $payload['event']: job.completed | job.failed
http_response_code(204);

Фид Авито Автозагрузки

GET /feeds/avito.xml?token=<токен фида> — готовые задачи с полями listing в формате Авито Автозагрузки formatVersion="3". Адрес вставляется в кабинет Авито: «Автозагрузка» → ссылка на файл.

• У фида свой токен только для чтения. Он выдаётся вместе с ключом и виден в настройках студии. Задачи этим токеном не создать.
• Боевой ключ в адресе не принимается: адрес фида хранится в кабинете Авито и попадает в логи.
• Токен можно перевыпустить в настройках, старый адрес сразу перестаёт работать.
• Задачи с одним externalId — одно объявление <Ad>. <Id> = externalId, без него — id задачи.
• Поля объявления берутся из самой свежей задачи серии, где передан listing: достаточно передать его в одной задаче. <Images> — кадры всех готовых задач серии по времени, до 10.
• В фиде последние 500 задач, параметр ?limit= — до 1000. Фид кешируется на 5 минут.
• Фид тестового ключа показывает только тестовые задачи.

<?xml version="1.0" encoding="UTF-8"?>
<Ads formatVersion="3" target="Avito.ru">
  <Ad>
    <Id>INV-2026-000123</Id>
    <Title>Кольцо 585, 3,2 г</Title>
    <Price>12000</Price>
    <Category>Часы и украшения</Category>
    <Description><![CDATA[Золото 585, гранат. Состояние хорошее.]]></Description>
    <Images>
      <Image url="https://banan.wtf/f/Qm9v…1.jpg"/>
      <Image url="https://banan.wtf/f/Qm9v…2.jpg"/>
      <Image url="https://banan.wtf/f/Qm9v…3.jpg"/>
    </Images>
  </Ad>
</Ads>

Какие поля обязательны для вашей категории, смотрите в справочнике Авито Автозагрузки. Мы передаём listing как есть. Пошагово — фид Авито с готовыми фото.

Ссылки на кадры

• Вид: https://banan.wtf/f/<token>.jpg. Без авторизации и без срока действия — Авито перечитывает их сколько нужно.
• Ответ кешируется на сутки: Cache-Control: public, max-age=86400, есть ETag и 304.
• Кадры боевого ключа — без метки. У тестового ключа — тестовый кадр с меткой.
• Отзыв ссылки и удаление аккаунта доходят до кеша не сразу — до суток.

Ошибки

HTTP/1.1 402 Payment Required

{
  "success": false,
  "code": "insufficient_balance",
  "message": "На балансе API недостаточно денег для этого кадра.",
  "balanceRub": 12,
  "priceRub": 19,
  "topupUrl": "https://banan.wtf/profile/settings?section=api"
}

Лимиты

При превышении — 429 rate_limited и заголовок Retry-After в секундах. Ночную пачку отправляйте ровным потоком, не залпом.

Цены

Боевой ключ списывает рублёвый баланс API по цене за кадр. Баланс API отдельный от тарифа студии.

• Списываем только за готовый кадр: цена резервируется при создании задачи и возвращается на баланс, если задача не выполнена.
• Повтор запроса с тем же Idempotency-Key не списывает второй раз.
• Баланс API отдельный от тарифа студии: задачи API не расходуют лимиты тарифа, а тариф не расходует баланс API.
• Остаток баланса не сгорает.
• Тестовый ключ бесплатный: модель не вызывается, в ответ приходит тестовый кадр с меткой и вашим Idempotency-Key.
• Бонус к пополнению начисляется на баланс сразу вместе с оплатой.

Пополнение картой или СБП — от 500 ₽, по счёту — от 10 000 ₽. Бонусы и примеры расчёта — на странице цен.

Сцены

Всего 26 сцен в 5 группах. Группа ведёт в свой раздел галереи с примерами. Машиночитаемый список — scenes.json, живой — GET /scenes.

До → после	sceneId	Сцена	Формат	inputs	variantId
Одежда на модели
→	clothing_model_studio	На модели в студии Полный рост, светлый фон	3:4	—	—
→	clothing_model_street	На модели на улице Городская улица, мягкий свет	3:4	—	—
→	clothing_model_back	Со спины Спинка, плечи, длина	3:4	—	—
→	clothing_model_walk	В движении Кадр в шаге, ткань в движении	3:4	—	—
→	clothing_detail	Фактура крупно Ткань, швы, фурнитура	3:4	—	—
	clothing_model_other	Другой типаж модели Размер, возраст, внешность	3:4	—	plus, asian, mature, man, woman
Инфографика
→	infographic_benefits	Преимущества Три факта подписями на слайде	3:4	facts	—
	infographic_size	Размеры Стрелки с габаритами	3:4	dims	—
	infographic_inbox	Комплектация Что в коробке, с подписями	3:4	items	—
Предметная съёмка
→	studio_dark	Чёрная студия Контровой свет, отражение	3:4	—	—
→	studio_marble	Мрамор Капли воды, холодный свет	3:4	—	—
→	studio_hand	В руке Масштаб и живой контекст	3:4	—	—
→	studio_sand	Песок Закат, длинная тень	3:4	—	—
→	studio_forest	Лес Туман, мягкий свет	3:4	—	—
→	studio_splash	Всплеск Замороженное движение воды	3:4	—	—
→	studio_macro	Макро Фактура и материал крупно	3:4	—	—
	lifestyle_in_use	В применении Товар в живой обстановке	3:4	—	—
Белый фон
→	white_main	Главное фото на белом Чистый белый фон, без ореолов	3:4	—	—
	white_angle	Ракурс три четверти Объём и боковая сторона	3:4	—	—
Ресейл и ломбарды
→	resale_clean_asis	Витринный кадр Современно и легко, вещь как есть	4:3	—	—
→	resale_white	Белый фон для сайта Чистый белый, без ореолов	1:1	—	—
→	resale_hallmark	Клеймо и проба крупно Макро: проба, клеймо, бирка, номер	4:3	—	—
→	resale_angle	Другой ракурс Три четверти в том же лёгком стиле, для серии	4:3	—	—
→	resale_scale	Масштаб На руке, на манекене или рядом с монетой	4:3	—	hand, mannequin, coin
→	resale_condition_card	Карточка состояния Проба, вес, состояние, комплектность подписями	4:3	facts	—
→	resale_promo_banner	Баннер акции Для соцсетей и витрины, подпись по желанию	4:3	headline, disclaimer (необяз.)	—

Поля inputs с пометкой «необяз.» можно не передавать.

Файлы для машин

• openapi.yaml — OpenAPI 3.1: методы, схемы, коды ошибок, вебхук.
• scenes.json — сцены каталога в той же форме, что GET /scenes.
• pricing.json — цены, пополнение, бонусы, тестовый ключ и лимиты.

Вопросы по подключению — support@banan.wtf. Интеграторам, которые подключают своих клиентов, платит партнёрская программа.

API для интеграции · Цены API · Фид Авито · Готовые сцены · Оферта · Конфиденциальность