Руководство
Руководство по API Nano-Banana-2: рабочие примеры curl и Python Requests через hiapi
На этой странице
Подготовка перед первым вызовом
Прежде чем отправить любой запрос к Nano-Banana-2, подготовьте четыре вещи. Ни одна из них не займёт много времени, а когда все четыре готовы, первый запрос превращается в упражнение по копированию и вставке, а не в поиск сокровищ.
1. Учётная запись hiapi и API-ключ
Каждый запрос аутентифицируется с помощью API-ключа, привязанного к вашей учётной записи hiapi. Создайте ключ в панели управления учётной записью и храните его в надёжном месте — в менеджере паролей или в переменной окружения на вашей машине. Относитесь к нему как к паролю: никогда не коммитьте в репозиторий и не вставляйте в общие документы.
На вашей машине экспортируйте его один раз за сессию оболочки, чтобы приведённые ниже примеры могли прочитать его без жёсткого кодирования:
export HIAPI_API_KEY="your_api_key_here"
2. Базовый URL API
Базовый URL — это корневой адрес, на основе которого строятся все запросы. При построении эндпоинта вы добавляете к нему маршрут модели. Храните базовый URL в конфигурационной переменной в коде, а не разбрасывайте по нескольким файлам — тогда при его изменении вы правите одну строку.
3. Клиент для отправки запросов
Для начала вам понадобится только один из следующих инструментов:
- curl — почти наверняка уже установлен. Используйте его, чтобы убедиться в правильности ключа и тела запроса, прежде чем писать код приложения.
- Python 3 с библиотекой
requests(pip install requests). Большинство читателей будут использовать его для построения реальной интеграции.
Полезно иметь оба: curl изолирует запрос от вашего кода, поэтому при проблеме вы сразу поймёте, в чём она — в вызове API или в приложении.
4. Чёткое понимание того, что вы хотите сгенерировать
Nano-Banana-2 поддерживает генерацию изображений по тексту и по изображению. Заранее решите, какой режим вам нужен, поскольку структура тела запроса различается (подробнее ниже). Для первого вызова начните с генерации по тексту — у неё меньше всего переменных.
Ключ экспортирован, клиент установлен, промпт продуман — теперь можно перейти к самому запросу.
Составные части запроса к Nano-Banana-2
Вызов Nano-Banana-2 — это POST-запрос с JSON-телом. Каждое поле выполняет свою роль, и понимание их по отдельности означает, что при проблеме вы можете менять одну вещь за раз.
Эндпоинт
Запрос отправляется на базовый URL API hiapi с добавленным маршрутом модели Nano-Banana-2. Метод всегда POST, потому что вы отправляете нагрузку для обработки, а не получаете ресурс.
Заголовки запроса
Важны два заголовка:
Content-Type: application/json— сообщает API, как разбирать ваше тело запроса.Authorization— содержит ваш API-ключ. Примеры ниже читают его из переменной окружения, экспортированной ранее.
Если любой из заголовков отсутствует или имеет неверный формат, запрос завершится ошибкой ещё до того, как его увидит модель. Это самый частый источник запутанных ошибок.
Поля тела запроса
Запрос генерации по тексту содержит следующие поля:
model— указывает, что запускается модель Nano-Banana-2. Указывайте явно, даже если существует значение по умолчанию; это делает код самодокументируемым и защищает вас при изменении значений по умолчанию.prompt— описание желаемого изображения на естественном языке. Здесь будет происходить большая часть вашей итеративной работы. Будьте конкретны: субъект, композиция, стиль, освещение. Расплывчатые промпты дают расплывчатые результаты.- Входное изображение — при генерации по тексту отсутствует или пустое. При генерации по изображению содержит ваше референсное изображение (подробнее в разделе о генерации по изображению).
- Параметры вывода и размера — поля, специфичные для модели, влияющие на форму или пропорции результата. Устанавливайте только те поля, которые указаны как поддерживаемые в документации модели; в строгих API неизвестные поля обычно означают отклонение запроса, а не молчаливое игнорирование.
Что возвращается
Ответ — это JSON. В зависимости от того, как построен вызов, вы получите либо непосредственно данные сгенерированного изображения, либо ссылку на него. Клиентский код должен сначала проверять HTTP-статус, а затем смотреть на тело ответа — не предполагайте, что ответ с кодом 200 обязательно содержит изображение, без проверки.
Вся структура именно такова: аутентифицированный POST-запрос с небольшим явным JSON-телом. Всё остальное в этом руководстве — лишь варианты этой формы.
Рабочий запрос curl
Это минимальный полный вызов, который вы можете отправить. Запустите его в терминале с уже экспортированным API-ключом, и через несколько секунд вы узнаете, работают ли учётная запись, ключ и сетевой путь.
curl -X POST "$HIAPI_BASE_URL/nano-banana-2" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{
"model": "nano-banana-2",
"prompt": "A weathered cabin on a rocky coastline at dawn, low fog, soft warm light, wide composition"
}'
Задайте базовый URL один раз в оболочке вместе с ключом:
export HIAPI_BASE_URL="https://api.hiapi.ai"
(Используйте базовый URL, отображаемый в вашей панели управления hiapi — именно он является авторитетным значением для вашей учётной записи.)
Чтение вывода
curl выводит сырой ответ в stdout. При успешном вызове вы увидите JSON, содержащий сгенерированное изображение. Передайте его через python -m json.tool, чтобы отформатировать вывод и подтвердить структуру:
curl -s -X POST "$HIAPI_BASE_URL/nano-banana-2" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{"model":"nano-banana-2","prompt":"a red fox in fresh snow, side profile, crisp detail"}' \
| python -m json.tool
Интерпретация увиденного
- Успешный ответ — подтверждает, что ваш ключ действителен, эндпоинт верен и тело запроса разбирается. Сохраните эту рабочую команду — это ваша базовая линия.
- Ответ с ошибкой — означает, что что-то не так в одной из трёх строк заголовков или в теле запроса. Скопируйте текст ошибки; раздел отладки сопоставляет типичные ошибки с исправлениями.
Ценность старта с curl заключается в изоляции. Ваш ключ, заголовки и JSON находятся в одном видимом месте, поэтому сбой указывает на сам запрос, а не на код приложения. Как только эта команда работает, перенос в Python становится механической работой.
Тот же запрос на Python
Ниже тот же вызов, реализованный с помощью requests. Тело запроса — это тот же самый dict, что вы видели в теле curl-запроса — сам API не меняется, меняется только способ отправки.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
payload = {
"model": "nano-banana-2",
"prompt": "A weathered cabin on a rocky coastline at dawn, low fog, soft warm light, wide composition",
}
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}",
}
response = requests.post(
f"{BASE_URL}/nano-banana-2",
json=payload,
headers=headers,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
Почему написано именно так
json=payloadзаставляетrequestsсериализовать dict за вас и установитьContent-Type. Вы всё ещё можете явно передать этот заголовок; это не повредит и делает запрос самодокументируемым.timeout=120— генерация изображений не мгновенна. Щедрый тайм-аут не даёт клиенту сдаться, пока модель ещё работает. Настройте это значение под ваш сценарий.raise_for_status()превращает ответы с кодом не из диапазона 2xx в исключения, так что сбой становится заметен сразу, а не просачивается тихо в код обработки результатов.- Переменные окружения держат ключ вне исходного кода. В производственной среде внедряйте его из хранилища секретов платформы, а не из файла
.env, который может быть закоммичен.
Извлечение изображения
Тело ответа — это JSON. Сначала один раз просмотрите его интерактивно, чтобы понять точную структуру, затем явно извлеките поле изображения:
image_url = data["image_url"] # confirm the key name against a real response
Если ваш ответ содержит данные base64 вместо URL, декодируйте их и запишите:
import base64
with open("output.png", "wb") as f:
f.write(base64.b64decode(data["image_base64"]))
Не угадывайте имена полей — выведите сырой ответ при первом успешном вызове и берите значения из того, что реально существует. Эта одна привычка предотвращает большинство дефектов интеграции.
Генерация по тексту и генерация по изображению с референсом
До сих пор речь шла о генерации по тексту: подаёте промпт, получаете изображение. Nano-Banana-2 также поддерживает генерацию по изображению, когда вы предоставляете референсное изображение, которое модель использует как ориентир. Понимание того, когда переключать режим и как меняется тело запроса, — это разница между успешным вызовом и отклонённым.
Когда использовать каждый режим
- Генерация по тексту — у вас есть идея, выраженная словами, и нет исходного изображения. Лучше всего подходит для исследования, иллюстраций и любого контента, создаваемого с нуля.
- Генерация по изображению — у вас есть готовое изображение, и вы хотите вариант, рестайлинг или редактирование с сохранением его структуры или субъекта. Это режим для итеративного дизайна, подгонки под визуальный стиль или преобразования фотографий.
Если ваш промпт звучит как «сделай так, чтобы это выглядело как…» или «сохрани компоновку, но…», вам нужна генерация по изображению.
Как референсное изображение меняет запрос
Эндпоинт и заголовки остаются прежними. Меняется тело запроса: вы добавляете поле референсного изображения рядом с промптом. В зависимости от способа предоставления изображения это поле содержит URL или закодированные данные изображения. Помните об этих правилах:
- Если передаёте ссылку, используйте URL, доступный напрямую публично. Страницы, требующие входа или проходящие через аутентифицированные перенаправления, не сработают — API нужно получить байты напрямую.
- Соблюдайте ожидаемый формат. Распространённые форматы вроде PNG и JPEG безопасны; необычные или повреждённые файлы — частая причина отклонения запроса.
- Проверяйте ограничения размера перед загрузкой. Большие изображения часто становятся причиной ошибок тела запроса.
- Держите промпт сфокусированным. При наличии референсного изображения описывайте желаемое преобразование, а не переописывайте референс.
Примерное тело запроса генерации по изображению выглядит так:
payload = {
"model": "nano-banana-2",
"prompt": "Same subject, restyled as a graphite sketch with light crosshatching",
"image_url": "https://example.com/your-reference.jpg",
}
Как всегда, сверяйте точные имена полей с вашим первым успешным ответом. Принцип прост: генерация по тексту — только промпт, генерация по изображению — та же форма запроса плюс проверенное референсное изображение. Сначала докажите работоспособность потока с генерацией по тексту, затем добавьте референсное изображение.
Обработка ошибок и отладка неудачных запросов
Сбои вызовов Nano-Banana-2 сводятся к трём категориям. Научитесь распознавать каждую, и вы сможете исправить большинство проблем за минуту.
Ошибки аутентификации
Если вы видите ошибку аутентификации, ключ не дошёл до API должным образом. Проверяйте по порядку:
- Действительно ли
HIAPI_API_KEYэкспортирован в оболочке или среде, запускающей запрос? Выполнитеecho $HIAPI_API_KEYдля проверки. - Присутствует ли заголовок
Authorizationи правильно ли он отформатирован? Важны и схема, и ключ. - Не был ли ключ отозван или ротирован в панели управления?
- Обращаетесь ли вы к правильному базовому URL для вашей учётной записи?
401 или 403 почти всегда означают одно из этих четырёх. Сам ключ редко бывает проблемой — обычно проблема в том, как он передаётся.
Ошибки формата тела запроса
Ошибки класса 400 обычно означают, что API не может разобрать или проверить ваше тело запроса:
- Недействительный JSON — лишние запятые, одинарные кавычки вместо двойных или неэкранированные символы. Помогает передача вывода curl в
python -m json.tool, а также построение тела запроса в коде, а не вручную. - Отсутствуют обязательные поля —
modelиpromptзабывают чаще всего; отправляйте оба явно каждый раз. - Неизвестные или неподдерживаемые поля — строгие API отклоняют поля, которые они не знают. Убирайте всё лишнее, пока запрос не пройдёт, затем добавляйте обратно по одному.
- Неверные типы значений — числа, отправленные как строки, или массив там, где ожидается одно значение. Строго соблюдайте типы из документации.
Плохие входные изображения
Относится только к генерации по изображению, но при возникновении наиболее раздражает: URL изображения, требующий аутентификации, URL за перенаправлением, URL, возвращающий HTML вместо изображения, слишком большой размер или неподдерживаемый формат. Убедитесь, что URL загружается непосредственно в браузере без входа, и проверьте тип и размер файла на соответствие ограничениям перед отправкой.
Работающая последовательность отладки
- Буквально прочитайте сообщение об ошибке и код состояния — они обычно указывают на проблему.
- Воспроизведите неудачный запрос в curl с минимальным набором полей, затем постепенно возвращайте сложность.
- Выведите полное тело ответа перед обработкой; не полагайтесь на свои предположения о его структуре.
Если минимальный вызов curl успешен, а ваше приложение падает, то дефект в вашем коде, а не в API. Это самое быстрое диагностическое разделение, которое вы можете сделать.
Интеграция в ваше приложение
Работающий запрос — хорошее начало; надёжная интеграция требует немного большего вокруг него. Вот как перейти от разового вызова к тому, на что можно положиться.
Оберните вызов в функцию
Изолируйте запрос в функции, которая принимает промпт (необязательно референсное изображение) и возвращает результат. Держите заголовки, базовый URL и построение тела запроса внутри этой функции, чтобы остальная часть кодовой базы никогда к ним не прикасалась. При изменении API вы редактируете одно место.
Осознанно обрабатывайте повторы
Генерация может временно сбоить по причинам, не связанным с вашим телом запроса. Используйте повторные попытки с экспоненциальной задержкой, но только для повторяемых сбоев — тайм-аутов и некоторых серверных ошибок. Никогда не повторяйте ошибки аутентификации или валидации тела запроса; они будут сбоить одинаково каждый раз, только увеличивая нагрузку. Ограничьте число попыток, чтобы устойчивые проблемы проявлялись, а не висели бесконечно.
Тайм-ауты и параллелизм
Установите тайм-аут, достаточно щедрый для генерации, но с верхним пределом, и настройте его после измерения реального времени ответа. Если вы отправляете много запросов, соблюдайте разумные ограничения параллелизма, а не отправляйте всё сразу — очередь с пулом воркеров предсказуемее неограниченных параллельных вызовов.
Храните то, что вы генерируете
Ответ даёт вам сгенерированное изображение. Своевременно копируйте его в собственное хранилище, а не полагайтесь на то, что возвращённый URL будет действителен бессрочно. Называйте файлы детерминированно и записывайте промпт и параметры рядом с каждым результатом — эта информация о происхождении понадобится вам при последующей итерации промптов.
Держите ключи вне кода
Читайте API-ключ из переменных окружения или менеджера секретов в каждом окружении. Регулярно ротируйте ключи. Если ключ оказался там, где его быть не должно, отзовите его в панели управления.
Начинайте с малого, затем расширяйте
Добейтесь работы одного промпта в curl, перенесите в Python, добавьте обработку ошибок из предыдущего раздела и только затем стройте окружающие очереди и хранилище. Каждый шаг служит доказательством предыдущего.
Имея проверенный вызов curl, соответствующий Python-клиент и обработанные три категории ошибок, вы обладаете полным путём от первого запроса до производственной интеграции.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий