HiAPI
Блог

Руководство

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

Nov 12, 2026
Абстрактные слоистые полупрозрачные стеклянные плоскости, преломляющие светло-серый фон в холодные синие полосы, используются как обложка для обучающего руководства
На этой странице

Что Nano-Banana как API даёт разработчикам

Nano-Banana — это модель генерации изображений, доступная через HiAPI API. Вы отправляете промпт — при необходимости вместе с одним или несколькими опорными изображениями — и получаете сгенерированное изображение. Ментальная модель на этом заканчивается. Никакого локального хостинга модели, никакого GPU, никакого дополнительного SDK: способ аутентификации, обёртка запросов и механизм асинхронных задач, которые вы используете с другими моделями HiAPI, работают и здесь.

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

Типичная интеграция делится на три этапа:

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

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

Анатомия запроса к Nano-Banana

Каждый запрос к Nano-Banana через HiAPI имеет одинаковый каркас. Меняется только полезная нагрузка.

Эндпоинт и аутентификация

Запрос отправляется на базовый URL HiAPI, а конкретная модель указывается в полезной нагрузке запроса, а не в вручную собранном URL вышестоящего сервиса. Вы аутентифицируетесь, передавая API-ключ в заголовке Authorization. Храните ключ в переменной окружения — никогда не встраивайте его в исходный код и не коммитьте в репозиторий.

Имя модели

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

Полезная нагрузка промпта

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

Необязательные опорные изображения

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

Поля, связанные с выходом

Некоторые поля влияют на форму результата, а не на его содержание: например, запрошенный выходной размер или соотношение сторон. Лучше рассматривать их как запрошенные значения, а не гарантированные — модель может вернуть размеры, немного отличающиеся от запрошенных. Код ниже по потоку должен читать фактические возвращённые размеры, а не предполагать, что запрошенное равно полученному.

Вот концептуальная структура с заполнителями:

{
  "model": "<nano-banana-model-id>",
  "prompt": "Рыжая лиса сидит в высоких травах в золотой час, малая глубина резкости",
  "reference_images": [],
  "size": "1024x1024"
}

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

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

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

export HIAPI_API_KEY="your-api-key-here"

Затем отправьте запрос на генерацию:

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<nano-banana-model-id>",
    "prompt": "Рыжая лиса сидит в высоких травах в золотой час, малая глубина резкости",
    "size": "1024x1024"
  }'

Что делает каждая часть:

  • URL — путь генерации изображений HiAPI. Один базовый URL обслуживает все модели; модель указывается в теле запроса.
  • Authorization — ваш ключ, читаемый из окружения, чтобы он не попадал в историю shell или систему контроля версий.
  • Content-Type — должен быть application/json; типичная ошибка новичка — забыть его указать и получить ошибку разбора.
  • Тело запроса — JSON-полезная нагрузка из предыдущего раздела, содержащая нужный вам промпт.

Интерпретация ответа

Ответ скажет вам, что произошло. Есть два результата, на которые стоит обратить внимание:

  • Синхронный результат — некоторые вызовы напрямую возвращают данные изображения или URL изображения. Если вы видите URL, загрузите и сохраните его как можно скорее, не полагаясь на его долгосрочную доступность.
  • Дескриптор задачи — если генерация асинхронна, ответ будет содержать идентификатор для опроса статуса. Это тема асинхронного раздела ниже.

Если вы хотите увидеть HTTP-строку статуса и заголовки ответа вместе с телом, добавьте -i в команду curl — при ошибках это очень помогает отличить проблему аутентификации от проблемы полезной нагрузки.

Тот же вызов на Python

За пределами одноразовых скриптов используйте Python. Библиотека requests позволяет сохранить пример с минимальными зависимостями и сделать HTTP-слой явно видимым.

import os
import requests

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

payload = {
    "model": "<nano-banana-model-id>",
    "prompt": "Рыжая лиса сидит в высоких травах в золотой час, малая глубина резкости",
    "size": "1024x1024",
}

response = requests.post(
    f"{BASE_URL}/images/generations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)

Несколько привычек, которые стоит завести с самого начала:

  • Задавайте таймаут. Генерация изображений медленная; без таймаута ваш рабочий процесс может зависнуть на неопределённый срок. Для синхронных вызовов щедрый таймаут — разумная отправная точка, но настраивайте его под свою нагрузку.
  • Используйте raise_for_status(). Он превращает 4xx и 5xx ответы в перехватываемые исключения, а не молча разбирает тело ошибочного ответа как результат.
  • Оберните в функцию. Приведённый фрагмент — это скрипт; в сервисе вам понадобится функция, принимающая промпт и возвращающая данные изображения или дескриптор задачи, чтобы остальной ваш код не заботился о деталях HTTP.

Если ответ содержит URL изображения, скачайте и сохраните его немедленно:

for item in data.get("data", []):
    url = item.get("url")
    if url:
        img = requests.get(url, timeout=60)
        img.raise_for_status()
        with open("output.png", "wb") as f:
            f.write(img.content)

Настоящим источником данных вашего приложения должно быть ваше собственное хранилище — а не временные удалённые URL.

Работа с асинхронными задачами

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

Сначала отправка, затем опрос

Ваш первоначальный POST вернёт что-то вроде ID задачи. Затем вы опрашиваете эндпоинт статуса с этим ID. Логика, которая вам нужна:

import time

def poll_task(task_id, api_key, interval=2, max_wait=300):
    headers = {"Authorization": f"Bearer {api_key}"}
    deadline = time.time() + max_wait
    while time.time() < deadline:
        r = requests.get(
            f"https://api.hiapi.ai/v1/tasks/{task_id}",
            headers=headers,
            timeout=30,
        )
        r.raise_for_status()
        body = r.json()
        status = body.get("status")
        if status in ("succeeded", "completed", "failed", "error"):
            return body
        time.sleep(interval)
    raise TimeoutError(f"Задача {task_id} не завершилась за {max_wait} секунд")

Три правила, которые сэкономят вам нервы

  1. Всегда ограничивайте общее время ожидания. Задание, которое никогда не завершается, не должно блокировать ваш рабочий процесс. max_wait выше — ваш путь к выходу.
  2. Делайте задержки. Фиксированный короткий интервал подходит для интерактивного использования; для пакетных заданий увеличивайте интервал по мере роста ожидания, чтобы не заваливать эндпоинт статуса запросами.
  3. Проверяйте конечное состояние. succeeded означает, что можно читать результат; failed означает, что следует прочитать полезную нагрузку ошибки, а не слепо повторять попытку. Повтор неправильно сформированной полезной нагрузки лишь тратит время.

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

Опорные изображения и согласованность персонажей

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

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

  • Лист персонажа — одно чистое опорное изображение, несколько промптов сцен, согласованные лицо и одежда.
  • Привязка стиля — опорное изображение задаёт визуальный язык, промпт направляет содержание.
  • Изображения продукта — опорное изображение объекта сохраняет его дизайн стабильным на разных фонах.

В запросе это означает заполнение поля опорных изображений вместо отправки пустого значения. Предоставляйте изображения в виде URL или закодированных данных в зависимости от того, что поддерживает спецификация параметров модели, и держите опорные изображения чистыми: один чёткий субъект лучше захламлённой сцены, потому что модель захватывает всё в кадре, а не только то, что вас интересует.

Один практичный шаблон конвейера:

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

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

Выходное разрешение и реальные ограничения

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

Запрошенный и фактический размер

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

Чем определяется качество

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

Планирование с учётом ограничений

  • Не хардкодьте размеры в коде ниже по потоку. Читайте их из возвращённого изображения.
  • Проверяйте перед сохранением. Если ваше приложение требует минимального размера, проверьте фактический размер после генерации; если он недостаточен, перегенерируйте — не предполагайте, что запрос гарантировал соблюдение требования.
  • Следите за размером файла. Вывод с более высоким разрешением означает большие полезные нагрузки; скачивайте потоково или с буферизацией, а не загружайте всё в память в цикле.
  • Будьте осторожны с пакетной обработкой. Ограничения параллелизма действуют на аккаунт; если вам нужно генерировать много изображений, добавьте небольшой пул воркеров с повторными попытками и задержками, а не заваливайте запросами неограниченный цикл.

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

Устранение типичных ошибок

Большинство первых неудачных интеграций относятся к нескольким категориям. Вот что проверять в каждой.

401 / 403 — аутентификация

Ваш ключ отсутствует, имеет неверный формат или не отправляется. Убедитесь, что заголовок Authorization присутствует, имеет префикс Bearer , а переменная окружения действительно экспортирована в shell или процесс, запускающий код. Лишний символ новой строки в конце скопированного ключа вызывает эту проблему чаще, чем вы ожидаете.

400 — некорректная полезная нагрузка

Обычно это одно из следующего: неверный JSON (лишние кавычки или висячие запятые), неверный Content-Type, отсутствие обязательного поля (например, prompt или model) или отправка поля опорных изображений в формате, который модель не принимает. Напечатайте точное тело запроса, которое вы фактически отправляете, и сравните поле за полем со спецификацией параметров.

404 — неверный путь или модель

Путь эндпоинта неверен или идентификатор модели не совпадает ни с одной моделью на платформе. Скопируйте имя модели дословно из списка, а не вводите по памяти.

Таймауты и зависание опроса

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

Пустой результат

Возврат 200 без изображения почти всегда является проблемой содержимого, а не ошибкой: промпт может быть слишком расплывчатым или отфильтрованным. Прежде чем винить API, проверьте поля ошибки или причины в теле ответа, затем уточните и проясните промпт.

Ошибки при повторных попытках

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

Если сомневаетесь, самый быстрый способ диагностики — минимальный вызов curl с простым промптом. Если он работает, проблема в вашей полезной нагрузке или коде, а не в учётных данных.

Похожие статьи

Все статьи →

Начните работать с постоянными артефактами ИИ

Получите API-ключ и вызывайте модели изображений, видео и аудио через один API на основе tasks.

Читать документацию API