Как использовать GPT Image 2 API: руководство по генерации изображений из текста и из изображений

Что GPT Image 2 API даёт разработчикам

GPT Image 2 API предоставляет вам единый, согласованный интерфейс для генерации изображений по подсказке. Вам не нужно склеивать нескольких поставщиков или поддерживать несколько SDK — достаточно отправить один HTTP-запрос в HiAPI.ai и получить данные изображения. Это важно, когда вы создаёте такие функции, как генератор маркетинговых материалов, иллюстрации для онбординга в приложении или пользовательские креативные инструменты, ведь задержка, время безотказной работы и предсказуемая структура запросов здесь критичны.

Вы будете использовать два режима генерации:

• Текст в изображение: вы предоставляете подсказку и целевой размер, а модель генерирует изображение с нуля.
• Изображение в изображение: вы предоставляете подсказку плюс одно или несколько референсных изображений, и модель генерирует изображение под их управлением.

Оба режима используют одинаковую аутентификацию и структуру ответа, поэтому как только у вас есть рабочий вызов, второй режим — это небольшое изменение, а не полностью новая интеграция. В этом руководстве последовательно рассказано, как выбрать между двумя вариантами, о минимальном запросе curl, обработке референсных изображений, запросе вывода 4K, переносе на Python и шаблонах обработки ошибок, которые защищают производственный конвейер изображений от тихих сбоев.

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

Текст в изображение и изображение в изображение: выбор варианта

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

Когда использовать текст в изображение

Текст в изображение — подходящий выбор по умолчанию в следующих случаях:

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

Когда использовать изображение в изображение

Изображение в изображение — правильный выбор, когда результат должен быть близок к уже существующему контенту:

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

Практическое правило

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

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

Отправьте первый запрос текст в изображение с помощью curl

Начните с curl. Он исключает переменную поведения SDK, поэтому когда что-то fails, вы можете быть уверены, что проблема в аутентификации или структуре тела запроса, а не в клиентской библиотеке.

Сначала установите API-ключ как переменную окружения, чтобы он не попал в историю shell или систему контроля версий:

export HIAPI_API_KEY="your_api_key_here"

Затем отправьте минимальный запрос:

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024"
  }'

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

1. HTTP-код состояния. 200 означает, что запрос принят и обработан. При любом другом коде сначала прочитайте тело ответа с ошибкой, прежде чем что-либо менять.
2. Аутентификация. 401 почти всегда означает, что ключ отсутствует, имеет неверный формат или истёк — убедитесь, что заголовок Authorization имеет формат Bearer, за которым следует ключ.
3. Тело запроса. 400 обычно указывает на конкретное поле: опечатка в параметре, строка размера, которую не принимает модель, или подсказка, не прошедшая валидацию.
4. Данные изображения. В зависимости от режима ответа вы получите URL, который можно загрузить, или данные изображения в base64. Обрабатывайте оба варианта, чтобы ваш клиент не оказался застигнутым врасплох позже.

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

Управление результатом с помощью референсных изображений

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

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

• Подсказка и референсное изображение должны согласовываться. Если подсказка описывает красный продукт, а референсное изображение синее, модель получит конфликтующие сигналы. Пишите подсказку как инструкцию относительно референсного изображения («перерисуй эту сцену в стиле акварели»), а не как описание, противоречащее ему.
• Отправляйте только то, что нужно. Одно сильное референсное изображение обычно лучше нескольких слабых. Несколько референсных изображений увеличивают объём загрузки и затрудняют понимание того, какое из них повлияло на результат.
• Следите за объёмом запроса. Изображения в base64 значительно раздувают полезную нагрузку запроса. Если вы загружаете большие фотографии, это первое, что нужно проверить, когда запрос становится медленным или отклоняется.
• Проверяйте перед отправкой. Убедитесь, что изображение имеет поддерживаемый формат и корректно декодируется. Некорректная строка base64 приводит к непонятным сбоям, диагностика которых отнимает много времени.

Рабочая структура запроса выглядит так:

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Restyle this scene as a soft watercolor painting, keep composition intact",
    "image": "https://example.com/reference.jpg",
    "size": "1024x1024"
  }'

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

Запрос вывода 4K

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

{
  "model": "gpt-image-2",
  "prompt": "A detailed isometric illustration of a city block, warm evening light",
  "size": "3840x2160"
}

При переходе к более высокому разрешению нужно проверить несколько вещей:

• Поддерживаемые строки размера. Значения размера проверяются в соответствии с диапазоном, принимаемым моделью. Отклонённые размеры возвращают 400, а не тихо понижаются — поэтому убедитесь в точной строке размера, которая вам нужна, вместо того чтобы угадывать близкое, но неверное значение.
• Объём ответа. Данные изображения 4K намного больше, чем результат 1K. Если ваш ответ содержит base64 или URL, который вы сразу загружаете, заложите это в память и настройки тайм-аута.
• Задержка. Генерация более высокого разрешения занимает больше времени. Задайте щедрый тайм-аут клиента, вместо того чтобы позволить медленному, но успешному запросу истечь на вашей стороне.
• Модель стоимости. Оплата зависит от размера и количества запрошенного вывода, поэтому делайте выбор осознанно: генерируйте с разрешением, которое фактически нужно функции, и понижайте разрешение в своём конвейере, если UI не требует полного разрешения. Актуальные цены смотрите на панели цен на сайте.
• Осторожное увеличение. Если вам нужен вывод больше, чем даёт модель, то масштабирование после генерации — отдельный шаг с собственными компромиссами по качеству. Осознанно решите, каким путём хотите идти.

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

Перенос запроса на Python

Не переписывайте запрос с нуля на Python. Перенесите точное тело запроса, которое вы уже проверили в curl, и отдельно подтвердите обработку ответа.

import os
import base64
import requests

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

payload = {
    "model": "gpt-image-2",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024",
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
data = response.json()

item = data["data"][0]
if item.get("b64_json"):
    image_bytes = base64.b64decode(item["b64_json"])
    with open("output.png", "wb") as f:
        f.write(image_bytes)
else:
    image_url = item["url"]
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)

Примечания к переносу:

• Храните ключ в переменной окружения, точно как в curl. Никогда не встраивайте его в код.
• Задайте явные тайм-ауты. Генерация изображений медленнее типичного вызова JSON API; использование короткого тайм-аута по умолчанию — распространённая причина ложных сбоев.
• Обрабатывайте оба режима ответа. Ветвление по b64_json и url позволяет коду работать независимо от конфигурации ответа.
• Переиспользуйте функцию. Оберните эту часть в небольшую вспомогательную функцию generate_image(prompt, size), чтобы текст в изображение и изображение в изображение различались только необязательным полем image в payload.

Поскольку словарь payload — это тот же объект, который вы тестировали в curl, любое изменение поведения, которое вы наблюдаете в Python, почти наверняка исходит от клиентской стороны — заголовков, кодировки или тайм-аутов, — что сильно сужает область отладки.

Обработка ошибок и валидация ответов

Генерация изображений по своей природе — вызов, склонный к сбоям: он медленнее большинства эндпоинтов API, несёт большие нагрузки и зависит от доступности модели. Относитесь к нему как к операции, которая иногда fails и требует повторной попытки, а не как к одноразовой операции.

Контрольный список ответа

1. Проверяйте состояние перед разбором. Вызовите raise_for_status() или проверьте код состояния и прочитайте тело ответа с ошибкой — оно обычно указывает на проблемное поле.
2. Валидируйте структуру. Перед индексацией убедитесь, что data существует и не пуст. Не предполагайте, что data[0] обязательно существует.
3. Проверяйте байты изображения. После декодирования убедитесь, что вывод не пуст и начинается с допустимой сигнатуры изображения. Файл нулевого размера — это тихий сбой, который проявится гораздо позже.
4. Записывайте ID запроса. Сохраняйте идентификатор запроса из ответа в логах, чтобы отследить неудачную генерацию без воспроизведения.

Стратегия повторных попыток

• Повторяйте только временные сбои. Тайм-ауты, сбросы соединения и ответы 5xx заслуживают повторной попытки. 401 или 400 будут fails одинаково каждый раз — исправьте запрос, а не повторяйте его.
• Используйте экспоненциальную задержку с джиттером. Начинайте с короткой задержки и постепенно увеличивайте её; джиттер предотвращает синхронные повторные попытки группы рабочих процессов.
• Ограничьте число попыток. Обычно достаточно двух-трёх повторных попыток. Дальше покажите ошибку пользователю или переведите задачу в путь недоставленных сообщений.
• Сделайте операцию идемпотентной. Поскольку повторные попытки могут породить дублирующие генерации, сохраняйте результаты с привязкой к исходному ID задачи, чтобы повторные попытки никогда не приводили к повторному списанию за видимое пользователю действие.

Адаптация к асинхронности

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

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