Миграция API изображений в SeedRouter: запросы и задачи

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

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

Какие предположения придётся изменить?

Найдите код, который превращает запрос изображения в пригодный файл. Сейчас он может ожидать картинку в первом же ответе, декодировать поле base64 или использовать multipart-загрузку. Каждое такое предположение нужно отдельно сверить со справочником GPT Image 2 в SeedRouter.

Текущее предположение	Контракт SeedRouter	Изменение в приложении
Отправка возвращает готовое изображение	Отправка возвращает ссылку на задачу	Сохраните `id` до ожидания результата
Результат лежит в массиве `data` ответа на отправку	Изображения завершённой задачи лежат в `output.data`	Читайте результаты после завершения
Клиент декодирует `b64_json`	Изображения возвращаются ссылками на хостинг	Скачивайте возвращённые ссылки
Редактирование загружает байты файла	Референсы используют объекты ссылок в `images`	Сделайте входные изображения доступными по ссылке
Отдельный путь правок выбирает редактирование	Операцию выбирают `images` и `mask`	Используйте публичную конечную точку генерации
Таймаут на клиенте означает провал	Задача ещё может выполняться	Продолжайте опрашивать сохранённый идентификатор

Поэтому синхронный вызов SDK для изображений не является прямой заменой, даже если он принимает настраиваемый базовый адрес. Сохраните нужные настройки модели, но переделайте тот код приложения, который ждёт и обрабатывает результат.

Сопоставьте поля запроса до переноса кода

Начните с model, prompt, size, quality и n. В качестве идентификатора модели используйте gpt-image-2. Передавайте явные размеры, например 1024x1024, либо auto; не переносите отдельное поле resolution и не подставляйте строку с соотношением сторон вместо размера.

Документ OpenAPI SeedRouter удобно держать под рукой при разборе. Сравнивайте поля, которые приложение отправляет на самом деле, включая значения, подставленные SDK, а не только аргументы, видимые в месте вызова. Неизвестные поля отклоняются.

Для этой модели style, response_format и настраиваемый input_fidelity не являются допустимыми полями запроса. Уберите эти предположения, а не прячьте их внутри общего объекта опций. Запрос также не поддерживает stream и partial_images; ход работы в этой интеграции сообщает статус задачи.

У настроек вывода есть зависимости. Если запрашиваете прозрачность, выбирайте PNG. Передавайте output_compression только для JPEG, но не для PNG. Нулевое значение сжатия допустимо, поэтому избегайте проверки на «истинность», которая подменит его значением по умолчанию. Это мелочи, которые успешный базовый запрос не затронет.

Замените расчёт на синхронный ответ

Пример на Node.js ниже отправляет один запрос и печатает идентификатор задачи. Задайте SEEDROUTER_API_KEY на сервере; никогда не помещайте ключ в код браузера или в публичную переменную окружения.

const response = await fetch('https://api.seedrouter.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SEEDROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2',
    prompt: 'A cobalt-blue ceramic mug on a pale gray tabletop.',
    size: '1024x1024',
    quality: 'low',
    n: 1,
  }),
  signal: AbortSignal.timeout(60000),
});
const task = await response.json();
if (!response.ok) {
  // Preserve a task reference if one accompanies an uncertain submission.
  if (typeof task.id === 'string') console.log('Task reference:', task.id);
  throw new Error(`Submission needs review: HTTP ${response.status}`);
}
if (typeof task.id !== 'string' || !task.id) throw new Error('Missing task ID.');
console.log(task.id); // Persist this ID with your application's image record.

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

Для проверки хода работы используйте GET https://api.seedrouter.ai/v1/tasks/{id} с тем же заголовком авторизации. При completed читайте output.data[].url. При failed обработайте документированную ошибку и покажите подходящее состояние сбоя. Готовый к запуску пример с сохранением прогресса — в пакетной отправке и опросе.

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

Переведите референсы и маски на ссылки

Существующему процессу с локальными файлами нужен дополнительный шаг подготовки: разместите референс по доступной HTTP(S)-ссылке, которой вы управляете. Передайте её как images: [{"image_url": "https://example.com/reference.png"}], заменив адрес на свой. Не отправляйте путь к файлу, ссылку blob:, data URL в base64 или Files ID.

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

Маска задаётся как mask: {"image_url": "https://example.com/mask.png"} и требует референсных изображений. Её размеры должны совпадать с размерами первого референса. Перед переносом существующего процесса редактирования просмотрите все ограничения на медиавходы, особенно форматы и размеры файлов.

Что должна покрывать приёмка миграции?

Проверяйте то поведение, на которое опирается приложение, включая обрывы. Одно удачное изображение доказывает лишь то, что сработал один запрос. Оно не доказывает, что состояние ожидания переживёт перезагрузку страницы или что сбой загрузки не приведёт к повторной генерации.

Отправьте текстовый запрос и сохраните полученный идентификатор до начала опроса.
Остановите опрос, запустите его заново с тем же идентификатором и убедитесь, что нового POST не происходит.
Обрабатывайте processing, completed и failed как разные состояния.
Скачайте готовое изображение без заголовка авторизации API.
Проверьте правку по доступной ссылке, а затем обработку ошибки для недоступной.
Проверьте необязательные поля, включая нулевое сжатие, по опубликованной схеме.
Убедитесь, что списания читаются из истории расходов, а не из выдуманного поля стоимости в ответе задачи.

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

Частые вопросы

Можно ли оставить существующие промпты?

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

Нужна ли новая клиентская библиотека?

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

Где найти итоговую стоимость?

В истории расходов аккаунта. Завершённая задача может включать расход токенов, но поля стоимости в её публичном ответе нет. Оценки разобраны в руководстве по тарифам.

Доведите миграцию до границы приложения

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

Перенос интеграции изображений в SeedRouter