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

Что такое imagen-4.0-ultra и когда его выбирать

imagen-4.0-ultra — это уровень с наивысшей точностью в семействе imagen-4.0, и HiAPI предоставляет его как модель генерации изображений на той же OpenAI-совместимой конечной точке, что и чат и другие семейства моделей. Ментальная модель проста: вы отправляете структурированное JSON-тело запроса, описывающее изображение, и получаете обратно данные изображения — а не результат чат-дополнения.

Выбор между уровнями определяется главным образом задачей, а не рейтингом:

• Черновики и итерации. Если вы исследуете подсказки, тестируете композицию или генерируете миниатюры для определения направления, более лёгкие модели изображений возвращают результат быстрее и обходятся дешевле за генерацию. Оставьте ultra для того раунда, который действительно важен.
• Финальные материалы. Ключевые визуалы, маркетинговые изображения и всё, что люди будут рассматривать в исходном размере, выигрывают от детализации, следования подсказке и способности уровня ultra справляться со сложными сценами с несколькими субъектами или элементами, похожими на текст.
• Пакетные конвейеры с порогом качества. Распространённый шаблон — сначала широко черпнуть черновики лёгкой моделью, а затем повторно запустить только выбранные подсказки на imagen-4.0-ultra. Поскольку HiAPI помещает ID модели в тело запроса, переключение уровня требует лишь изменения одной строки, а не новой интеграции.

Несколько ожиданий стоит задать заранее. Генерация изображений не мгновенна; один запрос ultra может занимать заметно больше времени, чем текстовое дополнение, поэтому проектируйте клиент с щедрым таймаутом и не предполагайте задержку менее секунды. И поскольку ответ несёт бинарные данные изображения, а не массив choices, любой код разбора, написанный для чат-моделей, не подойдёт — планируйте это заранее.

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

Предварительные условия и настройка аутентификации

Перед отправкой первого запроса убедитесь в трёх вещах: у вас есть ключ HiAPI API, вы знаете базовый URL OpenAI-совместимой конечной точки API, и ваш инструмент может выполнять HTTPS-запросы (curl или Python с requests, или даже httpx).

Держите ключ вне кода

Храните ключ в переменной окружения, а не вставляйте его в скрипт:

export HIAPI_API_KEY="your_api_key_here"

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

Заголовок аутентификации

Каждый запрос несёт стандартный заголовок Bearer-токена:

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

Оба заголовка важны. Отсутствие Content-Type может привести к тому, что сервер отклонит или неправильно разберёт тело запроса, иногда проявляясь как запутанная общая ошибка вместо чёткого сообщения валидации.

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

Быстрая проверка работоспособности

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

Сборка тела запроса

Начните с минимального тела запроса, способного сгенерировать изображение: ID модели плюс подсказка. Всё остальное — необязательные оптимизации.

{
  "model": "imagen-4.0-ultra",
  "prompt": "A sunlit reading room with tall windows, a wooden desk, and shelves of worn books, soft dust motes in the light"
}

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

Формы подсказок, которые обычно работают

• Сначала субъект, затем сцена, затем стиль. "A fox in a snowy birch forest, morning light, shallow depth of field" надёжнее, чем набор стилевых ключевых слов.
• Будьте конкретны в композиции. Упоминайте угол камеры, кадрирование или компоновку, когда они важны для вашего случая.
• Избегайте противоречий. Требование "минимализм" и "замысловатые декоративные детали" в одном предложении часто даёт компромиссный результат, который вам не нужен.

Размеры и соотношение сторон

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

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

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

Рабочий 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-ultra",
    "prompt": "A sunlit reading room with tall windows, a wooden desk, and shelves of worn books, soft dust motes in the light"
  }'

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

• -X POST — генерация изображения — это операция создания, а не чтения.
• URL — маршрут генерации изображений на OpenAI-совместимой конечной точке HiAPI. Задайте HIAPI_BASE_URL как базовый URL, указанный в документации HiAPI, чтобы путь оставался правильным даже при смене хоста.
• Два заголовка — Bearer-аутентификация и тип содержимого JSON, как описано выше.
• Тело -d — тот же JSON, который вы будете повторно использовать в Python. Кавычки важны: оберните полезную нагрузку в одинарные кавычки, чтобы оболочка не развернула ничего внутри.

Советы по отладке

Добавьте -i, чтобы включить заголовки ответа, тогда вы увидите HTTP-статус, даже если тело большое. Если хотите убедиться, что именно отправляется, добавьте -v и прочитайте строку исходящего запроса — это быстро выявляет некорректный URL или отсутствующий заголовок.

Если вывод в терминале представляет собой массу base64 или бинарного шума, это означает, что запрос успешен. Не передавайте его в логи; см. раздел об обработке ответа для более чистого подхода. Перенаправление сырого ответа в файл (> out.json) допустимо для разовой проверки.

Как только curl вернёт успешный статус и разбираемое тело, у вас есть проверенный контракт. Шаг на Python должен воспроизвести этот точный JSON байт в байт (структурно), чтобы любая дальнейшая ошибка приписывалась коду, а не другому запросу.

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

С requests эквивалентный вызов остаётся близким к версии на curl, что делает перекрёстную проверку пустяком:

import os
import requests

base_url = os.environ["HIAPI_BASE_URL"]
api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "imagen-4.0-ultra",
    "prompt": (
        "A sunlit reading room with tall windows, a wooden desk, "
        "and shelves of worn books, soft dust motes in the light"
    ),
}

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()
result = response.json()

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

• json=payload сериализует словарь и устанавливает тип содержимого за вас. Для ясности или согласованности с curl вы всё равно можете передать заголовки явно.
• timeout=120 — не украшение. Генерация изображений может быть медленной; без явного таймаута вы наследуете значение по умолчанию библиотеки, которое может быть короче, чем вы ожидаете, и прерывание клиентом будет выглядеть как сбой сервера.
• raise_for_status() превращает ответы 4xx и 5xx в исключения, а не позволяет некорректно сформированному телу ошибки попасть в ваш код разбора.

Обёртка для повторного использования

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

Поскольку тело запроса — чистый JSON, ту же функцию можно использовать для других моделей изображений на HiAPI — замените ID модели и, при необходимости, поддерживаемые параметры размера. Храните несколько примеров подсказок в тестовом скрипте, чтобы после любого обновления клиента вы могли повторно запустить заведомо рабочий запрос и быстро получить сигнал.

Обработка ответа с изображением

Ответ — это полезная нагрузка изображения, а не результат чат-дополнения. Не ищите choices[0].message.content — пишите код разбора, соответствующий тому, что фактически возвращает маршрут изображений, как описано в документации HiAPI.

Защитный разбор

Ответ обычно несёт данные изображения в виде base64-строки, иногда с метаданными. Декодируйте только после подтверждения наличия поля:

import base64

item = result["data"][0]
image_b64 = item.get("b64_json")
if image_b64 is None:
    # 某些响应可能携带 URL 或其他格式；请查阅文档
    raise ValueError(f"Unexpected image payload keys: {list(item)}")

image_bytes = base64.b64decode(image_b64)
with open("output.png", "wb") as f:
    f.write(image_bytes)

list(item) в сообщении об ошибке — полезная часть: когда полезная нагрузка меняется, оно сообщает вам фактические ключи, а не заставляет угадывать.

Логирование без выгрузки бинарных данных

Никогда не логируйте сырое тело ответа на запрос изображения — оно большое и в основном нечитаемое. Логируйте код статуса, длину содержимого, ID модели и хеш или количество байтов декодированного изображения. Этого достаточно, чтобы убедиться, что каждая подсказка дала разное изображение, не раздувая хранилище.

Операционные привычки

• Проверяйте перед сохранением. Убедитесь, что декодированные байты начинаются с распознаваемой сигнатуры изображения, и перехватывайте ошибки декодирования в месте записи файла.
• Атомарная запись. Сохраняйте во временный путь и переименовывайте после успеха, чтобы сбой посреди записи не оставил усечённый файл, выглядящий допустимым.
• Сохраняйте подсказку вместе с выводом. Рядом с каждым изображением сохраняйте подсказку, ID модели и любые параметры размера. Когда позже заинтересованная сторона попросит вариант, вам понадобится исходный запрос.
• Задайте правила хранения. Сгенерированные изображения накапливаются; решите заранее, где они хранятся и как долго.

Диагностика неудачных запросов

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

Сбой аутентификации

401 или 403 почти всегда означает неверный заголовок. Убедитесь, что схема — ровно Bearer, за которой следует пробел и ключ, без завершающих пробелов или лишних кавычек. Убедитесь, что переменная окружения действительно задана в оболочке или процессе, где вы запускаете запрос — ключ, экспортированный в одном терминале, не существует в другом. Если вы недавно ротировали ключ, убедитесь, что старое значение не закэшировано в конфигурационном файле или секрете развёртывания.

Неверный ID модели

Ответ «модель не найдена» означает, что поле model не совпадает с ID, зарегистрированным в HiAPI. Скопируйте идентификатор из документации моделей HiAPI, а не вводите заново; одного неверного символа или придуманного суффикса версии достаточно для сбоя. Если вы меняете ID модели для сравнения уровней, проверьте, что замена попала в тело запроса, а не только в комментарий.

Параметр отклонён

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

Другие симптомы

• 200, но тело пустое или неразбираемое — возможно, вы читаете не то поле. Проверьте ключи верхнего уровня перед индексацией внутрь полезной нагрузки.
• Таймаут клиента, но серверная сторона списала средства — ваш таймаут может быть слишком коротким; увеличьте его и повторите попытку с той же подсказкой один раз, прежде чем считать это сбоем.
• JSON в curl и Python различаются — выведите сериализованную полезную нагрузку в Python и сравните со строкой -d в curl. Здесь кроется большинство сообщений «в curl работает».

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