KovAPIKovAPI
POST https://kovapi.com/v1/images/generations

Генерация изображений (асинхронно, через задачи) на базе Google Nano Banana 2 Lite (Gemini 3.1 Flash Lite Image) — самой быстрой и недорогой модели семейства Nano Banana. Для генерации по тексту нужен только prompt; для редактирования передайте референсы в image или images (URL, data: URI или base64) либо вызовите /v1/images/edits. После отправки сразу возвращается id задачи (HTTP 202); опрашивайте GET /v1/images/jobs/{id}, чтобы получить изображение. Только 1K, 14 пропорций: 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 21:9, 4:1, 1:4, 8:1 и 1:8. Запрос в 2K или 4K отклоняется при отправке и не оплачивается. Оплата за изображение; неудачные запросы не оплачиваются.

Попробовать в песочнице →

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

Три шага: отправить задачу, опросить её и забрать ссылку на изображение. Замените YOUR_API_KEY своим ключом, и команды ниже заработают как есть.

Шаг 1 · Отправка (сразу возвращает id задачи, HTTP 202)
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2-lite", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "16:9", "resolution": "1K"}'
Ответ (HTTP 202)
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281500,
  "model": "nano-banana-2-lite"
}
Шаг 2 · Опрашивайте каждые 2–3 секунды, пока status не станет succeeded или failed
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
Ответ при успехе
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281500,
  "model": "nano-banana-2-lite",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.jpg"}
  ],
  "usage": {"images": 1, "resolution": "1K", "model": "nano-banana-2-lite"}
}

Шаг 3 · data[0].url — это изображение (оригинал upstream в формате JPEG). Оно хранится 7 дней; чтобы пользоваться им дольше, скачайте его в своё хранилище.

Полный пример (Python: отправить, дождаться, сохранить на диск)
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. отправка
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "nano-banana-2-lite",
    "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field",
    "size": "16:9",
    "resolution": "1K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. опрос каждые 3 секунды до завершения
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. скачивание изображения
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("nano-banana-2-lite.jpg", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["message"])

Аутентификация

Header
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Чтобы начать, создайте API-ключ в консоли.

Тело запроса

ПараметрТипОбязательныйОписание
model string Да Идентификатор модели, здесь nano-banana-2-lite.
prompt string Да Текстовый промпт с описанием изображения.
size string Нет Соотношение сторон результата. Рекомендуется передавать соотношение — 1:1, 3:4, 2:3, 9:16, 4:3, 3:2, 16:9 — тогда модель рендерит нативно именно в этом соотношении, без обрезки объекта. Также принимаются размеры в пикселях (например, 1024x1024, 1024x1536, 1536x1024). По умолчанию 1:1 (квадрат).
resolution string Нет Разрешение: только 1K (по умолчанию, можно не указывать). resolution 2K / 4K возвращает 400 unsupported_resolution при отправке и не оплачивается. Если в size указан размер в пикселях, 14 собственных размеров 1K у Lite (например, 2928x352 или 1584x672) считаются 1K.
thinking_level string Нет Уровень размышления, только для nano-banana-2-lite: minimal (по умолчанию, можно не передавать) или high. high сначала думает, потом рисует: на 3–6 секунд дольше, цена та же. Стоит попробовать для сложной композиции, точного количества и размещения текста; в наших тестах разница на картинках была незаметна. Для других моделей high отклоняется при отправке с кодом 400, без оплаты.
n integer Нет Всегда 1: каждая задача возвращает одно изображение. Большее значение всё равно даст одно изображение и оплату за одно; для нескольких изображений отправьте несколько задач одновременно.
image string Нет Изображение в изображение: референсное изображение в виде публичного URL, data: URI или необработанного base64. Если это поле передано, запрос выполняет полноценное изображение-в-изображение с сохранением идентичности объекта в выбранном соотношении и размере (размер/соотношение) — эквивалентно вызову /v1/images/edits.
images array Нет Несколько референсов, до 8 (если больше, используются первые 8): массив строк или объектов {"image_url": "..."}; каждый — публичная ссылка на изображение, data: URI или base64, до 16 МБ. С ними задача идёт как «изображение из изображения», так же как /v1/images/edits. Для одного референса подойдёт и поле image выше.

Пример запроса

cURL
# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://kovapi.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "nano-banana-2-lite", "prompt": "a serene ink-wash poster, lots of negative space", "size": "16:9", "resolution": "1K"}'
# 2) poll until status=succeeded
curl https://kovapi.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'

Ответ

200 · JSON
{
  "id": "img_3f9a...c2",
  "object": "image.generation.job",
  "status": "queued",
  "model": "nano-banana-2-lite"
}

Цена

Оплата за изображение; цена зависит только от уровня разрешения, а пропорция и режим (из текста или из изображения) не влияют. При отправке резервируется цена уровня, а если задача не удалась, сумма полностью возвращается. 1 кредит = $0.005.

УровеньКредитов за изображениеUSD за изображение
1K2$0.01

Каждая задача возвращает ровно одно изображение: какой бы n вы ни передали, вы получите одно изображение и заплатите за одно. Нужно несколько — отправьте несколько задач одновременно (один аккаунт генерирует до 50 изображений параллельно).

Пропорции, разрешение и размер изображения

Пропорцию задаёт size; resolution можно не указывать (единственный уровень — 1K). Модель рисует сразу в выбранной пропорции, и вы получаете оригинальное изображение без обрезки и масштабирования; у каждой пропорции один фиксированный размер, см. таблицу:

Пропорция1K
1:11024x1024
16:91376x768
9:16768x1376
4:31200x896
3:4896x1200
3:21264x848
2:3848x1264
4:5928x1152
5:41152x928
21:91584x672
1:4512x2064
4:12064x512
1:8352x2928
8:12928x352

Поддерживаются только пропорции из таблицы (размер в пикселях в size считается ближайшей из них, с допуском 1,5 %). Любая другая пропорция сразу завершается ошибкой и не оплачивается; ничего не рисуется с последующей обрезкой.

В size можно указать и размер в пикселях: размеры из таблицы (например, 2928x352 или 1584x672) рисуются в 1K, любой другой размер — в собственном размере 1K ближайшей пропорции (расхождение до 1,5 %); если длинная сторона больше 1536, это считается 2K / 4K и отклоняется при отправке. resolution может быть только 1K: 2K / 4K возвращает 400 unsupported_resolution при отправке, задача не создаётся и оплата не списывается. Без size получится квадрат 1:1.

Изображение из изображения и референсы

  • Передайте image (одно изображение) или images (несколько, до 8; если больше, используются первые 8), и задача станет «изображение из изображения»; в промпте напишите, что изменить. POST /v1/images/edits принимает те же параметры.
  • Каждый референс — это публичная ссылка на изображение (http или https), data: URI или просто base64, до 16 МБ каждый, в распространённом формате: JPEG, PNG, WebP и т. п.
  • Ссылка должна отдавать само изображение, а не веб-страницу и не адрес за логином или с защитой от хотлинка. Референс, который не удаётся прочитать, отклоняется при отправке с кодом 400 и причиной; задача не создаётся, деньги не списываются.
  • Пропорцию результата задаёт size, а не референс. Чтобы сохранить исходную пропорцию, укажите её в size.
  • Референсы мы храним у себя 7 дней.
curl · Изображение из изображения по двум референсам
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2-lite", "prompt": "Keep the people, change the background to a beach at night with warm string lights", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "1K"}'

Статус задачи и поля ответа

GET /v1/images/jobs/{id} всегда возвращает id, object (image.generation.job), status, created (секунды Unix) и model; остальные поля зависят от статуса:

statusЗначениеДополнительные поля
queuedВ очередиqueue_position (сколько задач впереди), eta_seconds (ориентировочное ожидание в секундах)
processingГенерируется—
succeededГотовоdata[].url (ссылка на изображение; наш хостинг хранит его 7 дней); usage.images (сколько изображений выдано), usage.resolution (уровень оплаты)
failedОшибка; сумма, зарезервированная при отправке, полностью возвращенаerror.message, error.type, error.code

Опрашивайте каждые 2–3 секунды. Один аккаунт генерирует до 50 изображений одновременно; остальные задачи ждут в порядке отправки, а задача, не начавшаяся за 15 минут, завершается ошибкой с полным возвратом. Записи о задачах хранятся 3 дня, после этого по id вернётся 404, но ссылка на изображение действует все 7 дней. Задачу может читать только аккаунт, который её отправил.

Сколько ждать

Обычное время от отправки до результата, ориентировочно. «Изображение из изображения» занимает на несколько секунд больше; задача, которую шлюз автоматически перезапустил, может занять 1–2 минуты.

УровеньОбычное время
1K5–15 с

Ошибки и возвраты

Все ошибки имеют одну форму, {"error": {"message", "type", "code", "param"}}; ориентируйтесь на code.

Ошибки при отправке (задача не создаётся, деньги не списываются)

HTTPcodeПричинаЧто делать
400missing_promptprompt пустойДобавьте prompt
400model_not_foundНеверный id модели или модель сейчас недоступнаПроверьте id; список моделей — /v1/models
400invalid_requestНе удаётся прочитать референс (битая ссылка, не изображение, больше 16 МБ…); в message указано, какой и почемуДайте прямую ссылку на изображение или передайте base64
401invalid_api_keyКлюч неверный, удалён или отключёнПроверьте ключ в консоли
402insufficient_quotaНе хватает баланса, чтобы зарезервировать задачуПополните баланс и повторите
429rate_limit_exceededПревышен поминутный лимит, заданный для этого ключаСнизьте частоту или поднимите лимит ключа в консоли
503model_maintenanceМодель на обслуживанииПовторите позже; подробности на странице статуса
503service_unavailableВременная ошибка на нашей стороне (например, не удалось сохранить референс)Повторите чуть позже

Неудачные задачи (задача принята, но завершилась со status failed; резерв возвращается полностью)

СитуацияЧто вы увидитеЧто делать
Промпт или референс не прошёл проверку безопасности Googleerror.message вроде Content blockedПерепишите промпт или замените референс; повторная отправка без изменений обычно снова отклоняется
Временный сбой или таймаут на стороне поставщика (сначала мы автоматически повторяем запрос и возвращаем ошибку, только если повторы тоже не сработали)error.code вроде upstream_error или upstream_timeout, причина — в messageОтправьте снова
Задача 15 минут ждала и не началасьЭто сказано в error.messageОтправьте позже

Webhook вместо опроса

В продакшене добавляйте callback_url при отправке. Когда задача завершится, успешно или нет, мы отправим POST на этот адрес с тем же JSON, что возвращает запрос статуса, как событие image.completed или image.failed, с заголовками подписи для проверки отправителя. Можно также задать один адрес для всего аккаунта в «Настройки → Webhook». Документация по webhook

curl · callback_url
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2-lite", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'