Как использовать imagen4-ultra через API HiAPI: примеры на curl и Python

Что imagen4-ultra на HiAPI может вам дать

imagen4-ultra — это высококачественная модель генерации изображений по тексту от HiAPI: вы отправляете запрос (промпт) и получаете готовое изображение. Для разработчиков это по-настоящему удобно тем, что, как и все остальные модели платформы, она работает за единым интерфейсом HiAPI, поэтому способы аутентификации, структура запросов и модель обработки задач, которые вы здесь освоите, без изменений переносятся на другие эндпоинты.

Этот урок — рабочая практика, а не перечень параметров. К концу вы получите:

• запрос curl, который можно сразу скопировать и вставить для отправки задачи генерации изображения;
• небольшой Python-клиент, переписанный из того же запроса;
• чёткое понимание того, как соотношение сторон и другие опции влияют на результат;
• цикл опроса для ожидания завершения задачи и сохранения изображения на диск.

Сразу оговорюсь: генерация изображений не мгновенная. imagen4-ultra работает асинхронно — вы отправляете задачу, получаете идентификатор задачи и опрашиваете её до завершения рендеринга. Если вы уже работали с другими асинхронными эндпоинтами HiAPI, эта схема будет знакомой; если нет — раздел про опрос охватывает весь жизненный цикл.

Мы всё время остаёмся в рамках собственного API HiAPI: без SDK конкретных вендоров и без сторонних консолей. Один базовый URL, один ключ, один формат запроса.

Перед отправкой первого запроса

Чтобы первый вызов прошёл успешно, вам понадобятся три вещи.

1. Ключ API

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

export HIAPI_API_KEY="your-key-here"

2. Базовый URL

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

export HIAPI_BASE_URL="https://api.hiapi.ai"

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

3. Как передаётся аутентификация

HiAPI использует bearer-токен в заголовке Authorization. Каждый запрос — и отправка, и опрос — несёт одни и те же два заголовка:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

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

Прежде чем продолжить, сделайте базовую проверку: убедитесь, что ваш ключ экспортирован в той же сессии оболочки, в которой вы будете запускать curl. Значительная доля сообщений «401 Unauthorized» в итоге сводится к тому, что ключ экспортирован в одной вкладке терминала, а используется в другой.

Далее мы всегда будем считать идентификатором модели imagen4-ultra. Если хотите убедиться в точной строке, доступной вашей учётной записи, посмотрите список моделей в документации.

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

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

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen4-ultra",
    "prompt": "Одинокий маяк на скалистом побережье в сумерках, длинная выдержка, драматичные облака, кинематографичное освещение",
    "aspect_ratio": "16:9",
    "n": 1
  }'

Разберём тело запроса по полям:

• model — идентификатор вызываемой модели. Он определяет маршрутизацию запроса; без него API не знает, какую модель запускать.
• prompt — описание изображения на естественном языке. Это главный рычаг влияния на качество результата. Будьте конкретны насчёт субъекта, освещения, стиля и композиции; расплывчатый промпт даёт расплывчатое изображение.
• aspect_ratio — форма выходного холста в виде ширина:высота. Подробнее ниже.
• n — сколько изображений сгенерировать в этой отправке. Во время тестирования держите значение 1, чтобы стоимость каждого запуска было легко посчитать.

В зависимости от конфигурации эндпоинта ответ либо содержит готовое изображение, либо — что чаще для таких моделей — объект задачи с идентификатором и полем статуса. Сохраните этот идентификатор; раздел про опрос опирается на него.

# Типичная структура ответа на отправку
{
  "id": "job_abc123",
  "status": "queued"
}

Пропустите ответ через инструмент форматирования JSON (если есть — | jq .), чтобы вы могли читать имена полей по ответу своей учётной записи, а не щуриться на одну длинную строку.

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

Версия на Python — построчный перевод: тот же URL, те же заголовки, то же тело запроса. Использование requests делает соответствие очевидным:

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "imagen4-ultra",
    "prompt": "Одинокий маяк на скалистом побережье в сумерках, длинная выдержка, драматичные облака, кинематографичное освещение",
    "aspect_ratio": "16:9",
    "n": 1,
}

response = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers=headers,
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
print(job["id"], job["status"])

При переносе этого кода в реальный сервис стоит сохранить несколько вещей:

• Читайте ключ из переменной окружения, никогда не из литерала в файле. Запись os.environ[...] явно падает при отсутствии переменной — именно это вам и нужно.
• Задайте явный таймаут для вызова отправки. Сама задача выполняется асинхронно, поэтому HTTP-запрос должен возвращаться быстро; ограничение в 30 секунд отловит сетевые проблемы, а не подвесит программу.
• Вызывайте raise_for_status() до обращения к JSON. Тело 4xx-ответа — не та структура, которую вы ожидаете; ранний сбой даёт более понятную трассировку, чем KeyError через три строки.
• Переиспользуйте requests.Session, если отправляете много задач — пул соединений значит больше, чем кажется.

Если предпочитаете httpx или aiohttp, преобразование механическое: тот же словарь headers, то же JSON-тело, тот же путь. Сам запрос не зависит от HTTP-библиотеки.

Соотношение сторон и опции запроса

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

Соотношение сторон передаётся в теле запроса строкой "width:height" — "1:1", "16:9", "9:16", "4:3", "3:2" и так далее. Выбирайте пропорцию, соответствующую конечному сценарию использования изображения:

• 1:1 — аватары, карточки товаров, посты в соцсетях, которые обрезаются до квадрата.
• 16:9 / 9:16 — ключевые баннеры, миниатюры видео, размещения в вертикальном формате историй.
• 4:3 / 3:2 — классическая фотографическая композиция, галерейные раскладки.

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

Помимо соотношения сторон, в повседневной работе важны такие опции:

• prompt — по-прежнему самый влиятельный вход. Итерации начинайте здесь, прежде чем где-либо ещё.
• n — количество изображений на одну отправку. Полезно, когда нужны несколько вариантов на выбор; на этапе исследования промпта держите значение низким.
• model — точный идентификатор варианта модели. Если ваша учётная запись предоставляет несколько моделей изображений, это переключатель между ними.

Придерживайтесь параметров, задокументированных для этого эндпоинта, и не угадывайте имена. Неизвестные поля — частая причина 400-ответов, а опечатка в опции легко теряется в большом теле запроса. Если сомневаетесь, сначала отправьте минимальное тело — model, prompt, aspect_ratio — убедитесь, что оно работает, а затем добавляйте опции по одной.

Опрос асинхронной задачи и скачивание результата

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

Шаг 1: отправить и захватить ID задачи

Повторно используйте предыдущий запрос и извлеките id из ответа:

job = response.json()
job_id = job["id"]

Шаг 2: опрашивать до перехода задачи в конечное состояние

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

import time

def wait_for_job(job_id, headers, base_url, timeout=300):
    deadline = time.time() + timeout
    delay = 2
    while time.time() < deadline:
        r = requests.get(
            f"{base_url}/v1/images/generations/{job_id}",
            headers=headers,
            timeout=30,
        )
        r.raise_for_status()
        data = r.json()
        status = data["status"]
        if status == "succeeded":
            return data
        if status == "failed":
            raise RuntimeError(f"job failed: {data}")
        time.sleep(delay)
        delay = min(delay * 2, 15)
    raise TimeoutError(f"job {job_id} not finished within {timeout}s")

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

Шаг 3: скачать изображение

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

result = wait_for_job(job_id, headers, BASE_URL)
image_url = result["output"][0]["url"]

img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("lighthouse.png", "wb") as f:
    f.write(img.content)

Две привычки, которые предотвращают большинство неожиданностей в продакшене: всегда открывайте файл в бинарном режиме ("wb"), никогда в текстовом; и считайте URL для скачивания временным — сразу сохраняйте файл в собственное хранилище, а не рассчитывайте, что ссылка будет действовать бессрочно.

Частые ошибки и способы их исправления

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

401 Unauthorized

Ключ отсутствует, имеет неверный формат или не виден процессу, делающему запрос.

• Проверьте, что заголовок в точности Authorization: Bearer <key> — слово Bearer, пробел, затем ключ.
• Убедитесь, что переменная окружения задана в той же оболочке или процессе. В контейнерах и CI переменные, экспортированные в вашей локальной оболочке, не переходят вместе с кодом.
• Если вы недавно меняли ключ, убедитесь, что старый нигде не остался закэширован.

400 Bad Request

Обычно это проблема тела запроса.

• Неизвестное или с опечаткой имя поля — придерживайтесь параметров, задокументированных для эндпоинта.
• Значение aspect_ratio, которое эндпоинт не принимает — используйте форму width:height из документации.
• Значение n вне допустимого диапазона.
• Некорректный JSON — например, лишняя запятая или неэкранированные кавычки внутри строки промпта. Если подозреваете это, отформатируйте и выведите тело запроса перед отправкой для проверки.

404 при запросе статуса или на шаге скачивания

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

Таймаут опроса

Если wait_for_job достиг дедлайна:

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

Статус задачи failed

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

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