Генерация изображений (асинхронно, через задачи) на базе 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 своим ключом, и команды ниже заработают как есть.
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"}'{
"id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
"object": "image.generation.job",
"status": "queued",
"created": 1791281500,
"model": "nano-banana-2-lite"
}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 дней; чтобы пользоваться им дольше, скачайте его в своё хранилище.
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"])Аутентификация
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 выше. |
Пример запроса
# 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'Ответ
{
"id": "img_3f9a...c2",
"object": "image.generation.job",
"status": "queued",
"model": "nano-banana-2-lite"
}Цена
Оплата за изображение; цена зависит только от уровня разрешения, а пропорция и режим (из текста или из изображения) не влияют. При отправке резервируется цена уровня, а если задача не удалась, сумма полностью возвращается. 1 кредит = $0.005.
| Уровень | Кредитов за изображение | USD за изображение |
|---|---|---|
| 1K | 2 | $0.01 |
Каждая задача возвращает ровно одно изображение: какой бы n вы ни передали, вы получите одно изображение и заплатите за одно. Нужно несколько — отправьте несколько задач одновременно (один аккаунт генерирует до 50 изображений параллельно).
Пропорции, разрешение и размер изображения
Пропорцию задаёт size; resolution можно не указывать (единственный уровень — 1K). Модель рисует сразу в выбранной пропорции, и вы получаете оригинальное изображение без обрезки и масштабирования; у каждой пропорции один фиксированный размер, см. таблицу:
| Пропорция | 1K |
|---|---|
| 1:1 | 1024x1024 |
| 16:9 | 1376x768 |
| 9:16 | 768x1376 |
| 4:3 | 1200x896 |
| 3:4 | 896x1200 |
| 3:2 | 1264x848 |
| 2:3 | 848x1264 |
| 4:5 | 928x1152 |
| 5:4 | 1152x928 |
| 21:9 | 1584x672 |
| 1:4 | 512x2064 |
| 4:1 | 2064x512 |
| 1:8 | 352x2928 |
| 8:1 | 2928x352 |
Поддерживаются только пропорции из таблицы (размер в пикселях в 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 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 минуты.
| Уровень | Обычное время |
|---|---|
| 1K | 5–15 с |
Ошибки и возвраты
Все ошибки имеют одну форму, {"error": {"message", "type", "code", "param"}}; ориентируйтесь на code.
Ошибки при отправке (задача не создаётся, деньги не списываются)
| HTTP | code | Причина | Что делать |
|---|---|---|---|
| 400 | missing_prompt | prompt пустой | Добавьте prompt |
| 400 | model_not_found | Неверный id модели или модель сейчас недоступна | Проверьте id; список моделей — /v1/models |
| 400 | invalid_request | Не удаётся прочитать референс (битая ссылка, не изображение, больше 16 МБ…); в message указано, какой и почему | Дайте прямую ссылку на изображение или передайте base64 |
| 401 | invalid_api_key | Ключ неверный, удалён или отключён | Проверьте ключ в консоли |
| 402 | insufficient_quota | Не хватает баланса, чтобы зарезервировать задачу | Пополните баланс и повторите |
| 429 | rate_limit_exceeded | Превышен поминутный лимит, заданный для этого ключа | Снизьте частоту или поднимите лимит ключа в консоли |
| 503 | model_maintenance | Модель на обслуживании | Повторите позже; подробности на странице статуса |
| 503 | service_unavailable | Временная ошибка на нашей стороне (например, не удалось сохранить референс) | Повторите чуть позже |
Неудачные задачи (задача принята, но завершилась со status failed; резерв возвращается полностью)
| Ситуация | Что вы увидите | Что делать |
|---|---|---|
| Промпт или референс не прошёл проверку безопасности Google | error.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 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"}'