HiAPI
Блог

Руководство

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

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

Nov 10, 2026
Обложка: ступенчатые бетонные плоскости пересекаются в косом солнечном свете, на тёплом сером фоне — участок тёмно-сине-серой тени и тонкие швы цвета шалфея.
На этой странице

Что делает этот эндпоинт и когда использовать image-to-image

Модели текстового-to-image отлично создают сцены с нуля, но многие производственные задачи начинаются с уже существующего изображения. gpt-image-2.6-flare/image-to-image — это именно тот эндпоинт, который HiAPI предоставляет для таких задач: вы отправляете референсное изображение и промпт, а модель возвращает преобразованное изображение, которое следует вашим инструкциям и при этом остается прочно привязанным к референсу.

Типичные сценарии использования:

  • Перенос стиля и перерисовка — превращение фотографии продукта в стилизованную иллюстрацию или перерисовка фотографии на другом визуальном языке.
  • Редактирование и доработка — изменение освещения, фона или композиции существующего материала без повторной съемки.
  • Генерация вариантов — создание нескольких визуальных вариантов базового дизайна для A/B-тестирования или творческих экспериментов.
  • Адаптация материалов — изменение размера или перекомпоновка референсного изображения под разные каналы с сохранением его ключевого объекта.

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

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

Перед вызовом этого эндпоинта убедитесь, что выполнены следующие условия:

  • Аккаунт HiAPI и API-ключ. Ключ отправляется как bearer token в заголовке Authorization. Не коммитьте его в репозиторий исходного кода, а загружайте из переменной окружения (например, HIAPI_API_KEY).
  • Идентификатор модели. Используйте строго gpt-image-2.6-flare/image-to-image — идентификатор модели чувствителен к регистру, а слэш является частью идентификатора.
  • Путь эндпоинта. Генерация изображений находится по маршруту генерации изображений на хосте API HiAPI. Смотрите страницу модели, чтобы получить актуальный базовый URL и путь, а не хардкодьте хост, который вы видели в старом фрагменте кода.
  • Файл референсного изображения в распространенном формате (PNG или JPEG — надежный выбор по умолчанию). Держите его размер разумным; слишком большие файлы замедляют загрузку и могут вызвать ограничение запросов.

Запрос к gpt-image-2.6-flare/image-to-image состоит из трех ключевых частей:

  1. Селектор модели — сообщает HiAPI, на какую модель направить запрос.
  2. Промпт (prompt) — текстовая инструкция, описывающая желаемое преобразование. Он не является необязательным; именно промпт направляет редактирование.
  3. Референсное изображение — входное изображение, на основе которого модель должна работать. Способ его передачи зависит от способа запроса (см. следующий раздел).

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

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

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

Способ A: встроить в тело запроса

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

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

Способ B: сначала загрузить, затем ссылаться по URL

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

При использовании URL нужно учесть несколько моментов:

  • URL должен быть публично доступен для API — не за аутентификацией, не localhost и не просроченная подписанная ссылка, которая перестанет работать посреди запроса.
  • Используйте тип содержимого, который принимает модель; если URL возвращает HTML вместо изображения, валидация не пройдет.
  • Предпочитайте стабильные имена файлов, чтобы можно было сопоставить логи в вашем хранилище и запросы к HiAPI.

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

Синхронные и асинхронные вызовы

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

Синхронный режим

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

Используйте синхронные вызовы, когда:

  • Вы занимаетесь прототипированием или отладкой и хотите увидеть полный результат за один шаг.
  • Запрос выполняется в среде, где блокировка на некоторое время допустима (инструменты CLI, фоновые worker'ы).
  • Вы хотите максимально простой клиент без логики опроса.

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

Асинхронный режим

Вы отправляете запрос как задачу, сразу получаете идентификатор задачи, а затем опрашиваете (или получаете callback), пока задача не завершится. Вашему клиенту нужен небольшой конечный автомат: отправить, подождать, получить результат, обработать сбой.

Используйте асинхронные вызовы, когда:

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

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

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

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

Соберем этот вызов из терминала. Сначала установите ваш ключ:

export HIAPI_API_KEY="your-api-key-here"

Шаг 1: подготовьте референсное изображение

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

ls -lh reference.png
file reference.png

file должен сообщить PNG image data или JPEG image data. Если он сообщает что-то другое, исправьте это, прежде чем продолжать.

Шаг 2: отправьте запрос

Запрос — это POST на эндпоинт генерации изображений, тело JSON содержит модель, ваш промпт и референсное изображение. В зависимости от выбранного способа загрузки поле image либо является URL, либо строкой base64.

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare/image-to-image",
    "prompt": "Recreate this scene as a flat vector illustration with a muted palette",
    "image": "https://your-storage.example.com/reference.png"
  }'

Об этих параметрах:

  • -sS скрывает индикатор прогресса, но все равно показывает ошибки — подходит для скриптов.
  • Authorization: Bearer $HIAPI_API_KEY не дает ключу появиться в самой команде.
  • $HIAPI_BASE_URL задается со страницы модели; не угадывайте хост.
  • Здесь поле image использует способ с URL; для встроенного изображения замените его строкой base64.

Шаг 3: прочитайте ответ

Добавьте -i, чтобы включить заголовки ответа, и -w '\nHTTP %{http_code}\n', чтобы вывести код состояния. Успешный вызов возвращает изображение (или ссылку на изображение, в зависимости от формата ответа) вместе с метаданными. При сбое вы получите код состояния 4xx или 5xx и JSON-тело ошибки — прежде чем что-либо менять, прочитайте поле message.

Шаг 4: перенаправьте вывод в файл

Чтобы получить чистый файл, перенаправьте stdout в файл и снова проверьте его с помощью file. Если ответ — это JSON, содержащий URL, извлеките этот URL и скачайте его вторым curl. Перед подключением к любому автоматизированному процессу обязательно убедитесь, что скачанные байты действительно являются изображением.

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

Базовый вариант на curl легко переводится на Python. В этом примере используются только стандартная библиотека плюс requests:

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "gpt-image-2.6-flare/image-to-image",
    "prompt": "Recreate this scene as a flat vector illustration with a muted palette",
    "image": "https://your-storage.example.com/reference.png",
}

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

Обработка ответа

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

def extract_image(data):
    if "url" in data:
        return requests.get(data["url"], timeout=60).content
    if "image" in data:
        import base64
        return base64.b64decode(data["image"])
    raise ValueError(f"Unexpected response shape: {list(data)}")

Обработка ошибок

Не делайте raise_for_status() единственным путем обработки ошибок. Оберните вызов и выведите сообщение об ошибке от API:

try:
    response = requests.post(url, headers=headers, json=payload, timeout=120)
    response.raise_for_status()
    image_bytes = extract_image(response.json())
except requests.HTTPError as e:
    print("HTTP", e.response.status_code, e.response.text)
    raise
except requests.Timeout:
    print("Request timed out; consider the async job route instead")
    raise

Асинхронный вариант

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

Диагностика типичных ошибок

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

Ошибки аутентификации (401 / 403)

  • Действительно ли HIAPI_API_KEY установлен в shell или процессе? echo $HIAPI_API_KEY должен его вывести.
  • Заголовок в точности Authorization: Bearer <key> — заглавная A, заглавная B, один пробел?
  • Не был ли ключ отозван или ротирован? Сгенерируйте его заново и повторите попытку с минимальным запросом.

Некорректная полезная нагрузка референсного изображения

Это самый частый сбой, и обычно он не связан с моделью:

  • URL недоступен: откройте URL изображения в браузере из другой сети. Если он возвращает 404 или перенаправляет на страницу входа, API тоже не сможет его получить.
  • Неверный тип содержимого: URL, возвращающий HTML или JSON, будет отклонен. Проверьте с помощью curl -I <url>, что в ответе Content-Type: image/....
  • Файл поврежден или нечитаем: запустите file reference.png локально. Убедитесь, что байты после декодирования строки base64 совпадают с исходным файлом.
  • Файл слишком большой: проверьте ограничения размера, указанные на странице модели; уменьшите размер перед повторной попыткой.

Ошибки формата параметров

  • Опечатка в идентификаторе модели: gpt-image-2.6-flare/image-to-image должен совпадать точно, включая слэш.
  • Отсутствует промпт: текстовая инструкция обязательна, ее нельзя опускать.
  • Лишние поля: удалите любые параметры, которые вы не можете найти в документации. Неизвестные ключи часто вызывают 4xx.
  • Синтаксис JSON: перед отправкой проверьте тело запроса с помощью jq . <<< "$BODY".

Таймауты

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

Стратегия отладки

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

Встраивание в ваш конвейер

Как только базовый вариант заработает, несколько привычек помогут gpt-image-2.6-flare/image-to-image оставаться надежным в производственной среде.

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

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

Повторяйте с экспоненциальной задержкой, но только для правильных ошибок. Временные ошибки 5xx и сетевые таймауты заслуживают повторной попытки с экспоненциальной задержкой и джиттером; ошибки 4xx, вызванные неверными параметрами, будут каждый раз завершаться одинаково, поэтому исправляйте запрос, а не повторяйте его.

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

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

Комбинируйте с другими моделями HiAPI. Этот эндпоинт естественно сочетается с текстовым-to-image, образуя гибридные процессы (сначала сгенерировать базовое изображение, затем отредактировать его); при необходимости его можно сочетать с шагами увеличения или удаления фона. Поскольку все идет через один и тот же интерфейс и аутентификацию HiAPI, добавление шага — это просто еще один вызов с тем же ключом.

Начните с базового варианта на curl, перенесите его на Python и переходите на асинхронный режим, когда этого потребует трафик. Страница модели содержит актуальные параметры запросов и ограничения — сверяйтесь с ней, прежде чем предполагать имя поля или предельный размер.

Похожие статьи

Все статьи →

Начните работать с постоянными артефактами ИИ

Получите API-ключ и вызывайте модели изображений, видео и аудио через один API на основе tasks.

Читать документацию API