GPT Image 2 / 2.5: генерация и редактирование изображений

Выберите эндпоинт перед написанием запроса: text-to-image использует /images/generations; image-to-image использует /images/edits с загруженными файлами изображений. Упоминание «reference image 1» в промпте не прикрепляет изображение.

Модели и эндпоинты

Model ID	Text-to-image	Image-to-image
gpt-image-2	/images/generations	/images/edits + файлы изображений
gpt-image-2.5-sunburst	/images/generations	/images/edits + файлы изображений
gpt-image-2.5-flare	/images/generations	/images/edits + файлы изображений

Это разные идентификаторы моделей. При переключении моделей явно меняйте model; GPT Image 2.5 — это не псевдоним GPT Image 2. Актуальную доступность и тарифы аккаунта проверяйте в маркетплейсе.

Операция	Метод и эндпоинт	Формат запроса
Text-to-image	POST https://apimaster.ai/v1/images/generations	JSON
Image-to-image / редактирование	POST https://apimaster.ai/v1/images/edits	multipart/form-data с реальными файлами изображений
Асинхронное редактирование изображений	POST https://apimaster.ai/v1/images/edits/async	Те же multipart-файлы, что и для edits; возвращает ID задачи
Асинхронный text-to-image	POST https://apimaster.ai/v1/images/generations/async	JSON; возвращает ID задачи
Запрос задачи	GET https://apimaster.ai/v1/tasks/{task_id}?model=MODEL_ID	Bearer-аутентификация

Для ответа задачи при редактировании изображений используйте /images/edits/async. Загрузите те же файлы и поля, что и для синхронного edits, затем опрашивайте /tasks/{task_id}. Не переносите запрос на редактирование в generations/async. Эти эндпоинты задач используют существующий асинхронный контракт: асинхронный upstream может вернуть задачу сразу, а синхронный upstream может завершить редактирование до того, как шлюз вернёт ID задачи. Это не обещание немедленного фонового выполнения. Не используйте Chat Completions для этих моделей.

Аутентификация и таймауты

Создайте API-ключ и отправляйте Authorization: Bearer YOUR_API_KEY. JSON-запросы генерации используют Content-Type: application/json. Для загрузки файлов позвольте cURL или вашей HTTP-библиотеке сгенерировать multipart-границу; не задавайте заголовок Content-Type вручную.

Выделяйте не менее 180 секунд для базовых запросов, 300 секунд для более высокого разрешения и 600 секунд для требовательных правок или высокого качества. Таймаут клиента не доказывает, что upstream-запрос остановился. Избегайте немедленных повторных отправок.

Text-to-image: JSON-генерация

curl --fail-with-body --max-time 300 "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor orange cat sitting on a windowsill at sunset",
    "n": 1,
    "size": "1024x1024"
  }'

Для Sunburst или Flare замените идентификатор модели на gpt-image-2.5-sunburst или gpt-image-2.5-flare. Не добавляйте референсные изображения в этот пример; используйте примеры редактирования ниже.

Image-to-image: загрузка одного референса

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change only the background to pale mint green. Preserve the subject, lettering and layout of the reference image." \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "image=@reference.png;type=image/png"

Замените reference.png на существующее локальное изображение. @ указывает cURL загрузить байты файла; image=reference.png отправляет только строку с именем файла. Этот паттерн эндпоинта также применим к gpt-image-2 и gpt-image-2.5-sunburst.

Image-to-image: загрузка нескольких референсов

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Create one comic page. Reference 1 defines character A, reference 2 defines character B, and reference 3 defines the setting. Preserve each character's appearance." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

Повторяйте то же поле image[] для каждого файла в порядке, описанном в промпте. n — это количество выходных изображений, а не количество референсов. Ограничения на референсы зависят от выбранной модели и доступного маршрута; не считайте, что существует универсальный лимит в 16 изображений. Начните с одного референса и n=1, затем добавляйте входные данные по мере необходимости.

Пример редактирования на Python

Установите requests. Этот пример загружает реальный файл и обрабатывает ответы как с URL, так и с base64-изображением.

import base64
import os
from pathlib import Path
import requests

api = "https://apimaster.ai/v1"
headers = {"Authorization": "Bearer " + os.environ["APIMASTER_API_KEY"]}
with open("reference.png", "rb") as image:
    response = requests.post(
        f"{api}/images/edits",
        headers=headers,
        data={
            "model": "gpt-image-2.5-flare",
            "prompt": "Change only the background to pale mint green. Preserve the subject and lettering.",
            "n": 1,
            "size": "1024x1024",
        },
        files={"image": ("reference.png", image, "image/png")},
        timeout=(20, 600),
    )
response.raise_for_status()
item = response.json()["data"][0]
if item.get("b64_json"):
    Path("result.png").write_bytes(base64.b64decode(item["b64_json"]))
elif item.get("url"):
    print(item["url"])
else:
    raise RuntimeError("No image returned: " + str(response.json()))

Для нескольких файлов передайте список повторяющихся записей ("image[]", (filename, file_object, mime_type)) в files. Держите каждый файл открытым до завершения запроса.

Асинхронное редактирование изображений

Используйте этот эндпоинт с GPT Image 2, Sunburst или Flare, когда ваше приложение работает с ID задач. Правила загрузки файлов, порядок референсов, ограничения возможностей и аутентификация такие же, как у синхронного edits.

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Combine the three reference images into one poster, preserving their subjects and order." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

Отправка возвращает data[0].task_id. Опрашивайте, используя тот же идентификатор модели:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2.5-flare" \
  -H "Authorization: Bearer YOUR_API_KEY"

Завершённая отслеживаемая задача имеет такой вид; каждое сгенерированное изображение включено:

{
  "data": {
    "status": "succeeded",
    "result": {
      "images": [{"url": "https://your-image-host.example/result.png"}]
    }
  }
}

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

Существующие интеграции с URL или base64

Если ваш ввод — это URL, скачайте изображение в своём приложении и загрузите его байты в /images/edits. Если это base64 data URI, декодируйте полезную нагрузку в файл или байтовый буфер и загрузите его. Не отправляйте URL или base64-текст так, как если бы это была загрузка файла.

Некоторые маршруты GPT Image 2 поддерживают расширение image_urls на generations. Это не переносимый контракт редактирования изображений, и нельзя предполагать, что он будет работать с GPT Image 2.5. Новые интеграции должны использовать приведённые выше примеры multipart-редактирования. JSON-запрос, содержащий image_urls, image или images, не эквивалентен загрузке файлов в edits.

Параметры и ограничения возможностей

Поле	Использование
model	Обязательно; используйте один точный идентификатор модели из таблицы выше
prompt	Обязательно; опишите результат и порядок референсов
image / image[]	Реально загруженные файлы для edits; используйте PNG или JPEG для базовых примеров
n	Количество выходных изображений; начните с 1; максимум зависит от маршрута
size	Необязательно; 1024x1024 — базовый пример; другие пиксельные размеры или соотношения сторон зависят от маршрута
resolution	Необязательное зависящее от маршрута расширение, например 1k, 2k, 4k; не каждая модель/маршрут поддерживает каждый уровень
quality	Необязательно; допустимые значения и стоимость зависят от маршрута
background, output_format, output_compression	Необязательно; прозрачность и кодировка вывода требуют поддержки маршрута
mask	Только GPT Image 2, когда доступный маршрут edits поддерживает загруженные маски; не поддерживается текущим multipart-обработчиком GPT Image 2.5

Для GPT Image 2 поддержку масок нужно проверять отдельно от обычного редактирования по референсам. Совместимая PNG-маска должна совпадать с входными размерами и содержать альфа-канал. Текущий multipart-эндпоинт GPT Image 2.5 отклоняет загруженные файлы масок; не добавляйте маску в приведённые выше примеры Sunburst или Flare. Не предполагайте, что JSON-обходной путь с mask_url поддерживается, не проверив выбранный маршрут.

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

Синхронные ответы

Успешная генерация или правка возвращает записи изображений в data:

{
  "created": 1789890000,
  "data": [{"url": "https://your-image-host.example/result.png"}]
}

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

Асинхронные задачи: отправка и опрос

Для text-to-image отправьте JSON без референсных изображений в generations/async. Для редактирования изображений используйте приведённый выше multipart-пример edits/async. Оба используют один и тот же эндпоинт запроса задачи:

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A watercolor cat on the moon","n":1}'

{
  "code": 200,
  "data": [{"status": "submitted", "task_id": "task_EXAMPLE"}]
}

Конверт отправки обычно сообщает submitted; upstream может уже сообщить состояние завершения. Первый опрос может уже показать завершение. ID задачи не гарантирует немедленного ответа: если выбранный upstream синхронный, платформа ожидает завершения генерации, прежде чем вернуть задачу. Выдерживайте достаточный таймаут отправки.

Опрашивайте с тем же идентификатором модели, что и при отправке:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Статус задачи	Действие
pending, submitted, processing, in_progress	Ждите; опрашивайте снова через 3–5 секунд
succeeded, success, completed	Прочитайте каждую запись в data.result.images; отслеживаемые задачи используют строковый url, тогда как устаревшие upstream-ответы могут использовать массив URL
failed, error, cancelled	Прекратите опрос и изучите ошибку

Используйте конечный общий дедлайн опроса, например 10 минут. Если он истечёт, сохраните ID задачи для последующих проверок вместо того, чтобы автоматически создавать ещё одну платную задачу. Ответы запроса задачи и синхронные ответы с изображениями имеют разную структуру.

Устранение неполадок с референсными изображениями

1. Убедитесь, что фактический путь запроса — /v1/images/edits или /v1/images/edits/async, а не generations или generations/async.
2. Убедитесь, что multipart содержит байты файлов в image или повторяющихся image[], со сгенерированной границей. Текст промпта, имена файлов и количество референсов не заменяют файлы.
3. Проверьте точный идентификатор модели. Расширение GPT Image 2 автоматически не поддерживается Sunburst или Flare.
4. Если в деталях задачи/лога нет превью, не делайте вывод, что изображение не было отправлено: логи могут опускать base64-данные и содержимое загруженных файлов. И наоборот, записанное количество референсов не доказывает, что upstream использовал изображения.
5. Протестируйте с простым референсом, содержащим отличительные надписи или формы, и запросите изменение фона, не описывая эти детали. Визуально сравните результат.
6. Для обращения в поддержку сохраните ID запроса (X-Oneapi-Request-Id), ID задачи, если есть, модель, эндпоинт, время, очищенные поля запроса и референсные изображения. Никогда не передавайте свой API-ключ.

При ответе 400 проверьте совместимость эндпоинта и параметров; 401 означает сбой аутентификации; 429 означает ограничение частоты/квоты. При таймаутах или сбоях upstream сохраните ID запроса/задачи и проверьте существующую задачу или запись использования, прежде чем отправлять повторно.