API

REST поверх HTTPS, JSON в запросах и ответах, даты в ISO 8601 (UTC). Базовый адрес: {{origin}}/v1. Ключ создаётся в кабинете, для работы нужна активная подписка.

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

curl {{origin}}/v1/images \
  -H "Authorization: Bearer sk-genaro-…" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "рыжий кот в шлеме космонавта, студийный свет", "model": "genaro-fast", "wait": true}'

Ответ (задание завершено, wait: true):

{
  "data": [{
    "id": "img_3f9c1a2b7d4e5f6a8b90",
    "object": "image.job",
    "status": "succeeded",
    "model": "genaro-fast",
    "prompt": "рыжий кот в шлеме космонавта, студийный свет",
    "aspect_ratio": "1:1",
    "upscale": false,
    "credits": 1,
    "created": "2026-11-06T12:00:00Z",
    "finished": "2026-11-06T12:00:48Z",
    "source": "api",
    "expired": false,
    "error": null,
    "images": [{"url": "{{origin}}/i/3f9c1a2b7d4e5f6a8b90.jpg", "thumbnail_url": "{{origin}}/i/3f9c1a2b7d4e5f6a8b90.t.webp", "width": 1024, "height": 1024}]
  }]
}

Обычно генерация занимает около 30 секунд, в 9 случаях из 10 укладывается в 70 секунд, изредка идёт дольше. В рабочих интеграциях используйте вебхук или опрос, а не долгое ожидание соединения.

Авторизация

Передавайте ключ в заголовке Authorization: Bearer sk-genaro-… или X-API-Key: sk-genaro-…. Ключ привязан к аккаунту и тратит его кредиты. Ключ показывается один раз при создании, на аккаунт можно держать до 10 ключей. Держите ключ на сервере: в браузере и мобильных приложениях он виден всем. Скомпрометированный ключ отзывается в кабинете. Без ключа работают только GET /v1/models и ссылки на готовые файлы.

Модели и кредиты

В запросах указывается id, в таблице рядом показана реальная модель, которая выполняет генерацию. Стоимость задания в кредитах списывается из часового лимита тарифа.

Форматы: 1:1, 16:9, 9:16, 4:3, 3:4. Длинная сторона результата обычно 1–1,4K, точный размер приходит в полях width и height. Апскейл ×2 доступен моделям с supports_upscale.

GET /v1/models

{
  "data": [{
    "id": "genaro-pro",
    "label": "Genaro Pro",
    "underlying_model": "Nano Banana Pro (Google)",
    "description": "Лучшее качество: надписи на картинке, портреты, работа по референсу.",
    "credits": 4,
    "credits_upscale": 8,
    "supports_upscale": true,
    "aspects": ["1:1", "16:9", "9:16", "4:3", "3:4"]
  }]
}

Тарифы и лимиты

• Кредиты в час. Лимит действует на окно с :00 до :59 и обновляется в начале часа, остаток не переносится. Задание резервирует свою цену при создании. Если не хватает, ответ 429 quota_exceeded с заголовком Retry-After и полями credits_left, credits_needed, resets_at (Unix-время). Неудавшиеся и отменённые задания лимит не тратят.
• Параллельность. Сверх лимита одновременных заданий запросы ждут в очереди, очередь между клиентами делится честно: первым идёт тот, кто в этом часу получил меньше.
• Запросы. До 120 запросов в минуту с одного IP-адреса и до 600 в минуту на ключ. Опрос статуса раз в 2–3 секунды в эти лимиты укладывается.
• Запрос на генерацию. Описание до 4000 символов, до 4 референсов по 6 МБ, до 4 картинок за запрос, всё тело запроса до 40 МБ.
• Хранение. Готовые файлы хранятся 14 дней, референсы удаляются сразу после задания.

Создать изображение

POST /v1/images → 202 Accepted, или 200 при wait: true, если все задания успели завершиться. В ответе массив data с объектами заданий.

Python, референс и ожидание результата:

import base64, requests

ref = base64.b64encode(open("face.jpg", "rb").read()).decode()
r = requests.post("{{origin}}/v1/images",
    headers={"Authorization": "Bearer sk-genaro-…"},
    json={"prompt": "этот же человек в деловом костюме, офис", "model": "genaro-pro",
          "aspect_ratio": "3:4", "reference_images": [ref], "wait": True},
    timeout=320)
job = r.json()["data"][0]
print(job["status"], job["images"][0]["url"] if job["images"] else job["error"])

JavaScript, задание с вебхуком:

const r = await fetch("{{origin}}/v1/images", {
  method: "POST",
  headers: { Authorization: "Bearer sk-genaro-…", "Content-Type": "application/json" },
  body: JSON.stringify({
    prompt: "уютная кофейня, тёплый свет",
    model: "genaro-plus",
    aspect_ratio: "16:9",
    webhook_url: "https://example.com/hook?token=секрет",
  }),
});
const { data } = await r.json();
console.log(data[0].id, data[0].status);

Объект задания

Получить результат

Без wait опрашивайте GET /v1/images/{id} раз в 2–3 секунды или используйте вебхук.

while True:
    j = requests.get(f"{{origin}}/v1/images/{job_id}", headers=H).json()
    if j["status"] in ("succeeded", "failed", "canceled"):
        break
    time.sleep(2)

Ссылки на изображения не требуют ключа: не публикуйте их, если картинка приватная. Статус failed означает, что кредиты вернулись в лимит часа, причина лежит в error. Запрос можно отправить снова.

Список заданий

GET /v1/images?limit=20&before=ID отдаёт ваши задания, новые первыми. limit 1–100, по умолчанию 20. Для следующей страницы передайте в before id последнего элемента.

{"data": [ /* объекты заданий */ ], "has_more": true}

Отмена и удаление

Остаток кредитов

GET /v1/usage

{
  "source": "subscription",
  "credits_per_hour": 250,
  "credits_used": 12,
  "credits_left": 238,
  "window_resets_at": "2026-11-06T13:00:00Z",
  "subscription_ends": "2026-12-06T12:00:00Z",
  "plan": "Про"
}

Без активной подписки source равен none, а новые задания получают 402 subscription_required.

Вебхуки

Если указан webhook_url, после завершения (успех или ошибка) мы отправим POST с JSON задания: это тот же объект, что возвращает GET /v1/images/{id}. Ответ с кодом меньше 500 считается доставкой, при ошибке будет до трёх попыток: сразу, через 5 и через 30 секунд. Адрес должен быть публичным, порты только 80, 443, 8080 и 8443, локальные и внутренние сети блокируются, редиректы не выполняются, ответа мы ждём до 10 секунд.

Подписи у вебхуков нет. Чтобы убедиться, что вызов настоящий, зашейте секрет в URL (…/hook?token=…) и перепроверяйте статус через GET.

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

Передайте заголовок Idempotency-Key: <уникальная строка> в POST /v1/images. Повтор запроса с тем же ключом вернёт те же задания и ничего не спишет второй раз, так что повторять при таймаутах сети безопасно.

OpenAI-совместимость

POST /v1/images/generations повторяет формат OpenAI Images API и всегда ждёт результат, до 170 секунд. Работают OpenAI SDK и no-code платформы (n8n, Make, Flowise): укажите наш адрес как базовый и ваш ключ.

curl {{origin}}/v1/images/generations \
  -H "Authorization: Bearer sk-genaro-…" \
  -H "Content-Type: application/json" \
  -d '{"model": "genaro-pro", "prompt": "уютная кофейня, тёплый свет", "size": "1792x1024"}'

from openai import OpenAI

client = OpenAI(base_url="{{origin}}/v1", api_key="sk-genaro-…")
image = client.images.generate(model="genaro-pro", prompt="уютная кофейня, тёплый свет", size="1792x1024")
print(image.data[0].url)

Ответ: {"created": 1762430400, "data": [{"url": "…", "revised_prompt": "…"}]}. Если генерация не успела, вернётся 504 timeout с полем job_id: заберите результат через GET /v1/images/{id}.

Ошибки

Тело ошибки: {"error": {"code": "...", "type": "...", "message": "..."}}. Текст сообщения можно показывать пользователю, логику стоит строить по code.

В основном API отказ модели приходит статусом failed у задания (чтение при этом отвечает 200), а кредиты возвращаются.

Правила использования

Запрещены откровенный контент для взрослых, любые сексуальные сцены с участием несовершеннолетних, дипфейки реальных людей без согласия, мошенничество и нарушение прав третьих лиц. Подробности — в условиях использования. Не перепродавайте и не публикуйте свой ключ.