Как использовать imagen-4.0-fast через HiAPI API: руководство по curl и Python

На что ориентирован imagen-4.0-fast

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

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

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

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

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

Перед первым вызовом нужно подготовить четыре вещи.

1. Аккаунт HiAPI и ключ API

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

export HIAPI_API_KEY="your_key_here"

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

2. Базовый URL и идентификатор модели

Храните две константы в одном модуле конфигурации, чтобы каждый запрос в кодовой базе указывал в одно место:

HIAPI_BASE_URL = "https://api.hiapi.ai"
HIAPI_IMAGE_MODEL = "imagen-4.0-fast"

Идентификатор модели используется для выбора imagen-4.0-fast в полезной нагрузке запроса. Относитесь к нему как к данным, а не как к жёстко заданной строке, разбросанной по разным файлам.

3. HTTP-клиент, которому вы доверяете

В Python подойдут и httpx, и requests; httpx предоставляет более понятный объект тайм-аута. В работе с оболочкой curl вполне достаточно, и это самый быстрый способ изолировать проблему: в вашем коде она или в самом запросе.

4. Минимальный инструмент тестирования

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

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

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

Ниже приведён полный, работающий вызов curl. Он генерирует изображение по текстовому промпту:

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-fast",
    "prompt": "a quiet harbor at dawn, soft mist over wooden docks, photographic",
    "n": 1,
    "size": "1024x1024"
  }'

Разбор по полям:

• -sS скрывает индикатор прогресса, но по-прежнему показывает ошибки. При отладке можно добавить -i, чтобы увидеть заголовки ответа, где обычно есть идентификатор запроса — удобно ссылаться на него при обращении за помощью.
• -X POST вместе с заголовком Content-Type: application/json делает полезную нагрузку структурированным запросом, а не непрозрачным телом.
• Authorization: Bearer $HIAPI_API_KEY — единственный механизм аутентификации. Ключ читается из переменной окружения, поэтому, если вы задали её в сессии, он не попадёт в историю оболочки в открытом виде.
• model выбирает imagen-4.0-fast в эндпоинте изображений HiAPI. Если его опустить, можно получить другую модель по умолчанию — всегда указывайте её явно.
• prompt — единственное обязательное содержательное поле. Будьте описательны, но не пишите энциклопедию; слишком длинные промпты расходуют токены и после определённого предела редко улучшают вывод быстрого уровня.
• n управляет количеством изображений, возвращаемых в ответ на запрос. Во время интеграции начинайте с 1.
• size — запрос разрешения вывода. О том, как его выбирать, рассказывается в пятом разделе.

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

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

Ниже минимальный клиент на Python, поле в поле соответствующий вызову curl и обёрнутый обработкой ошибок на уровне HTTP:

import os
import httpx

HIAPI_BASE_URL = "https://api.hiapi.ai"
HIAPI_IMAGE_MODEL = "imagen-4.0-fast"

def generate_image(prompt: str, size: str = "1024x1024") -> dict:
    api_key = os.environ["HIAPI_API_KEY"]  # fail fast if unset
    payload = {
        "model": HIAPI_IMAGE_MODEL,
        "prompt": prompt,
        "n": 1,
        "size": size,
    }
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    }
    with httpx.Client(timeout=httpx.Timeout(60.0, connect=10.0)) as client:
        response = client.post(
            f"{HIAPI_BASE_URL}/v1/images/generations",
            json=payload,
            headers=headers,
        )
    if response.status_code == 401:
        raise RuntimeError("HiAPI rejected the API key")
    if response.status_code == 429:
        raise RuntimeError("Rate limited; back off and retry")
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    result = generate_image("a quiet harbor at dawn, soft mist over wooden docks, photographic")
    print(result)

В этом фрагменте есть несколько намеренных решений:

• os.environ["HIAPI_API_KEY"] немедленно выбрасывает KeyError при отсутствии переменной, что лучше, чем отправить неаутентифицированный запрос и принять 401 за проблему с ключом.
• Явные тайм-ауты — тайм-аут соединения и тайм-аут чтения заданы раздельно. Тайм-аут чтения наиболее важен для генерации изображений, поскольку сервер удерживает соединение на время генерации.
• Ветвление по коду состояния перед raise_for_status(). 401 и 429 требуют совершенно разных реакций кода; объединение их в одно исключение делает повторные попытки легко ошибочными.
• Контекстный менеджер Client гарантирует детерминированное закрытие соединений. В долгоживущем сервисе следует создать клиент при запуске и переиспользовать его — переиспользование соединений важно для пропускной способности.

Тело ответа содержит ссылки на сгенерированные изображения и метаданные. Записывайте полное тело ответа при первых нескольких вызовах во время интеграции, чтобы точно знать, на какие имена полей опирается ваш код.

Параметры и выбор разрешения

Обработка параметров imagen-4.0-fast лучше даётся при простом, явном стиле. Держите полезную нагрузку словарём, создаваемым одной функцией, и проверяйте её перед отправкой, а не после ошибки.

Промпт

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

n

Запрос нескольких изображений за один вызов удобен для пользовательского селектора, но он кратно увеличивает работу одного запроса, продлевая время занятия соединения. Во время интеграции держите n равным 1; увеличивайте его только после измерения сквозной задержки при включении.

size

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

Детерминизм и воспроизводимость

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

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

Обработка тайм-аутов и параллелизма

Поскольку imagen-4.0-fast сохраняет короткое время генерации, большинство проблем надёжности находятся на стороне клиента: слишком низкие тайм-ауты, повторные попытки там, где их быть не должно, или слишком высокая параллельность относительно лимитов аккаунта.

Тайм-ауты

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

Повторные попытки

Повторяйте только то, что безопасно повторять: ошибки соединения и ответы 5xx. Никогда не повторяйте 4xx — некорректная полезная нагрузка будет одинаково ошибочной каждый раз. Используйте экспоненциальную задержку с джиттером и ограничьте общее число попыток. Полезная структура — три попытки с задержками около 1s, 2s, 4s с рандомизацией, что распределяет нагрузку, когда многие клиенты одновременно терпят неудачу.

Параллелизм

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

Обратное давление

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

Отладка распространённых ошибок запросов

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

401 Unauthorized

Ключ отсутствует, имеет неверный формат или не отправлен как Bearer token. Проверьте заголовок Authorization напрямую, убедитесь, что переменная окружения действительно заполнена в том процессе, который делает вызов (контейнеры и CI-раннеры отличаются от вашей оболочки), и проверьте, что вокруг значения нет лишних кавычек или завершающих пробелов. Если curl с буквальным ключом работает, а ваше приложение — нет, проблема точно в загрузке окружения.

400 Bad Request

Полезная нагрузка некорректна или значение параметра недопустимо. Воспроизведите с точным JSON, который фактически отправляет ваш клиент — записывайте сериализованную полезную нагрузку, а не словарь в памяти — и сравните с работающим примером curl. Частые причины: отсутствующий Content-Type, опечатка в model, числовые поля, отправленные как строки, и поля, оставшиеся от более ранней формы API.

422 / ошибки валидации

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

429 Ограничение скорости или исчерпание квоты

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

5xx и тайм-ауты

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

Одна общая привычка

Для каждого производственного сбоя сохраняйте воспроизведение curl с --verbose. Переход от ошибки приложения к одной копируемой команде curl сужает отладку до самого запроса. На этом поведение imagen-4.0-fast через HiAPI API становится предсказуемым.