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

Что такое Nano-Banana-2-Lite и когда его использовать

Nano-Banana-2-Lite — это сверхбюджетный тариф в семействе Nano-Banana на HiAPI. Он рассчитан на сценарии генерации изображений с высокой нагрузкой и высокой чувствительностью к стоимости, где важнее предсказуемые затраты и быстрые итерации, а не максимальная точность. Если вы прототипируете функцию, массово генерируете миниатюры или вариации, либо запускаете фоновые задачи, допускающие более лёгкую модель, этот тариф — подходящая отправная точка.

Используйте его, когда результат — лишь один из этапов более крупного конвейера: черновые визуалы, плейсхолдеры, массовые эксперименты или A/B-тесты, где нужно много кандидатов при низкой стоимости. Для финальных ключевых визуалов или сценариев, требующих максимальной детализации, переходите на более крупный тариф. Интерфейс API при этом не меняется, поэтому для смены модели не нужно переписывать интеграцию.

Предварительные требования и структура запроса

Перед вызовом Nano-Banana-2-Lite убедитесь, что у вас есть:

• Аккаунт HiAPI и API-ключ. Храните его в переменной окружения, например HIAPI_API_KEY; никогда не коммитьте его в систему контроля версий.
• Терминал с curl для первого теста, а также Python 3.8+ и библиотека requests для версии со скриптом.
• Промпт, описывающий желаемое изображение. Начните с простого; позже можно добавить референсные входы.

Каждый запрос к HiAPI следует одной и той же структуре: POST с JSON-телом на эндпоинт модели. Тело запроса содержит имя модели, промпт и любые необязательные параметры. Поскольку генерация асинхронна, вызов на отправку возвращает идентификатор задачи, после чего вы опрашиваете эту задачу. Ответ — JSON, а ошибки содержат код состояния и сообщение, которое можно залогировать.

В вашей полезной нагрузке как минимум нужно задать model равным nano-banana-2-lite и указать prompt. Необязательные поля, такие как reference_images и настройки вывода, рассматриваются в следующих разделах.

Рабочий запрос curl

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

curl -X POST https://api.hiapi.ai/v1/images/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1"
  }'

Ответ содержит id задачи и поле status. Только что отправленные задачи обычно возвращают queued или processing. Сохраните этот id; он понадобится на шаге опроса. Если вы получили 401, проверьте, что HIAPI_API_KEY экспортирован в вашей оболочке. Если вы получили 422, ознакомьтесь с сообщением об ошибке, чтобы найти проблемное поле.

Отправка того же запроса на Python

Перенесите вызов curl в Python, чтобы встроить его в скрипт или сервис. В этом примере используется requests, а ключ читается из переменной окружения.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "nano-banana-2-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1",
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
print(job["id"], job["status"])

Храните тело запроса в словаре, чтобы расширять его необязательными полями без переписывания вызова. Для шага отправки таймаут в 30 секунд разумен, поскольку тяжёлая работа выполняется асинхронно.

Добавление необязательных референсных входов

Референсные входы позволяют направлять генерацию с помощью визуального контекста. На HiAPI вы прикрепляете их как массив reference_images в том же JSON-теле. Каждый элемент — это публично доступный URL или data URI в base64. Используйте референсные изображения, когда хотите сохранить композицию, повторить стиль или обеспечить согласованность продуктовых изображений между несколькими вариациями.

{
  "model": "nano-banana-2-lite",
  "prompt": "Same layout, but in a warm sunset palette",
  "reference_images": [
    "https://example.com/reference/layout.png"
  ]
}

Включайте референсы только тогда, когда они дают полезный сигнал. Каждый референс — это дополнительные данные для передачи, которые могут размыть простой промпт. Для прямых задач текст-в-изображение полностью опускайте это поле. Если вы всё же используете референсы, держите их релевантными и немногочисленными; одно-два тщательно подобранных изображения обычно лучше большой подборки.

Опрос асинхронных результатов

Генерация изображений асинхронна: вы отправляете задачу, а затем опрашиваете эндпоинт задачи, пока её состояние не станет терминальным. Шаблон одинаков для curl и Python.

При использовании curl проверяйте задачу по её id:

curl https://api.hiapi.ai/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

В Python оберните опрос в цикл с задержкой, чтобы не запрашивать API слишком часто:

import time

def wait_for_job(job_id, interval=2, max_attempts=30):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {API_KEY}"}
    for _ in range(max_attempts):
        r = requests.get(url, headers=headers, timeout=30)
        r.raise_for_status()
        data = r.json()
        if data["status"] in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError("Job did not finish in time")

Начните с короткого интервала и постепенно увеличивайте его, если опрашиваете много задач. Всегда задавайте максимальное число попыток, чтобы зависшая задача не блокировала ваш рабочий процесс навсегда. Считайте failed терминальным состоянием и логируйте сообщение об ошибке.

Загрузка и проверка результата

При успешном выполнении задачи ответ содержит один или несколько URL вывода. Загрузите файл и сохраните его локально, затем проверьте полученное содержимое.

result = wait_for_job(job["id"])
if result["status"] == "succeeded":
    image_url = result["output"]["url"]
    img = requests.get(image_url, timeout=60)
    img.raise_for_status()
    with open("output.png", "wb") as f:
        f.write(img.content)

Выполните базовую проверку загруженного содержимого: убедитесь, что тип содержимого — изображение, что размер файла ненулевой и разумный, и откройте его один раз, чтобы подтвердить соответствие промпту. Записывайте id задачи вместе с именем локального файла, чтобы можно было проследить любой материал до его запроса.

Чек-лист по стоимости и сбоям перед запуском в продакшен

Nano-Banana-2-Lite имеет сверхбюджетную ценовую категорию; тарификация следует стандартному учёту генерации изображений на платформе. Смотрите актуальную панель цен на сайте для точных тарифов, а не полагайтесь на жёстко заданные предположения.

Перед запуском в продакшен выработайте следующие привычки:

• Повторы с экспоненциальной задержкой. Повторяйте временные ошибки (таймауты, 5xx) несколько раз с увеличением задержки; не повторяйте ошибки валидации 4xx.
• Ограничьте опрос. Используйте фиксированный интервал и максимальное число попыток. Логируйте конечное состояние и затраченное время.
• Записывайте id задачи и промпт. Храните id задачи, промпт, модель и любые референсные входы вместе с каждым выводом, чтобы можно было воспроизвести или проверить запуск.
• Проверяйте входы как можно раньше. Перед отправкой проверяйте длину промпта и референсные URL, чтобы не тратить задачи впустую.

С этими проверками Nano-Banana-2-Lite становится предсказуемой недорогой рабочей лошадкой для массовой и фоновой генерации. Просмотрите страницу модели на HiAPI, чтобы узнать актуальные параметры и тарифы.