Как вызвать gpt-image-2.5-sunburst/text-to-image через HiAPI API: curl и Python

Что даёт этот эндпоинт модели

gpt-image-2.5-sunburst/text-to-image — это модель генерации изображений, доступная через унифицированный API HiAPI. Вы вызываете её по ID модели, отправляете промпт в теле запроса той же формы chat-completions, что и для текстовых моделей, а в ответе получаете данные сгенерированного изображения.

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

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

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

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

Нужно подготовить три вещи.

Ключ API

Создайте ключ в своей учётной записи HiAPI и храните его в переменной окружения, а не в исходном коде:

export HIAPI_API_KEY="your-key-here"

Точный ID модели

Строка — gpt-image-2.5-sunburst/text-to-image. Относитесь к ней как к непрозрачному идентификатору — скопируйте её, не перепечатывайте по памяти. Косая черта — часть ID. Опечатка здесь — самая частая причина неудачи первого вызова, и она проявится как ошибка вроде «модель не найдена», а не как проблема с полезной нагрузкой.

Клиент, умеющий отправлять HTTPS-запросы

Для первой проверки достаточно curl, который предустановлен в большинстве систем. Для кода приложения достаточно Python с библиотекой requests (или любого HTTP-клиента). Этот эндпоинт не требует от клиента специальной библиотеки для изображений; вы просто отправляете JSON и читаете JSON обратно.

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

Минимальный работающий запрос с curl

Это минимальный корректный вызов:

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
      {
        "role": "user",
        "content": "A sunlit coastal cliff at golden hour, wide angle, high detail"
      }
    ]
  }'

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

• URL — стандартный путь chat-completions HiAPI. Модели изображений используют тот же маршрут, что и текстовые модели.
• Authorization — bearer-токен с ключом API. Если этот заголовок имеет неверный формат, вы получите 401 ещё до вызова модели.
• Content-Type — должен быть application/json.
• model — точный ID модели из предыдущего раздела.
• messages — стандартный массив объектов role/content. Ваш промпт — это content сообщения user.

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

curl -sS ... -o response.json

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

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

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

import os
import requests

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

payload = {
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
        {
            "role": "user",
            "content": "A sunlit coastal cliff at golden hour, wide angle, high detail",
        }
    ],
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=(10, 180),  # connect, read
)

response.raise_for_status()
data = response.json()
print(data)

Три детали заслуживают внимания:

Тайм-аут задан явно и асимметрично

Кортеж (10, 180) задаёт короткий тайм-аут соединения и более щедрый тайм-аут чтения. Генерация изображений по своей природе занимает время; единый плоский тайм-аут, скопированный из текстового клиента, будет порождать ложные сбои. Держите тайм-аут соединения коротким, чтобы сетевые проблемы быстро завершались ошибкой.

Используйте json=payload, а не data=

Передача словаря через json= берёт на себя сериализацию и устанавливает тип содержимого за вас. Если вы передаёте предварительно сериализованную строку через data=, задайте заголовок вручную.

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

Ответ — это JSON; перед индексацией логируйте всё тело ответа при неожиданной форме. Не предполагайте фиксированную глубину вложенности, пока не увидите реальный ответ, и никогда не предполагайте форму успеха при статусе не 2xx.

Если вы предпочитаете клиентскую библиотеку, настроенную для HiAPI, отправляемая полезная нагрузка будет完全相同; меняется только место вызова.

Правильная передача референсных изображений

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

Сохраняйте структуру полезной нагрузки одинаковой во всех языках: сообщение user несёт массив содержимого, где текстовая часть содержит промпт, а часть с изображением несёт референсные данные. Тот же JSON-запрос, который вы строите на Python, должен быть выразим байт-в-байт в curl; если вы не можете написать curl-эквивалент Python-полезной нагрузки, значит структура разошлась.

Когда результат, похоже, игнорирует ваше референсное изображение, проверяйте в следующем порядке:

1. Расположение. Часть с изображением находится внутри messages[].content или просочилась на верхний уровень тела запроса? Модель видит только то, что находится в сообщениях.
2. Кодирование. Референсное изображение передаётся в запросе в виде закодированных данных. Убедитесь, что данные целостны и правильно отформатированы, а не обрезаны ручной сборкой или неаккуратным копированием.
3. Связь с промптом. Референсное изображение направляет генерацию; оно не заменяет инструкции. Явно укажите роль изображения — стиль, композиция, субъект — вместо того чтобы предполагать, что модель догадается.
4. Размер. Очень большой референс раздувает запрос и замедляет обмен. Уменьшите его до размера, который действительно нужен задаче, перед кодированием.

Полезная привычка отладки

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

Обработка ошибок, тайм-аутов и повторов

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

Отличайте клиентские ошибки от временных сбоев

• 4xx (кроме 429) — неверный формат полезной нагрузки, неверный ID модели, отсутствие аутентификации. Повтор того же запроса снова потерпит неудачу. Исправьте запрос.
• 401/403 — проблема с учётными данными. Проверьте ключ и формат заголовка Authorization.
• 429 — превышен лимит запросов. Повторите, но с экспоненциальной задержкой и джиттером, а не сразу.
• 5xx и ошибки соединения — временные. Повторите.
• Тайм-аут чтения — неоднозначен: генерация могла уже завершиться на стороне сервера. Считайте тайм-аут повторяемым, только если ваш рабочий процесс может допустить возможное дублирование.

Повторяйте только безопасное

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

import time, random

def post_with_retry(session, url, payload, attempts=3):
    for i in range(attempts):
        try:
            r = session.post(url, json=payload, timeout=(10, 180))
            if r.status_code == 429 or r.status_code >= 500:
                raise RuntimeError(f"retryable: {r.status_code}")
            r.raise_for_status()
            return r.json()
        except (RuntimeError, requests.ConnectionError, requests.Timeout):
            if i == attempts - 1:
                raise
            time.sleep((2 ** i) + random.random())

Не повторяйте в этом цикле ошибки полезной нагрузки 4xx — сразу выводите их на поверхность, чтобы ошибочный запрос громко падал, а не тратил попытки.

Соразмеряйте тайм-аут с моделью

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

Чек-лист production перед запуском

Короткий список, который предотвращает большинство инцидентов:

• ID модели в одном месте. Определите gpt-image-2.5-sunburst/text-to-image как константу или значение конфигурации, а не разрозненные строковые литералы.
• Ключи из переменных окружения, никогда не коммитятся. Меняйте их как любые другие секреты.
• Явные тайм-ауты с щедрым окном чтения, заданные на запросе, а не на значениях по умолчанию сессии.
• Повторы только при 429/5xx/тайм-аутах, с задержкой и джиттером, с ограничением числа попыток.
• Логируйте полный ответ при сбое — статус, тело ответа и ID запроса перед разбором, чтобы диалог с поддержкой начинался с доказательств.
• Сохраняйте рабочий эталонный образец полезной нагрузки для обычного случая и для случая с референсным изображением, чтобы сравнивать при изменении поведения.
• Референсные изображения внутри содержимого сообщения, уменьшенные под задачу, с указанием их роли в промпте.
• Дымовой тест в CI, который делает один реальный вызов по ID модели, чтобы переименованная или выведенная из эксплуатации модель проявилась до того, как её обнаружат пользователи.

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