Руководство
Как использовать gpt-image-2.6-sunburst/image-to-image через HiAPI API: практика с curl и Python
Отправка референсного изображения, опрос асинхронных задач и сквозная отладка запросов
На этой странице
Когда уместен gpt-image-2.6-sunburst/image-to-image
Генерация по тексту даёт вам результат, в котором модель свободно интерпретирует подсказку. Генерация «изображение в изображение» отталкивается от уже имеющегося у вас материала: вы передаёте эндпоинту референсное изображение и инструкцию, и модель создаёт новое изображение, производное от этого референса. В HiAPI gpt-image-2.6-sunburst/image-to-image — это эндпоинт, предназначенный именно для этого второго режима.
Выбирайте его, когда исходное изображение само по себе является частью требования — например, для рестайлинга существующего материала, корректировки освещения или композиции, применения определённой визуальной обработки к продуктовому фото или создания контролируемых вариантов дизайна. Референс служит якорем: он несёт субъект, палитру и компоновку, а ваша подсказка описывает преобразование, а не сцену с нуля. Если у вас нет исходного материала и вы просто хотите получить изображение по описанию, эндпоинт генерации по тексту проще и даёт модели больше свободы.
Два практических следствия определяют всё дальнейшее. Во-первых, запрос несёт почти бинарный вход (ссылку на изображение), что влияет на то, как вы строите тело запроса. Во-вторых, генерация изображения не мгновенна, поэтому эндпоинт работает как асинхронная задача, а не возвращает изображение напрямую. Планируйте два шага — «отправка» и «получение», — а не один блокирующий вызов.
Предварительные условия и настройка аутентификации
Прежде чем отправить первый запрос, вам понадобятся три вещи: учётная запись HiAPI, ключ API и способ передать ссылку на исходное изображение, который принимает эндпоинт. Создайте ключ в консоли HiAPI и обращайтесь с ним как с паролем — он авторизует каждый вызов, засчитываемый на ваш аккаунт.
Передавайте ключ как bearer-токен в заголовке Authorization. Никогда не жёстко прописывайте его в исходниках, блокнотах или истории коммитов. Экспортируйте его в переменную окружения для тестирования в shell, а в коде приложения читайте из окружения (или менеджера секретов):
export HIAPI_API_KEY="your_api_key_here"
Заранее решите, как вы будете передавать референсное изображение. Обычно можно загрузить материал во временное хранилище и передать URL либо отправить изображение в теле запроса как данные в base64. URL делает запрос меньше и удобнее для логирования; base64 избавляет от дополнительного хостинга, но раздувает тело запроса. В любом случае держите файл в формате, поддерживаемом эндпоинтом, и проверяйте ограничения размера перед отправкой. Также запишите базовый URL HiAPI API для вашей учётной записи — каждый путь ниже должен иметь его в качестве префикса.
Отправка референсного изображения с помощью curl
Начните в shell, чтобы точно видеть, что именно отправляется. Форма вызова — POST на эндпоинт «изображение в изображение» с JSON-телом, содержащим референс и инструкцию.
curl -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-sunburst/image-to-image",
"image": "https://your-bucket.example.com/reference.png",
"prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
"n": 1
}'
Разберём по полям: model выбирает эндпоинт; image несёт референсное изображение (здесь URL; если вы не размещаете файл, то строка данных в base64); prompt — это инструкция редактирования, которая должна описывать изменения, а не заново описывать субъект; n — количество желаемых результатов. Делайте prompt конкретным и ограниченным по охвату — инструкции, противоречащие референсу, легко дают хаотичные результаты.
Отправьте запрос и проверьте тело ответа. Для асинхронного эндпоинта вы не получите готовое изображение; вы получите идентификатор задачи или объект состояния. Сохраните этот ответ перед тем, как продолжить — это дескриптор для всего последующего. Быстрая проверка с curl -i также покажет HTTP-код состояния — это самый быстрый способ отличить проблемы аутентификации (4xx при отправке) от проблем с содержимым.
Тот же вызов на Python
После успешного вызова в shell перенесите его на 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-sunburst/image-to-image",
"image": "https://your-bucket.example.com/reference.png",
"prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
"n": 1,
}
resp = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
resp.raise_for_status()
job = resp.json()
print(job)
Отличия от curl механические: ключ берётся из os.environ, тело запроса — это dict, сериализуемый в JSON, а raise_for_status() превращает неудачную отправку в исключение, а не в тихую ошибку. Последняя строка важна — большая часть боли при отладке возникает из-за того, что ответ 4xx принимают за успех, а затем опрашивают ID задачи, который никогда не существовал.
Для бинарного входа прочитайте файл, закодируйте его в base64 и поместите строку в image вместо URL. Остальная часть тела запроса не меняется, поэтому вы можете переключать способ, не трогая логику запроса.
Обработка жизненного цикла асинхронной задачи
Генерация изображения занимает время, поэтому эндпоинт следует схеме «сначала отправка, затем опрос». Понимайте три состояния, а остальное — вопрос ведения записей.
1. Отправьте и сохраните задачу
Ваш POST вернёт идентификатор задачи. Немедленно извлеките его и сохраните куда-нибудь — строку в базе данных, сообщение в очереди, строку в логе, по которой можно выполнить запрос. Если ваш процесс упадёт между отправкой и опросом, этот идентификатор — единственный способ восстановить уже оплаченную работу.
2. Опрашивайте до завершения задачи
С фиксированным интервалом опрашивайте эндпоинт состояния, используя ID задачи. Начните консервативно — несколько секунд между проверками — и постепенно увеличивайте интервал для длинных задач, чтобы не бомбардировать API. Останавливайтесь в терминальном состоянии: успех, ошибка или ваш собственный тайм-аут. Никогда не опрашивайте в плотном цикле.
import time
def wait_for_job(job_id, base_url, api_key, timeout=300, interval=2):
deadline = time.time() + timeout
while time.time() < deadline:
r = requests.get(
f"{base_url}/v1/images/jobs/{job_id}",
headers={"Authorization": f"Bearer {api_key}"},
timeout=30,
)
r.raise_for_status()
data = r.json()
if data["status"] in ("succeeded", "failed"):
return data
time.sleep(interval)
interval = min(interval * 1.5, 15)
raise TimeoutError(f"job {job_id} not finished in time")
3. Получите и сохраните результат
При успехе ответ указывает на сгенерированное изображение. Если URL временный, скачайте его своевременно и запишите в собственное хранилище под контролируемым вами именем, чтобы потребители ниже по потоку никогда не зависели от временной ссылки. Записывайте ID задачи вместе с сохранённым материалом — это самое дешёвое подспорье для отладки.
В производственной среде опрос должен выполняться фоновым worker'ом, а не обработчиком запросов. Веб-запрос, блокирующийся на всё время генерации изображения, и хрупок, и без необходимости занимает соединение.
Распространённые ошибки и способы исправления
Когда вызов не удаётся, проверяйте по этому списку сверху вниз; первый пункт ловит большинство проблем.
401 / 403 при отправке
Проблема аутентификации. Проверьте, что ключ присутствует в заголовке Authorization, используется схема Bearer и что при копировании-вставке не попали лишние пробелы или переводы строк. Убедитесь, что переменная окружения действительно установлена в shell или процессе, выполняющем запрос.
400 / 422 на тело запроса
Тело запроса имеет неверный формат или какое-то поле ошибочно. Частые причины: синтаксическая ошибка JSON из-за ручного набора строки curl, значение image, которое не является ни доступным URL, ни допустимым base64, отсутствие prompt или неподдерживаемый формат изображения. Проверьте JSON локально и убедитесь, что референсное изображение действительно открывается в браузере.
404 на модель или путь
Опечатка в пути или имени модели. Идентификатор модели — точная строка: gpt-image-2.6-sunburst/image-to-image отличается от варианта для генерации по тексту и чувствителен к регистру.
Тайм-ауты и зависший опрос
Отличайте медленную задачу от испорченной. Устанавливайте timeout для каждого HTTP-вызова, задавайте собственный общий дедлайн и при сдаче фиксируйте последнее наблюдавшееся состояние задачи. Если задачи регулярно превышают ваш дедлайн, увеличьте его, а не переходите на плотный цикл повторных попыток.
Пустой или непригодный вывод
Задача успешна, но изображение не то, что вы хотели. Обычно это проблема подсказки: инструкция слишком расплывчата или конфликтует с референсом. Сделайте инструкцию редактирования более конкретной в отношении того, что должно измениться и что должно остаться неизменным.
Рекомендации для производственного конвейера «изображение в изображение»
После того как прототип заработал, остаётся работа над надёжностью и предсказуемостью.
- Повторяйте только повторяемые ошибки. Используйте экспоненциальную задержку для повторных попыток при неудачной отправке из-за 5xx и сетевых ошибок; не повторяйте вслепую 4xx, это лишь снова провалится. Отслеживайте идемпотентность самостоятельно, привязывая ключ задачи к вашему собственному ID запроса, чтобы повторные попытки не дублировали работу.
- Разделяйте отправку и опрос. Поместите отправку и опрос в разные worker'ы или стадии. Это делает задержку вашего API независимой от времени генерации и позволяет масштабировать опрос отдельно.
- Контролируйте собственное хранилище. Сразу после завершения задачи скачивайте результат в собственный bucket. Считайте возвращённый URL временной ссылкой.
- Храните подсказки под версионным контролем. Подсказки — это производственные активы. Сохраняйте подсказку, референсное изображение и ID задачи вместе с каждым результатом, чтобы через несколько месяцев вы могли воспроизвести или объяснить результат.
- Следите за задержкой и затратами. Задачи с изображениями оплачиваются за результат, поэтому ограничивайте число параллельных задач на пользователя и ведите учёт использования по задачам. Отслеживайте p95 задержки от отправки до сохранения материала — это то число, которое реально ощущает пользователь.
Как только форма запроса и жизненный цикл определены, остальное — обычная инженерия. Детали модели вы найдёте в документации HiAPI, а оттуда подключите эндпоинт к своему конвейеру.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий