Руководство
Как использовать nano-banana-2 через HiAPI API: готовые примеры на curl и Python Requests
Руководство для разработчиков по подключению nano-banana-2 к конвейеру генерации изображений
На этой странице
Что умеет nano-banana-2 и когда его использовать
nano-banana-2 — это модель генерации изображений, вызываемая через HTTP API. Вы отправляете подсказку, опционально прикладываете исходное изображение и получаете сгенерированное изображение. Это вся ментальная модель, которая нужна вам перед написанием кода.
nano-banana-2 стоит использовать, когда нужно генерировать изображения программно внутри существующего продукта или конвейера, а не через окно чата: создание маркетинговых материалов, изготовление миниатюр и обложек, итеративные правки на основе исходного изображения или пакетные задачи, где количество изображений определяется вашими собственными данными. Поскольку его интерфейс — это обычный request/response API, вы можете поставить его за worker очереди, бэкенд-эндпоинт или CLI-инструмент, не вводя новый SDK для каждого языка.
Два режима покрывают большинство случаев:
- Генерация по тексту — вы описываете желаемое в подсказке и получаете изображение.
- Генерация по изображению — вы предоставляете исходное изображение плюс подсказку, описывающую преобразование, и получаете изменённое изображение.
У обоих режимов одинаковая форма запроса, поэтому одна обёртка клиента (которую мы построим далее в статье) обрабатывает оба. Если ваш конвейер только рендерит из текста, поле image можно полностью игнорировать. Если ваш конвейер редактирует существующие материалы, то генерация по изображению — ваша точка входа.
Чего nano-banana-2 не делает за вас: он не управляет вашими повторами, таймаутами, хранением или идемпотентностью. Это те части, которые вы строите вокруг вызова — и именно на них приходится большая часть остальной части этого руководства, поскольку наивный вызов requests.post в цикле — самая частая причина того, что «демо работает, а в продакшене нет».
Перед отправкой первого запроса
Перед первым вызовом вам нужно подготовить три вещи.
1. Учётные данные платформы
Вам нужен доступ к API платформы HiAPI и учётные данные, назначенные вашей учётной записи. Обращайтесь с ними как с секретом: загружайте из переменных окружения или менеджера секретов, никогда не коммитьте в репозиторий и никогда не вставляйте в клиентские бандлы. Каждый запрос ниже читает ключ из переменной окружения, поэтому в исходном коде не будет никакой конфиденциальной информации.
export HIAPI_API_KEY="your-key-here"
2. Клиентское окружение
Для curl вам нужен только shell, в котором можно запустить curl — примеры используют аргументы из стандартной сборки. Для Python нужны Python 3 и библиотека requests:
python3 -m venv .venv
source .venv/bin/activate
pip install requests
3. Место для хранения вывода
Генерация изображений возвращает данные изображения — встроенные в ответ или в виде ссылки, которую можно получить позже, в зависимости от формы ответа, возвращаемой вашей учётной записью. Заранее решите, будете ли вы сохранять байты на диск, загружать в объектное хранилище или возвращать URL вызывающей стороне. Продумайте это сейчас, чтобы избежать классического момента «оно работает в shell, но мне некуда положить файл».
Для начала работы не нужно оценивать лимиты или цены. Общий принцип первой интеграции: отправьте минимальный валидный запрос, убедитесь, что получаете валидный ответ, затем добавляйте параметры. Именно это делает следующий раздел.
Минимальный рабочий запрос curl
Ниже — полный вызов генерации по тексту. Эндпоинт, заголовки и тело — единственные переменные части: эндпоинт идентифицирует модель и операцию на платформе HiAPI, заголовки несут ваши учётные данные, а JSON-тело несёт полезную нагрузку.
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "nano-banana-2",
"prompt": "a minimalist isometric workspace, soft daylight, muted palette",
"n": 1
}'
Установите HIAPI_BASE_URL в базовый адрес API, указанный в панели управления вашей учётной записи HiAPI, чтобы не хардкодить имя хоста в скрипты. В теле три поля, и все три важны:
modelуказывает платформе, какую модель запускать. Оставляйте его явно, даже если вы используете значение по умолчанию где-то ещё; это делает логи самодокументируемыми.prompt— это естественный язык. Будьте конкретны в отношении субъекта, композиции и стиля; расплывчатые подсказки дают расплывчатые изображения.n— количество изображений, запрошенных для этой подсказки. Начните с1, когда проверяете, что цепочка работает.
Успешный ответ возвращает данные изображения в теле ответа. Проверьте его перед написанием любого парсера: пропустите вывод через jq или перенаправьте в файл, затем посмотрите на ключи верхнего уровня. Вы подтверждаете две вещи — что запрос был принят и где именно в ответе находится полезная нагрузка изображения.
Не спешите добавлять параметры при первом вызове. Рабочая базовая линия, которую вы понимаете, лучше, чем огромное тело запроса, которое вы скопировали. Как только этот вызов возвращает изображение, каждый следующий раздел — это его вариант.
Тот же запрос на Python
Перенесите вызов curl на Python, не меняя полезную нагрузку. Единый источник истины (один dict) означает, что тело, проверенное вами в shell, — это тело, которое вы в итоге запустите в продакшене.
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
def generate_image(prompt: str, model: str = "nano-banana-2", n: int = 1,
timeout: float = 60.0) -> dict:
"""Отправляет один запрос генерации по тексту и возвращает разобранный JSON-ответ."""
payload = {"model": model, "prompt": prompt, "n": n}
response = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=timeout,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = generate_image(
"a minimalist isometric workspace, soft daylight, muted palette"
)
print(result.keys())
Стоит подчеркнуть три детали, поскольку именно их чаще всего упускают, когда копируют фрагменты кода.
Всегда устанавливайте timeout. Без него зависшее соединение будет бесконечно блокировать ваш worker. Значение выше — лишь отправная точка, а не жёсткое правило; настраивайте его по фактически наблюдаемой задержке.
Используйте json=, а не data=. Передача dict в json правильно устанавливает тип содержимого и сериализует; передача сырой строки в data — как раз причина ошибок формата тела запроса, которые выглядят как сбои модели.
Вызывайте raise_for_status() перед разбором. Попытка разобрать ответ 4xx через .json() в поля изображения порождает запутанные нижестоящие ошибки. Сначала выявите HTTP-статус.
Эта функция и есть упомянутая ранее переиспользуемая обёртка. Следующий раздел расширит её полезную нагрузку, а не заменит её.
Полезные нагрузки для генерации по тексту и по изображению
Режимы отличаются ровно в одном месте: содержит ли тело запроса исходное изображение. Всё остальное — эндпоинт, заголовки аутентификации, имя модели — остаётся неизменным.
Генерация по тексту
{
"model": "nano-banana-2",
"prompt": "a minimalist isometric workspace, soft daylight",
"n": 1
}
Генерация по изображению
{
"model": "nano-banana-2",
"prompt": "same scene, but converted to a warm evening palette",
"image": "<base64-encoded source image>",
"n": 1
}
Концепция, которую нужно усвоить: в режиме генерации по изображению подсказка описывает преобразование, а не готовую сцену с нуля. «Преобразовать в тёплую вечернюю палитру» лучше, чем заново описывать всё изображение, потому что исходное изображение уже даёт содержимое.
Два практических замечания о поле image:
- Кодируйте исходное изображение в формате, который API документирует для этого поля, и держите закодированную нагрузку намного ниже бюджета размера запроса. Слишком большой ввод — одна из основных причин отклонения запросов.
- Если вы планируете принимать загрузки пользователей, проверяйте размер и формат до кодирования. Быстрый сбой на вашей стороне гораздо дешевле, чем круговой рейс, заканчивающийся 4xx.
Добавьте опциональный параметр image в обёртку Python, и одна функция обслужит оба режима:
def generate_image(prompt: str, image: str | None = None, **kwargs) -> dict:
payload = {"model": "nano-banana-2", "prompt": prompt, **kwargs}
if image is not None:
payload["image"] = image
# ... те же вызовы запросов, что и раньше
Поскольку ветвление — это всего лишь if, ваш вызывающий код определяет режим, а транспортный уровень остаётся неизменным. Вот награда за сохранение единой обёртки.
Обработка асинхронных задач и повторов
Генерация изображений может занимать больше времени, чем типичный вызов JSON API. Некоторые ответы сразу возвращают готовое изображение; другие возвращают задачу, которую нужно опрашивать, чтобы получить результат. Проектируйте с учётом сценария опроса, даже если ваш первый успешный вызов возвращает результат сразу — иначе ваш конвейер рухнет, когда какая-то генерация займёт слишком много времени.
Надёжный шаблон состоит из трёх частей: цикл опроса с экспоненциальной задержкой, жёсткий дедлайн и стратегия повторов, различающая «ещё не готово» и «сбой».
import time
import requests
def poll_job(job_id: str, base_url: str, api_key: str,
initial_wait: float = 2.0, max_wait: float = 30.0,
deadline: float = 300.0) -> dict:
start = time.monotonic()
wait = initial_wait
while True:
if time.monotonic() - start > deadline:
raise TimeoutError(f"job {job_id} exceeded deadline")
response = requests.get(
f"{base_url}/v1/jobs/{job_id}",
headers={"Authorization": f"Bearer {api_key}"},
timeout=30.0,
)
response.raise_for_status()
body = response.json()
status = body.get("status")
if status == "succeeded":
return body
if status == "failed":
raise RuntimeError(f"job {job_id} failed: {body}")
time.sleep(wait)
wait = min(wait * 2, max_wait)
Путь задачи и словарь статусов должны соответствовать тому, что указано в справочнике API вашей учётной записи HiAPI — скорректируйте приведённые выше ключи под соответствующую форму, но сохраните структуру.
Правила, которые поддерживают его здоровым в продакшене:
- Экспоненциальная задержка с верхним пределом. Опрос каждые 200 мс тратит квоту и нагружает эндпоинт; удвоение ожидания с верхним пределом стабилизируется около реального времени завершения.
- Ограничивайте общее число попыток и общее время.
deadlineне обсуждается. Неограниченный цикл — это ожидание сбоя в медленный день. - Повторяйте только повторяемые ошибки. Временные сетевые ошибки и ответы 5xx заслуживают ещё одной попытки с джиттером; ответы 4xx — нет, повторная отправка некорректной нагрузки только тратит время. Используйте небольшое ограниченное число повторов (два-три) и логируйте каждый.
- Сделайте повторы безопасными. Если ваш эндпоинт создания задачи принимает ключ идемпотентности, отправляйте стабильный ключ для каждого логического запроса, чтобы повторная отправка не порождала дубликаты генераций.
С дедлайном, задержкой и ограниченным числом повторов медленная генерация становится логируемым, обработанным событием, а не зависшим worker.
Отладка ошибок, с которыми вы реально столкнётесь
Когда вызов завершается неудачно, сначала прочитайте исходный код статуса и полное тело ответа, прежде чем трогать какой-либо параметр модели. Тело ответа обычно указывает на проблему. Догадки медленнее, чем логирование.
Ошибки аутентификации
401 или 403 почти всегда означает одно из следующего: ключ отсутствует в переменной окружения, заголовок имеет неправильный формат или учётные данные не активны в этом окружении. Проверьте буквальное значение заголовка, который вы фактически отправляете — отсутствие префикса Bearer или лишний перевод строки в скопированном ключе — частые причины.
Ошибки полезной нагрузки
400 с сообщением о теле запроса означает, что сам JSON некорректен: отсутствует prompt, лишняя запятая, data= вместо json= в Python или неправильно закодированное поле image. Один раз выведите точные байты, которые отправляете, проверьте их, затем уберите вывод.
Отклонённый ввод
Запросы генерации по изображению, не прошедшие валидацию, обычно связаны с входным изображением: слишком большое, неправильный формат или не декодируется. Проверяйте размер и кодировку на своей стороне перед отправкой и возвращайте чёткую ошибку тому, кто предоставил изображение, вместо повтора.
Таймауты и 5xx
Они относятся к категории повторяемых. Различайте в логах таймаут соединения и ошибку сервера и убедитесь, что ваши повторы ограничены — иначе постоянный 5xx превратится в бесконечный цикл.
Действенный порядок диагностики
- Логируйте HTTP-статус и исходный текст ответа при каждом сбое.
- Сначала проверьте путь учётных данных, раньше всего остального.
- Воспроизведите неудачную нагрузку через curl, убрав ваш клиентский код из уравнения.
- Только после этого настраивайте
prompt,imageили другие параметры модели.
Если сбой сохраняется после всех четырёх шагов, захватите ID запроса из ответа (или эквивалентное поле корреляции) и приложите его при обращении в поддержку — это превращает расплывчатый отчёт в отслеживаемый.
Приведение к готовности к продакшену
Перед запуском пройдитесь по этому контрольному списку.
- Секреты: ключ API загружается из переменной окружения или менеджера секретов и не появляется ни в каких логах, сообщениях об ошибках и клиентских бандлах.
- Таймауты: у каждого HTTP-вызова — создания, опроса и получения итогового изображения — есть явный таймаут.
- Границы: у опроса есть дедлайн, у повторов — максимальное число попыток, а в коде различаются повторяемые и неповторяемые сбои.
- Наблюдаемость: для каждого вызова логируйте форму запроса (опуская или хешируя, если подсказка может содержать пользовательские данные), код статуса, задержку и ID корреляции.
- Осознание затрат: тарификация следует измерениям, определённым вашей учётной записью HiAPI, поэтому отслеживайте, сколько генераций и сколько вывода производит каждый запрос, и инструментируйте собственные счётчики использования, чтобы неконтролируемые циклы становились видны до счёта.
- Хранение: сгенерированные изображения записываются в постоянное место — объектное хранилище или базу данных — а не остаются во временном каталоге, который исчезает вместе с контейнером.
Ни один из этих пунктов не специфичен для nano-banana-2. В этом и суть: вызов модели — простая часть, всё вокруг него — обычная гигиена распределённых систем. Постройте обёртку один раз, храните нагрузку в одном dict, и генерация по тексту и по изображению получается бесплатно.
Начните с вызова curl, перенесите его в обёртку Python, добавьте цикл опроса, затем пройдитесь по контрольному списку. Подробности о модели и актуальный справочник API см. в документации nano-banana-2 на платформе HiAPI.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий