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

Возможности imagen-4.0 в HiAPI

imagen-4.0 — это модель генерации изображений по тексту: вы отправляете подсказку на естественном языке, а она возвращает сгенерированное изображение. Как разработчику интеграции, вам важно не столько устройство модели, сколько контракт вокруг неё. В HiAPI этот контракт представляет собой HTTP-эндпоинт — он принимает JSON и аутентифицирует запросы с помощью bearer-ключа — что в точности совпадает с шаблоном, который вы уже знаете по вызовам chat completion и embedding.

Практические преимущества использования HiAPI вместо прямого подключения к модели:

• Единая схема аутентификации. Один и тот же API-ключ подходит для всех моделей платформы, поэтому вам не нужно переключаться между учётными данными разных провайдеров.
• Единый формат запроса. Одно тело JSON-запроса, содержащее идентификатор модели и подсказку. Не нужно изучать структуру запросов конкретного SDK.
• Синхронный ответ. imagen-4.0 возвращает результат в том же HTTP-ответе, поэтому в базовых сценариях не нужно строить циклы опроса или вебхуки.

Это руководство проведёт вас от нуля до рабочего запроса на curl и Python, а затем объяснит, как читать ответ и что подготовить перед выходом в продакшен.

Получение API-ключа и настройка аутентификации

Каждый вызов imagen-4.0 в HiAPI аутентифицируется с помощью bearer-токена. Вы создаёте API-ключ в своей учётной записи HiAPI, и после этого ключ становится единственной учётной данными, необходимой для запроса — без отдельного идентификатора проекта и без подписи заголовков.

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

Локальная настройка

Экспортируйте ключ в сеансе оболочки:

export HIAPI_API_KEY="your-key-here"

Если вы хотите, чтобы переменная сохранялась постоянно, добавьте эту строку в файл конфигурации оболочки; или используйте файл .env, добавьте его в .gitignore и загружайте при запуске приложения.

Развёрнутая среда

В CI и продакшене задавайте HIAPI_API_KEY через менеджер секретов платформы — внедряйте переменную окружения во время выполнения, а не встраивайте файл в образ. Так код приложения будет одинаковым локально и в развёрнутой среде, различаться будет только источник переменной.

Заголовок запроса

Каждый запрос содержит:

Authorization: Bearer $HIAPI_API_KEY

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

Поймите структуру запроса до отправки

Тело запроса imagen-4.0 достаточно мало, чтобы держать его в голове, и в этом суть — поняв его структуру, вы сможете построить запрос на любом языке, не переводя скопированный фрагмент кода.

Минимум, что нужно отправить:

{
  "model": "imagen-4.0",
  "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
}

Два поля выполняют основную работу:

• model указывает, какая модель обрабатывает запрос. Это строка и тот же идентификатор, который платформа использует везде, где упоминается imagen-4.0. Если указать его неверно, вы получите ответ с ошибкой, а не молчаливый откат.
• prompt — описание желаемого изображения. Пишите так, как описали бы картинку человеку: субъект, сцена, стиль, освещение. Конкретные подсказки дают более предсказуемые результаты, чем подсказки из одного слова.

Запрос отправляется методом POST с Content-Type: application/json на эндпоинт генерации изображений платформы. У модели могут быть дополнительные необязательные параметры, но тело запроса из двух полей выше — это полный, рабочий запрос — начните с него и добавляйте параметры только при необходимости.

Поскольку тело запроса — это чистый JSON, curl, Python, Node и любой инструмент с HTTP-клиентом равноправны. Следующие два раздела покажут один и тот же запрос в двух вариантах.

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

Начните с терминала, где вы увидите сырой ответ без искажений при разборе.

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0",
    "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
  }'

Разбор по строкам:

• -sS подавляет индикатор прогресса, но показывает ошибки, так что вывод остаётся читаемым и не скрывает сбои.
• -X POST задаёт метод запроса. Генерация изображения создаёт контент, поэтому используется POST.
• URL — это эндпоинт генерации изображений на платформе, составленный из вашего базового URL и пути. Храните базовый URL в переменной, чтобы одна и та же команда работала в разных средах.
• Первый заголовок содержит ваш bearer-ключ, считанный из ранее экспортированной переменной окружения.
• Content-Type: application/json сообщает серверу, как разбирать тело запроса.
• -d передаёт тело JSON. Одинарные кавычки не дают оболочке интерпретировать фигурные скобки и кавычки; JSON внутри — буквальный.

Если хотите проверить вывод, пропустите его через инструмент форматирования JSON:

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"imagen-4.0","prompt":"A weathered lighthouse on a cliff at dusk"}' \
  | python -m json.tool

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

Тот же запрос на Python

Вызов curl легко переносится. Единственный реальный выбор — HTTP-клиент; встроенный urllib работает везде, но код с requests короче и эта библиотека уже есть в зависимостях большинства кодовых баз.

Переиспользуемая вспомогательная функция

import os
import requests

HIAPI_BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai/v1")


def generate_image(prompt: str, model: str = "imagen-4.0") -> dict:
    api_key = os.environ["HIAPI_API_KEY"]
    response = requests.post(
        f"{HIAPI_BASE_URL}/images/generations",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={"model": model, "prompt": prompt},
        timeout=120,
    )
    response.raise_for_status()
    return response.json()


result = generate_image("A weathered lighthouse on a cliff at dusk")
print(result)

Стоит отметить три момента:

• os.environ["HIAPI_API_KEY"] немедленно выбрасывает KeyError при отсутствии переменной, что приводит к быстрому и громкому сбою вместо отправки пустого токена.
• json= автоматически сериализует словарь и задаёт тип содержимого, поэтому поведение запроса полностью совпадает с версией curl.
• timeout=120 ограничивает длительность вызова. Генерация изображения занимает больше времени, чем дополнение текста, поэтому используется щедрый таймаут вместо стандартного отсутствия таймаута.

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

Чтение синхронного ответа и обработка ошибок

imagen-4.0 отвечает синхронно: сгенерированное изображение возвращается в том же HTTP-ответе. В базовом сценарии нет идентификатора задания для опроса и нет цикла опроса для написания — относитесь к вызову как к любому другому взаимодействию запрос-ответ.

Что возвращается

Успешный ответ — это объект JSON. Разберите его с помощью response.json() в Python или пропустите вывод curl через инструмент форматирования JSON, затем найдите данные изображения в возвращаемой структуре — обычно это URL или закодированная полезная нагрузка изображения, а также метаданные о генерации. Прочитайте точные имена полей из реального ответа один раз, а затем пишите код на их основе.

Что нужно предотвратить

Оберните вызов и проверяйте статус перед разбором:

try:
    result = generate_image("A weathered lighthouse on a cliff at dusk")
except requests.HTTPError as e:
    print("HTTP error:", e.response.status_code, e.response.text)
except requests.Timeout:
    print("Request timed out")

Режимы сбоя, которые стоит обрабатывать явно:

• 401 — ключ отсутствует или недействителен. Исправьте переменную окружения, а не код.
• Обычные 4xx — неверный формат тела запроса, неверный идентификатор модели или отклонённая подсказка. Тело ответа обычно указывает, какой именно случай. Записывайте в журнал.
• 5xx — сбой на стороне сервера. Их стоит повторять с экспоненциальной задержкой.
• Таймаут — рассматривайте как неизвестный результат, а не как успех; не предполагайте, что изображение было сгенерировано.

Всегда записывайте код состояния и усечённое тело ответа при сбое. Отладка без этой информации — это догадки.

От первого запроса к продакшену

Запрос работает. Прежде чем масштабироваться, проверьте по пунктам:

• Конфигурация. Базовый URL и API-ключ берутся из окружения. Никаких литералов в исходном коде, никаких ключей в образах.
• Таймауты. У каждого вызова изображения есть таймаут. Без таймаута зависший запрос может бесконечно занимать рабочий процесс.
• Повторы. Повторяйте только 5xx и таймауты, используя экспоненциальную задержку с верхним пределом. Никогда не повторяйте 401 или 4xx с неверным телом запроса — они будут сбоить точно так же.
• Логирование. Записывайте модель, длину подсказки, код состояния и задержку для каждого вызова. Не записывайте ключи и, если подсказка может содержать пользовательские данные, не записывайте полную подсказку.
• Осознание затрат. Генерация изображений оплачивается по произведённому выводу, поэтому отслеживайте, сколько изображений запрошено на пользователя или на задание, и устанавливайте лимиты на уровне приложения. Актуальные тарифы смотрите на панели цен платформы, а не в этом руководстве.
• Параллелизм. Вызовы изображений медленнее текстовых. Исходя из этого задавайте размер пула рабочих процессов, а не предполагайте задержку chat-completion.

Когда всё это готово, та же вспомогательная функция generate_image без изменений подходит для пакетных заданий, пользовательских функций и внутренних инструментов. Дополнительные детали интеграции см. в документации платформы.