Руководство по API Nano Banana: вызов nano-banana, nano-banana-2 и nano-banana-pro на HiAPI

Что предлагает семейство моделей Nano Banana

Генерация изображений редко ограничивается одним режимом. На ранних этапах проекта нужны быстрые наброски для исследования идей; позже требуются тщательно проработанные рендеры для сдачи работы. Семейство Nano Banana на HiAPI построено именно вокруг этого: один интерфейс, три варианта, каждый настроен на свою позицию в кривой качества и скорости.

Имена выбраны намеренно. nano-banana — базовый вариант, используйте его, когда при формировании промпта или компоновки по-прежнему нужна быстрая визуальная обратная связь. nano-banana-2 делает шаг вперёд по точности и следованию промпту и обычно является выбором, когда результат близок к финальному, но вы ещё хотите итерации. nano-banana-pro — вариант с наивысшей точностью в семействе, подходящий для финальных рендеров, где детали и композиция важнее всего.

То, что у них общего, так же важно, как и то, чем они различаются. Все три вызываются через одну и ту же конечную точку HiAPI. Вы аутентифицируетесь один раз, формируете запрос один раз, а при переключении меняете только идентификатор модели. Это означает, что приложение может отправлять запросы на базовой модели, а затем повторно прогонять тот же промпт на более сильном варианте без изменения кода транспортного уровня.

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

Почему семейство, а не одна модель

Разные шаги рабочего процесса предъявляют разные требования. Исследование промптов, черновики компоновки и клиентские превью ценят скорость; ключевые визуалы и маркетинговые материалы ценят точность. Рассмотрение выбора модели как решения времени выполнения позволяет сопоставить каждый шаг с подходящим вариантом без перестройки конвейера.

Выбор между nano-banana, nano-banana-2 и nano-banana-pro

Выбирайте вариант, задав два вопроса: насколько этот результат близок к финальной версии и сколько попыток потребуется для его достижения? Всё остальное следует из этого.

nano-banana: для пакетной обработки и исследования

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

nano-banana-2: для итераций, близких к финалу

Переключайтесь на nano-banana-2, когда композиция стабильна и вы дорабатываете детали — отступы, точность субъекта, насколько точно вывод следует промпту. Это прагматичный промежуточный выбор: следование заметно сильнее, но без прохождения пути максимальной точности для каждого превью.

nano-banana-pro: для финального рендера

Оставляйте nano-banana-pro для выходных данных, которые нужно сдать. Ключевые визуалы, изображения продуктов и всё, что клиент будет внимательно рассматривать, заслуживает более сильного варианта. Не делайте его вариантом по умолчанию — оставьте его для последнего шага, чтобы исследовательские итерации оставались недорогими.

Практическое правило маршрутизации

Простая стратегия повышения подходит большинству команд:

• Все новые промпты по умолчанию используют nano-banana.
• Когда структура верна, но качества недостаточно, повышайте промпт до nano-banana-2.
• После фиксации промпта запустите финальную версию один раз на nano-banana-pro.

Это делает итерации быстрыми и предсказуемыми, а модели использования — легко понятными. Оплата зависит от использования и различается по вариантам, поэтому проверяйте актуальные тарифы и ограничения в живой документации моделей, а не зашивайте какие-либо числа в код.

Шаблоны промптов, общие для всех вариантов

Самое дорогое, что вы можете сделать, — написать промпт, который работает только на одной модели. Стройте их так, чтобы переключение требовало изменения одной строки.

Промпт из четырёх блоков

Пишите каждый промпт как четыре помеченных раздела в таком порядке:

1. Субъект — что изображено, изложенное просто.
2. Стиль — визуальная трактовка: фотография, иллюстрация, акварель, 3D-рендер.
3. Композиция — кадрирование, ракурс камеры, расположение, негативное пространство.
4. Ограничения — чего избегать и любые жёсткие требования.

Пример заполнения:

Subject: a ceramic coffee mug on a wooden desk, steam rising
Style: soft natural light, shallow depth of field, editorial photography
Composition: centered, 50mm equivalent, generous negative space at top
Constraints: no text, no logos, neutral background

Поскольку блоки независимы, вы можете усилить стиль или ослабить композицию, не переписывая весь промпт — и та же структура легко понимается каждым вариантом семейства.

Делайте промпты независимыми от модели

Избегайте формулировок, предполагающих особенности конкретной модели. Описывайте желаемый результат, а не шаги, которые должна предпринять конкретная модель. Когда нужно сравнить варианты, меняйте только идентификатор модели и сохраняйте промпт побайтово идентичным, чтобы сравнение было осмысленным.

Управляйте версиями промптов как кодом

Храните промпты как строки в файлах конфигурации или небольшой библиотеке промптов с индексацией по имени и версии. Когда вариант выдаёт лучший результат после небольшой правки, фиксируйте это изменение. Именно это позволяет перенести промпт с nano-banana на nano-banana-pro при сдаче без сюрпризов.

Негативные ограничения важны

Если промпт постоянно порождает текст, логотипы или нежелательные объекты, явно добавляйте их в блок ограничений. Чёткие негативные ограничения часто надёжнее изощрённых формулировок при работе с разными вариантами.

Создание рабочих запросов на HiAPI

Каждый вариант вызывается через одну и ту же конечную точку HiAPI. Запрос имеет четыре переменные части: базовый URL, заголовок аутентификации, поле модели и полезная нагрузка.

Форма запроса

Минимальный вызов генерации изображения выглядит так:

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",
    "prompt": "Subject: a ceramic coffee mug on a wooden desk, steam rising\nStyle: soft natural light, editorial photography\nComposition: centered, negative space at top\nConstraints: no text, no logos",
    "n": 1
  }'

Храните ключ API в переменной окружения или менеджере секретов — никогда в исходном коде. Поле model — единственное, что нужно менять при переключении вариантов, а поле prompt содержит четырёхблочную структуру из предыдущего раздела.

В Python тот же вызов занимает несколько строк:

import os, requests

def generate(prompt, model="nano-banana-2"):
    resp = requests.post(
        "https://api.hiapi.ai/v1/images/generations",
        headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
        json={"model": model, "prompt": prompt, "n": 1},
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()

Что содержит ответ

Ответ содержит результат изображения — обычно URL или закодированную полезную нагрузку — а также метаданные, идентифицирующие модель, обработавшую запрос. Считывайте и записывайте поле модели обратно: это самый дешёвый способ постфактум определить, какой вариант сгенерировал данный ресурс.

Проверяйте параметры перед сдачей

Точный набор необязательных параметров различается по вариантам и со временем меняется. Прежде чем зашивать в код что-либо, кроме model и prompt, проверьте живую документацию моделей на актуальные имена полей и допустимые значения. Считайте недокументированное неподдерживаемым, а не угадывайте.

Обработка ответов, сбоев и повторов

Генерация изображений — это сетевой вызов, за которым стоит модель, поэтому планируйте сбойные участки.

Сначала проверяйте, потом доверяйте

После каждого ответа проверяйте три вещи: HTTP-статус, наличие полезной нагрузки изображения и совпадает ли возвращённая модель с запрошенной. При любом несоответствии явно завершайте с ошибкой, а не передавайте плохой ресурс дальше по цепочке.

Повторяйте только те сбои, которые стоит повторять

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

Используйте ограниченный экспоненциальный откат с дрожанием:

import time, random

def call_with_retry(fn, retries=3):
    for attempt in range(retries):
        try:
            return fn()
        except (TimeoutError, ConnectionError):
            if attempt == retries - 1:
                raise
            time.sleep((2 ** attempt) + random.random())

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

Осознанный откат

Если вариант продолжает сбоить, откат к другому члену семейства позволяет конвейеру оставаться работоспособным. Поскольку все три используют одну форму запроса, откат — это просто другое значение model при повторе. Заранее определите порядок — например, откат с nano-banana-pro на nano-banana-2, когда вызовы с высокой точностью повторно сбоят — и фиксируйте, когда срабатывает откат, чтобы замечать закономерности.

Делайте сбои видимыми

Проверяйте возвращённую полезную нагрузку перед её сохранением и выдавайте метрики по повторам и откатам. Когда частота ошибок растёт, вы хотите узнать об этом до того, как пакет задач молча выдаст пустые результаты.

Укрепление перед сдачей

Перед тем как показывать генерацию изображений пользователям, пройдитесь по этому списку.

Подтвердите идентификаторы и параметры

Идентификаторы моделей меняются. Перепроверьте текущие имена моделей семейства Nano Banana и сверьте каждый необязательный параметр с живой документацией. Не сдавайте значения, которые существуют только в старых примерах.

Централизуйте конфигурацию

Поместите идентификаторы моделей, шаблоны промптов и лимиты повторов в один конфигурационный модуль. Когда вы повышаете промпт с nano-banana до nano-banana-pro, это должно быть изменением конфигурации, а не изменением кода, разбросанным по нескольким файлам.

Логируйте важное

Для каждого вызова логируйте модель, версию промпта, статус ответа, задержку и были ли повторы или откаты. Хэшируйте длинные промпты, чтобы журналы оставались читаемыми. Именно это позволяет ответить на вопрос «почему это изображение вчера выглядело иначе?».

Следите за использованием при масштабировании

Поскольку оплата зависит от использования, следите за количеством вызовов и сочетанием вариантов. Если каждый запрос незаметно повышается до nano-banana-pro, инструмент исследования может превратиться в проблему затрат. Маршрутизируйте осознанно: дешёвые варианты для итераций, более сильные — для финального вывода.

Тестируйте конечную точку

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

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