Подключение API GPT Image 2.5: генерация, редактирование и миграция с Image 2

Чтобы подключить GPT Image 2.5 в HiAPI, сначала выберите gpt-image-2.5-flare или gpt-image-2.5-sunburst, затем отправьте задачу через POST /v1/tasks. Обе модели поддерживают генерацию и редактирование; наличие image_urls определяет, есть ли в запросе референсные изображения.

При миграции с Image 2 нужно одновременно изменить имя модели и входные параметры. В старой версии resolution, size, поля референсных изображений и настройки маршрутов имеют другие соглашения; если заменить только строку модели, легко оставить неприменимые параметры.

Приведённый ниже код написан по онлайн-документации HiAPI от 9 сентября 2026 года и служит для иллюстрации запросов и процесса асинхронной обработки; фактические результаты и стоимость определяются по записям задач. Актуальные параметры см. в документации Flare и документации Sunburst.

Один ID модели покрывает генерацию и редактирование

В HiAPI поля запроса у Flare и Sunburst одинаковы. После выбора модели для генерации только по тексту опустите image_urls; для редактирования добавьте 1–16 референсных изображений и укажите в промпте, что нужно изменить и что сохранить. Не отправляйте пустой массив для генерации по тексту и не добавляйте вручную суффиксы /edit или /text-to-image. Каждая задача выводит одно изображение.

Если у вас уже есть стабильный рабочий процесс работы с изображениями, можно сначала мигрировать один тип задач, сохранив прежние входные данные и критерии приёмки. О позиционировании двух моделей можно сначала прочитать различия между Image 2 и 2.5; эта статья сосредоточена на том, как реализовать запросы.

Отправка запроса на генерацию

В примере ниже генерируется квадратное изображение кружки как товара. Сохраните JSON в файл request.json. quality явно задан как medium, чтобы в дальнейшем можно было воспроизвести параметры; aspect_ratio задан как указанный в документации пиксельный размер 1024x1024.

{
  "model": "gpt-image-2.5-flare/text-to-image",
  "input": {
    "prompt": "A studio product photograph of a matte cobalt blue ceramic mug on a warm gray seamless background. Front three-quarter view, soft light from the left, subtle contact shadow, no text, no logo.",
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

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

: "${HIAPI_API_KEY:?Set HIAPI_API_KEY on your server}"
: "${HIAPI_REQUEST_ID:?Set a unique ID for this logical request}"
curl --fail-with-body --silent --show-error \
  https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer ${HIAPI_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${HIAPI_REQUEST_ID}" \
  --data-binary @request.json \
  --output created.json

После успешного создания прочитайте ID задачи из data.taskId в created.json. В этот момент изображение всё ещё генерируется асинхронно. Idempotency-Key используется, чтобы один логический запрос при повторной отправке не создавал несколько задач; полные соглашения см. в документации по созданию задач. Не считайте успешную отправку завершением изображения.

Редактирование изображения через тот же интерфейс

Ниже приведён отдельный запрос на редактирование для Sunburst. Замените заполнитель в image_urls на реальный URL референсного изображения, доступный сервису, сохраните в request.json и отправьте с новым ID запроса. Адрес example.com лишь показывает структуру полей и не может использоваться для генерации напрямую.

{
  "model": "gpt-image-2.5-sunburst/image-to-image",
  "input": {
    "prompt": "Change only the background behind the mug to pale peach. Preserve the mug shape, cobalt blue color, handle, camera angle, lighting direction, and contact shadow. Do not add text or objects.",
    "image_urls": ["https://example.com/your-mug-reference.webp"],
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

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

Для прозрачного фона задайте background как transparent и выберите PNG или WebP. JPEG не поддерживает альфа-канал. После вывода модели всё равно нужно проверять края и основной объект; настройки полей не заменяют приёмку изображения.

Проверка статуса, затем сохранение файла

GET /v1/tasks/:id возвращает сведения о задаче. queued, handling, archiving — нетерминальные состояния; только success означает, что вывод доступен, а fail предоставляет информацию об ошибке через data.error. Внешний code: 200 означает только успешность запроса; необходимо дополнительно проверять data.status. Документация по деталям задачи

В примере ниже на Python используется requests; он читает созданный ранее created.json, сначала ждёт 3 секунды, затем опрашивает каждые 4 секунды. Он сохраняет JSON с деталями и первое изображение. 10 минут — локальный лимит ожидания в примере; он не отражает SLA сервиса и не отменяет задачу на сервере. По истечении тайм-аута сохраните taskId и позже продолжите опрос той же задачи.

import json
import os
import time
from pathlib import Path

import requests

created = json.loads(Path("created.json").read_text())
if created.get("code") != 200:
    raise RuntimeError(created)
task_id = created["data"]["taskId"]
headers = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
deadline = time.monotonic() + 600
delay = 3

while time.monotonic() < deadline:
    time.sleep(delay)
    response = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers=headers, timeout=30,
    )
    if response.status_code == 503:
        delay = min(delay * 2, 30)
        continue
    response.raise_for_status()
    envelope = response.json()
    if envelope.get("code") != 200:
        raise RuntimeError(envelope)
    task = envelope["data"]
    Path("task-detail.json").write_text(json.dumps(envelope, indent=2))
    status = task["status"]
    if status == "fail":
        raise RuntimeError(task.get("error"))
    if status == "success":
        image = next(x for x in task["output"] if x["type"] == "image")
        # This example requested WebP. Do not forward the API key to the CDN.
        with requests.get(image["url"], stream=True, timeout=60) as result:
            result.raise_for_status()
            with Path("result.webp").open("wb") as output:
                for chunk in result.iter_content(1024 * 1024):
                    output.write(chunk)
        print("Saved result.webp", task_id)
        break
    if status not in {"queued", "handling", "archiving"}:
        raise RuntimeError(f"Unexpected status: {status}")
    delay = 4
else:
    raise TimeoutError(f"Resume polling this task later: {task_id}")

Временные результаты необходимо скачать или перенести до output[].expireAt. Для production-сервиса можно настроить callback на верхнем уровне запроса для получения уведомлений о терминальном состоянии, сохранив опрос как запасной вариант; поля обратного вызова не следует помещать в input. Проверку подписи обратного вызова и обработку повторных уведомлений реализуйте согласно унифицированному асинхронному API. Пример не включает бизнес-очередь, сервис обратных вызовов или полную стратегию сетевых повторов.

Миграция с Image 2: проверьте входные данные по пунктам

Старая версия Image 2 имеет другие маршруты; при миграции сначала убедитесь, какой из них используется сейчас. Ниже перечислены различия параметров между документациями HiAPI; они не применимы к прямому переносу запросов SDK других провайдеров.

Старый рабочий процесс	Изменения в Image 2.5
Генерация и редактирование используют разные ID моделей Image 2	Используйте полный ID Flare или Sunburst; различайте по наличию image_urls
Standard-редактирование использует input_urls	Замените на image_urls; старое ext-редактирование уже использовало это поле
Standard / ext используют resolution	Выберите заново соотношение или пиксельный enum в aspect_ratio под целевой размер, не сохраняйте resolution
Beta-генерация использует size	Замените на поддерживаемый документацией пиксельный enum aspect_ratio, не копируйте произвольные размеры напрямую
Явный route: "beta" / "ext" или суффикс маршрута в имени модели	Перестройте запрос согласно документации модели 2.5, не используйте старые маршруты
Поддерживаемые старой версией пропорции, например 4:5	Проверьте по пунктам; в текущем enum 2.5 нет 4:5, не заменяйте молча на другую пропорцию
Зависимость от качества, размера или формата вывода по умолчанию	Указывайте явно и заново проверяйте вывод, стоимость и последующую обработку файлов

Текущие варианты пропорций 2.5: 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16 и auto. Кроме того, aspect_ratio принимает 10 пиксельных размеров, перечисленных в документации. Если нужен фиксированный размер, выбирайте значение enum; нельзя лишь по формату строки предполагать, что любой widthxheight доступен. Особенно это касается auto: в новой документации он описан как выбор моделью подходящей композиции, и не следует напрямую наследовать предположение старого маршрута редактирования «следовать входному изображению».

Варианты качества: low, medium, high, xhigh, max, auto, по умолчанию medium. Одноимённые уровни качества не гарантируют такую же стоимость или визуальный результат, как у старых моделей. Полный старый протокол можно сверить с документацией генерации Image 2 и редактирования Image 2.

Ошибки и бюджет — в одной цепочке приёмки

При отправке 400 следует проверить имя модели, поля и enum; 402 — баланс; 415 — Content-Type. Если задача уже создана и появился fail, сохраните data.error для диагностики и не отправляйте повторно те же недопустимые входные данные. При 503 можно повторить попытку с задержкой; если из-за сетевого сбоя при POST невозможно определить, была ли создана задача, используйте прежний ключ идемпотентности, чтобы избежать дублирования задач. Описание ошибок создания задачи

Проверку затрат начинайте с текущей страницы цен HiAPI и страницы конкретной модели. При приёмке миграции фиксируйте полное имя модели, размер, качество, количество референсных изображений, запрос, вывод и фактический счёт; нельзя использовать старую цену Image 2 и нельзя принимать стартовую цену других платформ за цену HiAPI. Образцы на веб-странице помогают оценить эффект, но время работы API и счёт требуют собственных фактических записей.

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