Руководство по миграции GPT Image API: переход с Responses на Images API, как сохранить многораундовое редактирование изображений?

Руководство по миграции GPT Image API: переход с Responses на Images API, как сохранить многораундовое редактирование изображений?

Примечание автора: если вы уже используете image_generation в Responses через APIYI для «общения с генерацией картинок на лету», то после перехода на отдельный Images API сможете сохранить последовательное редактирование изображений по методу из этой статьи.

Сначала вывод: мигрировать нужно только часть с генерацией изображений, существующий текстовый диалог трогать не нужно. Раньше «предыдущее изображение» неявно подключалось через previous_response_id, теперь его сохраняет ваше приложение и при каждом редактировании явно выбирает, загружая как исходное изображение в POST /v1/images/edits. После этого эффект многораундового редактирования не меняется — меняется только то, кто запоминает «предыдущее изображение».

Этот вывод опирается на обновление документации, которое APIYI опубликовал 2026-11-21 в 22:30 (по пекинскому времени). Пять официально проксируемых моделей генерации изображений теперь рекомендуется использовать через два независимых эндпоинта изображений. OpenAI не отключал Responses, и текстовый диалог на сайте работает как обычно. Все интерфейсы, поля и правила тарификации ниже взяты из документации APIYI apiyi.com и официального руководства OpenAI по генерации изображений. Код — это пример из документации, а не результат реальных тестов.

gpt-image-api-migrate-responses-to-images-api-multi-turn-edit-ru-image-0


Карта знаний и индекс миграции на GPT Image API

Вся миграция выполняется в четыре шага, и результат каждого шага становится входом для следующего:

Определяем старые вызовы и распределяем по маршрутам (раздел 1)
   └─> Выход: каждый запрос должен идти в чат, generations или edits
Генерируем и сохраняем первое изображение (раздел 2.1)
   └─> Выход: проверенный v1.png + запись об активе
Передаём выбранный оригинал в интерфейс редактирования (раздел 2.2)
   └─> Выход: v2.png + связь parent_asset_id
Приёмка и сверка счетов (раздел 3)
   └─> Выход: список годных изображений + стоимость каждой принятой картинки

gpt-image-api-migrate-responses-to-images-api-multi-turn-edit-ru-image-1

Шаг От чего зависит Почему стоит здесь Цель
1 Распределение маршрутов Список вызовов в текущем коде Сначала определить, что менять, чтобы случайно не тронуть текстовый чат Переключить на Images API только запросы на генерацию изображений
2.1 Первая генерация Маршрут generations, определённый на шаге 1 Для последующего редактирования нужен реально сохранённый оригинал Получить проверенный v1 и записать в базу
2.2 Продолжаем редактирование Файл v1, сохранённый на шаге 2.1 Отдельный эндпоинт не принимает previous_response_id, только загруженную вами картинку Получить v2 и записать связь «родитель-потомок»
3 Приёмка и сверка счетов Изображения с шага 2 и логи консоли В знаменатель стоимости попадают только принятые изображения Готовые к выдаче картинки + объяснимый счёт

Рекомендуемый порядок чтения: раздел 1 обязателен; раздел 2 проходите по порядку кода; раздел 3 — перед релизом или когда возникают обрывы соединения и вопросы по счёту.

To Know: термины миграции на GPT Image API

Термин Краткое объяснение
官转 Модели официального ретрансляционного канала, которые предоставляет APIYI; в этой статье — пять ID моделей изображений
image_generation Инструмент генерации изображений в Responses API; старый пайплайн через него генерирует картинки прямо в диалоге
previous_response_id Параметр Responses для продолжения контекста предыдущего раунда; независимые запросы Images его не принимают
multipart Формат загрузки формы; /images/edits использует его для передачи двоичных данных реальных изображений
b64_json Поле, которое возвращает отдельный эндпоинт изображений; содержит изображение в кодировке base64
parent_asset_id Поле связи, которое приложение само записывает: «из какой картинки получена эта»

1 Какие вызовы GPT Image API нужно мигрировать из Responses

1.1 Обновление GPT Image API 11/21: область действия и пять моделей официального прокси

Это обновление документации касается следующих пяти ID моделей официального прокси:

  • gpt-image-2.6-sunburst
  • gpt-image-2.6-flare
  • gpt-image-2.5-sunburst
  • gpt-image-2.5-flare
  • gpt-image-2

Соответствующие два отдельных эндпоинта для изображений — это POST /v1/images/generations (тело запроса в формате JSON) и POST /v1/images/edits (multipart-форма). APIYI не рекомендует продолжать генерировать изображения через цепочку image_generation в Responses, и причин здесь две: нестабильность поставок и дополнительная плата за инструменты. Кроме того, Chat Completions не поддерживает генерацию изображений с помощью этих пяти моделей официального прокси — если в старом коде есть такое использование, его тоже нужно включить в список на миграцию.

Стоит пояснить, что это изменение затрагивает только генерацию изображений. OpenAI не отключил Responses, и текстовые диалоги на платформе APIYI тоже не отключены. Поэтому область миграции ограничивается той частью кода, «в которой в запросе вызывается инструмент изображений или модель изображений». Какую из пяти моделей выбрать — это отдельная тема, можно посмотреть статью о выборе моделей в справочном центре APIYI apiyi.com; в этой статье мы её не раскрываем.

1.2 Маршрутизация в GPT Image API: текстовый диалог, первая генерация и доработка изображения

В FAQ от APIYI предложена такая схема: диалоговая модель определяет намерение пользователя, а приложение затем отдельно вызывает Images API и само управляет изображениями. Следуя этой логике, три задачи, которые раньше выполнял один запрос к Responses, можно разложить на три маршрута:

Намерение пользователя Новый маршрут Формат запроса Источник изображения
Чисто текстовый чат, вопросы и ответы Остаётся прежний интерфейс текстового диалога Без изменений Нет
Первая генерация изображения POST /v1/images/generations JSON Только prompt
Доработка на основе готового изображения POST /v1/images/edits multipart Приложение загружает выбранный оригинал

В нативном Responses продолжение редактирования можно реализовать через previous_response_id, а можно просто передать изображение. Отдельные запросы к Images не принимают previous_response_id — именно поэтому «многораундовое редактирование» приходится брать под контроль приложению. Модель больше не помнит за вас предыдущее изображение, вам нужно передать ей файл с ним.

Если пользователь говорит «сделай чуть краснее», а в сессии уже есть несколько версий — v1, v2, v3, — приложение не может определить, какую именно он имеет в виду. В этом случае стоит сначала уточнить у пользователя, а не догадываться. По умолчанию брать последнюю версию кажется проще, но если пользователь на самом деле хотел вернуться к v2 и переделать её, вы зря спишете ещё один вызов и вдобавок запутаете человека.

Разбор ответа тоже придётся менять:

gpt-image-api-migrate-responses-to-images-api-multi-turn-edit-ru-image-2

Цепочка Где в ответе находится изображение Как поддерживается контекст
Responses + image_generation result того элемента в output, у которого type=image_generation_call previous_response_id или передача изображения
Отдельный Images API data[0].b64_json Приложение загружает уже выбранный оригинал

2 Как GPT Image API дорабатывает предыдущее изображение

Разберём полный процесс на примере двух итераций. На первой генерируем синюю кружку, на второй меняем только корпус на кирпично-красный. Параметры — как в примере из документации APIYI: модель gpt-image-2.5-sunburst, размер 1024x1024, quality=medium, output_format=png. Токен читается из переменной окружения APIYI_KEY и передаётся по схеме Bearer.

2.1 Генерируем и проверяем PNG с синей кружкой через GPT Image API

На первой итерации вызываем эндпоинт generations. Промпт описывает: светло-серый фон, по центру — синяя керамическая кружка, ручка справа, мягкий боковой свет, на изображении нет текста. После получения ответа действуем в таком порядке:

  1. Вызываем raise_for_status(), чтобы сразу отсечь ошибки на уровне HTTP.
  2. Строго декодируем b64_json из base64; если не получается — считаем это ошибкой.
  3. Открываем файл через Pillow и вызываем load(), чтобы убедиться, что он действительно декодируется в изображение.
  4. Проверяем, что формат — PNG, размер — 1024×1024, и сохраняем как v1.png.
  5. Регистрируем этот ассет в приложении — для дальнейших правок исходное изображение берём отсюда.

Шаг 3 пропускать нельзя. open() читает только заголовок файла, а целы ли данные изображения — станет ясно только после load().

2.2 GPT Image API: загружаем выбранное исходное изображение и меняем только корпус кружки на кирпично-красный

На втором раунде вызываем эндпоинт edits. В data передаём model, prompt, size, quality, output_format, а в files через поле image[] загружаем настоящие бинарные данные v1.png. Смысл промпта такой: заменить только корпус кружки на кирпично-красный, а форму кружки, ручку, композицию, освещение и фон оставить без изменений.

На этом шаге есть несколько мест, где легко ошибиться:

  • Не передавайте response_format.
  • Не пишите Content-Type вручную. requests сам сгенерирует multipart-заголовок с boundary, а ручное указание, наоборот, потеряет boundary.
  • Не загружайте base64-строку как файл — загружать нужно именно исходные байты изображения.

После правок декодируйте и проверяйте тем же способом, сохраните как v2.png. v1 нужно сохранить, а в записи об ассете указать parent_asset_id = v1. Эта связь «родитель — потомок» и есть «многораундовый контекст» в новой архитектуре. Учтите также: это генеративное редактирование, модель старается сохранить остальные области, но не гарантирует, что все пиксели за пределами корпуса кружки останутся в точности такими же.

Ниже — минимальный полный пример (пример из документации, в этой статье не тестировался):

import base64
import io
import os
import uuid

import requests
from PIL import Image

BASE_URL = "https://api.apiyi.com/v1"  # единая точка входа APIYI
API_KEY = os.environ["APIYI_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
MODEL = "gpt-image-2.5-sunburst"
SIZE = "1024x1024"
# Примерный таймаут среднего уровня; подбирайте под свою сеть и качество. Без автоповтора.
TIMEOUT = (10, 360)

assets = {}  # asset_id -> {"path": ..., "parent_asset_id": ...}


def decode_and_check(resp, path):
    resp.raise_for_status()
    item = resp.json()["data"][0]
    b64 = item.get("b64_json")
    if not b64:
        raise ValueError("no b64_json in response, check body before any resend")
    raw = base64.b64decode(b64, validate=True)
    img = Image.open(io.BytesIO(raw))
    img.load()
    if img.format != "PNG" or img.size != (1024, 1024):
        raise ValueError(f"unexpected image: {img.format} {img.size}")
    with open(path, "wb") as f:
        f.write(raw)
    return path


def save_asset(path, parent_asset_id=None):
    asset_id = str(uuid.uuid4())
    assets[asset_id] = {"path": path, "parent_asset_id": parent_asset_id}
    return asset_id


# Раунд 1: текст-в-изображение через JSON
gen_resp = requests.post(
    f"{BASE_URL}/images/generations",
    headers=HEADERS,
    json={
        "model": MODEL,
        "prompt": (
            "Light gray background, a blue ceramic mug centered, "
            "handle facing right, soft side lighting, no text."
        ),
        "size": SIZE,
        "quality": "medium",
        "output_format": "png",
    },
    timeout=TIMEOUT,
)
v1_id = save_asset(decode_and_check(gen_resp, "v1.png"))

# Раунд 2: редактируем явно выбранный оригинал через multipart
selected_id = v1_id  # если целевая версия пользователя неясна, сначала уточните
with open(assets[selected_id]["path"], "rb") as f:
    edit_resp = requests.post(
        f"{BASE_URL}/images/edits",
        headers=HEADERS,  # Content-Type вручную не задаём; requests сам ставит boundary
        data={
            "model": MODEL,
            "prompt": (
                "Change only the mug body to brick red. Keep the mug shape, "
                "handle, composition, lighting and background unchanged."
            ),
            "size": SIZE,
            "quality": "medium",
            "output_format": "png",
        },
        files={"image[]": ("v1.png", f, "image/png")},
        timeout=TIMEOUT,
    )
v2_id = save_asset(decode_and_check(edit_resp, "v2.png"), parent_asset_id=selected_id)
print(assets)

timeout=(10, 360) в примере — это лишь средняя настройка из документации; реальные значения зависят от вашего сетевого канала и выбранного уровня качества. Автоматический повтор в примере намеренно не реализован — почему, разбираем в разделе 3.2.

🚀 Быстрая проверка: подставьте в APIYI_KEY токен, созданный в консоли APIYI apiyi.com — и скрипт выше пройдёт оба раунда. Новичкам стоит сначала убедиться на бесплатном тестовом лимите, что маршрутизация и логика разбора ответа работают как надо, и только потом переключать туда рабочий трафик.

gpt-image-api-migrate-responses-to-images-api-multi-turn-edit-ru-image-3


3 Как принять результат и сверять расчёты после миграции GPT Image API

3.1 Четыре проверки при приёмке изображений GPT Image API

Изображение можно пометить в приложении как «готовое» только после того, как пройдены все четыре проверки:

  1. HTTP-успех: raise_for_status() не выбросил исключение.
  2. Декодируемость: строгое base64-декодирование прошло успешно, Pillow load() сработал.
  3. Правильные параметры: формат и размер совпадают с запросом — в этом примере PNG, 1024×1024.
  4. Визуальные изменения действительно произошли: корпус чашки в v2 действительно стал кирпично-красным, а форма чашки, ручка, композиция и фон в основном сохранились.

Четвёртая проверка требует ручного осмотра или отдельного этапа проверки, потому что по HTTP-коду статуса не видно, правильно ли модель всё изменила. Изображения, прошедшие только первые три проверки, считаются максимум «технически валидными», но ещё не готовыми к выдаче. Если в ответе вообще нет изображения, сначала стоит проверить содержимое ответа и уже потом решать, повторять ли запрос; этой теме посвящена отдельная статья в справочном центре, и здесь мы её не повторяем.

3.2 Плата за старый инструмент GPT Image API и стоимость одного принятого изображения

До и после миграции логика расчёта счетов различается:

Пункт Старая цепочка Responses image_generation Отдельный Images API
Дополнительные расходы Около $0.20 — дополнительная плата за вызов инструмента изображений APIYI Такой платы за инструмент нет
Что означает эта цифра Только эта дополнительная плата за инструмент, а не цена всего заказа и не универсальная цена OpenAI Оплата по фактическому использованию
Как корректно сравнивать По «стоимости одного принятого изображения» По «стоимости одного принятого изображения»

Не сравнивайте только цену за единицу — лучше везде использовать такую формулу:

Стоимость одного принятого изображения = соответствующие фактические списания (включая необходимые текстовые вызовы, уже списанные неудачные запросы и повторные попытки) ÷ количество принятых изображений

В числитель нужно включить все связанные списания: диалоговые вызовы для определения намерения, уже списанные неудачные запросы и повторные попытки. В знаменатель попадают только изображения, прошедшие четыре проверки из раздела 3.1. Если не прошло ни одного изображения, стоимость за штуку считать не стоит: в этом случае вывод должен быть «что-то не так в процессе», а не «цена слишком высокая». Насколько миграция экономит деньги, зависит от вашего процента повторных попыток и доли изображений, прошедших приёмку; конкретных процентов в этой статье мы не приводим.

Данные для сверки берутся из журнала потребления в консоли, а именно из записей потребления с type=2. Если вы читаете поле quota, переводите его в сумму по документации платформы через quota ÷ 500000.

К обрыву соединения нужно относиться особенно внимательно. Отдельная конечная точка изображений отвечает синхронно: если соединение оборвалось на полпути, запрос мог уже списаться, а изображение по request ID уже не найти. Правильный порядок такой: сначала в журнале потребления консоли APIYI apiyi.com проверьте, списался ли этот запрос, и только потом решайте, нужно ли отправлять его заново. Именно поэтому в примере кода нет автоматических повторных попыток: при обрыве соединения они легко приводят к повторному списанию. Если упёрлись в лимит или нужно переключить канал, посмотрите статью в справочном центре о выборе канала и резервном переключении при 429.

Критерии завершённой миграции простые: текстовый диалог работает как обычно; первая генерация стабильно возвращает v1, проходящий четыре проверки; для каждого изменения изображения в записях ассетов виден явно указанный parent_asset_id; каждое списание за изображение в журнале консоли можно сопоставить с принятым изображением, известной неудачей или задокументированной повторной отправкой. Когда все эти пункты выполняются, оставшийся трафик генерации изображений через Responses можно переключать на Images API. Если нужны сравнительные тесты нескольких моделей, APIYI apiyi.com даёт единый OpenAI-совместимый интерфейс: при смене модели достаточно изменить один параметр — MODEL.

Справочные материалы

  1. APIYI, обновление документации: официальные ретранслируемые модели изображений переведены на Images API

    • Ссылка: docs.apiyi.com/live/2026-11/gpt-image-official-relay-images-api
    • О чём: пять идентификаторов официального релея, два независимых эндпоинта и причины, по которым старая цепочка не рекомендуется
  2. APIYI FAQ: обработка текста и изображений в одном API

    • Ссылка: docs.apiyi.com/faq/text-and-image-in-one-api
    • О чём: диалоговая модель определяет намерение, а приложение отдельно вызывает Images API — комбинированный подход
  3. Руководство OpenAI по генерации изображений

    • Ссылка: developers.openai.com/api/docs/guides/image-generation
    • О чём: последовательное редактирование через Responses и структура ответа
  4. APIYI GPT Image 2: текст-в-изображение / редактирование изображений

    • Ссылка: docs.apiyi.com/api-capabilities/gpt-image-2/text-to-image
    • Ссылка: docs.apiyi.com/api-capabilities/gpt-image-2/image-edit
    • О чём: параметры запроса, multipart-загрузка и примеры проверки декодирования
  5. APIYI Responses: инструмент изображений / лучшие практики Image API / запросы к логам

    • Ссылка: docs.apiyi.com/api-capabilities/gpt-image-2/responses-image-tool
    • Ссылка: docs.apiyi.com/api-capabilities/image-api-best-practices
    • Ссылка: docs.apiyi.com/api-capabilities/log-query
    • О чём: расчёт стоимости инструмента, обработка обрыва соединения и пересчёт логов потребления

Автор: техническая команда APIYI
Техническая связь: если при миграции возникли вопросы по маршрутизации или биллингу, напишите нам через главную страницу APIYI apiyi.com; подробности по интерфейсам — в центре документации docs.apiyi.com

Читайте также

Похожие записи