Как использовать Nano Banana 2 Lite API: curl, Python и один рабочий запрос

Nano-Banana-2-Lite — это экономичный вариант в семействе моделей изображений Nano-Banana на hiapi: тот же workflow на основе задач, что и у более крупных собратьев, более низкая цена за изображение и поддержка как генерации по тексту, так и редактирования по референсным изображениям. Это руководство проведёт вас через полный, работающий цикл интеграции — создание задачи, опрос задачи, скачивание результата — с демонстрацией на curl и Python, а также объяснит особенности schema, которыми он отличается от Nano-Banana-2 и Nano-Banana-Pro.

Что вы будете создавать и что нужно подготовить

Цель: отправить prompt в Nano-Banana-2-Lite, дождаться генерации изображения и сохранить его на диск.

Вам понадобится только одно: API-ключ hiapi (sk-...). Получите его в вашем hiapi dashboard. Стоимость за одно изображение указана на pricing page и на странице модели Nano Banana 2 Lite.

Все модели изображений на hiapi работают через единый async task API: вы создаёте задачу через POST /v1/tasks, а затем либо опрашиваете GET /v1/tasks/{id}, либо получаете webhook по завершении задачи.

Минимальный рабочий запрос (curl)

Создание задачи:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Nano-Banana-2-Lite",
    "input": {
      "prompt": "A watercolor illustration of a lighthouse at dawn, soft pastel palette",
      "aspect_ratio": "3:2"
    }
  }'

В ответе идентификатор задачи находится в data.taskId. Опрашивайте его:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Когда data.status равен "success", URL изображения находится в data.output[0].url. Скачивайте сразу — выходные URL содержат подпись и имеют срок действия (expireAt), поэтому сохраняйте байты, а не ссылку.

Два правила schema, на которых легко споткнуться, взятые напрямую из валидации самого API:

• Идентификатор модели чувствителен к регистру. "model": "nano-banana-2-lite" вернёт 400 MODEL_UNAVAILABLE ("model not available via /v1/tasks"). Используйте точный id Nano-Banana-2-Lite.
• prompt и aspect_ratio обязательны. Пропуск любого из них приведёт к 400 INVALID_REQUEST с сообщением missing required field. Допустимые значения aspect_ratio: auto, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, 8:1.

Тот же процесс на Python

SDK не нужен — task API это чистый JSON поверх HTTPS:

import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

# 1. Create the task
resp = requests.post(
    f"{API_BASE}/tasks",
    headers=HEADERS,
    json={
        "model": "Nano-Banana-2-Lite",
        "input": {
            "prompt": "A watercolor illustration of a lighthouse at dawn, soft pastel palette",
            "aspect_ratio": "3:2",
        },
    },
    timeout=60,
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until the task reaches a terminal state
deadline = time.time() + 600
while time.time() < deadline:
    task = requests.get(
        f"{API_BASE}/tasks/{task_id}", headers=HEADERS, timeout=30
    ).json()["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
    time.sleep(3)
else:
    raise TimeoutError(f"task {task_id} did not finish in 10 minutes")

# 3. Download immediately — output URLs are signed and expire
image_url = task["output"][0]["url"]
with open("lighthouse.png", "wb") as f:
    f.write(requests.get(image_url, timeout=120).content)
print("saved lighthouse.png")

Редактирование по референсному изображению: image_urls, а не image_input

Nano-Banana-2-Lite поддерживает редактирование изображений, но его поле референсных изображений — это image_urls — массив до 10 публично доступных URL:

{
  "model": "Nano-Banana-2-Lite",
  "input": {
    "prompt": "Replace the background with a clean white studio backdrop, keep the product unchanged",
    "aspect_ratio": "auto",
    "image_urls": ["https://your-cdn.com/product-photo.jpg"]
  }
}

Это самая частая ловушка в семействе: Nano-Banana-2 и Nano-Banana-Pro используют image_input для той же цели, а Lite отклоняет это поле (additional properties 'image_input' not allowed). Имена полей вроде input_urls, images или reference_images отклоняются на всех трёх моделях. Если вы переносите код между уровнями, обычно единственное необходимое изменение — это переименование одного поля.

Lite vs. Nano-Banana-2 vs. Pro: важные различия schema

	Nano-Banana-2-Lite	Nano-Banana-2	Nano-Banana-Pro
Обязательные входные данные	prompt, aspect_ratio	prompt	prompt
Референсные изображения	image_urls (≤10)	image_input	image_input
Управление resolution	Не принимается	Принимается	Принимается

Lite сохраняет интерфейс предельно простым: prompt, соотношение сторон, опциональные референсные изображения. Нет resolution, seed, n или negative_prompt — отправка любого из них приведёт к ошибке валидации additional properties ... not allowed. Если вам нужен явный контроль разрешения (1K/2K/4K) или более высокий уровень точности, переходите на Nano-Banana-2 или Nano-Banana-Pro; если вы генерируете массово — миниатюры, черновики, итерационные циклы, пакетные варианты — более низкая стоимость за изображение у Lite и есть его смысл.

Укрепление для production

По возможности используйте webhook вместо опроса. Добавьте блок callback при создании задачи, и hiapi отправит финальный результат POST-запросом на ваш endpoint:

{
  "model": "Nano-Banana-2-Lite",
  "input": { "prompt": "...", "aspect_ratio": "1:1" },
  "callback": { "url": "https://your-app.com/webhooks/hiapi", "when": "final" }
}

when принимает только "final" — вы получите ровно один callback, независимо от успеха или неудачи. Опрос подходит для скриптов и notebook; callbacks лучше подходят для серверов, так как избавляют вас от необходимости управлять циклами опроса и таймаутами. Если вы всё же опрашиваете, интервала 2–5 секунд с жёстким дедлайном (как в примере на Python) достаточно.

Обрабатывайте ошибки двух уровней. Сбои на уровне запроса возвращаются как HTTP-ошибки — невалидный или неавторизованный ключ вернёт 401 с {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}, ошибки schema вернут 400 INVALID_REQUEST с точным сообщением валидации. Сбои на уровне задачи приходят как status: "fail" с объектом error в самой задаче; обрабатывайте оба пути в вашем коде.

Сделайте повторные попытки идемпотентными. Создание задачи не идемпотентно — повторная попытка создания после таймаута может породить две задачи (и двойное списание). Сохраняйте taskId сразу после получения и после перезапуска продолжайте опрашивать существующий id, а не создавайте задачу заново вслепую.

Храните байты, а не URL. Выходные URL истекают. Прежде чем делать с изображением что-либо ещё, скачайте его и поместите в собственное хранилище.

Связанные материалы

• Страница модели Nano Banana 2 Lite — параметры, актуальные цены, playground
• GPT Image 2 vs Nano Banana 2: сравнение бок о бок с одинаковым prompt
• Сохранение консистентности персонажа с Nano-Banana на hiapi
• Документация hiapi и Цены

FAQ

Почему я получаю "model not available via /v1/tasks"? Идентификатор модели чувствителен к регистру. Используйте точно Nano-Banana-2-Lite; вариант в нижнем регистре будет отклонён с 400 MODEL_UNAVAILABLE.

Поддерживает ли Nano-Banana-2-Lite редактирование из изображения в изображение? Да. Передавайте референсные изображения в массив image_urls (до 10 URL). Он справляется с заменой фона, переносом стиля и рабочими процессами редактирования по инструкциям, управляемым prompt.

Почему мой код для Nano-Banana-2 падает на Lite с ошибкой "additional properties 'image_input' not allowed"? Разные уровни используют разные имена полей референсных изображений: Lite ожидает image_urls, а Nano-Banana-2 и Pro ожидают image_input. При переключении уровней переименуйте поле.

Можно ли задать resolution, seed или количество изображений? На Lite — нет; его input schema принимает только prompt, aspect_ratio и image_urls. Для управления resolution в 1K/2K/4K используйте Nano-Banana-2 или Nano-Banana-Pro.

Как долго действительны URL выходных изображений? Это подписанные URL со временем истечения (в объекте output — expireAt). Немедленно скачивайте байты и сохраняйте в собственное хранилище; никогда не делайте hotlink на результаты задач.

Что означает 401 permission_denied? Ваш API-ключ недействителен или не даёт права на эту модель. Проверьте ключ в вашем dashboard и убедитесь, что отправляете его в форме Authorization: Bearer sk-....

Сколько стоит одно изображение Nano-Banana-2-Lite? Оплата по факту использования, за изображение, позиционируется как самый дешёвый уровень в семействе Nano-Banana. Актуальные тарифы смотрите на pricing page.