GPT Image 2.5 API на Python: рабочий пример

Чтобы вызвать GPT Image 2.5 API, отправьте запрос методом POST на https://api.seedrouter.ai/v1/images/generations с ID модели, например gpt-image-2.5-flare, и промптом, сохраните id задачи из ответа и опрашивайте GET /v1/tasks/{id}, пока статус не станет completed. Завершённая задача содержит URL ваших изображений. Та же конечная точка обрабатывает генерацию по тексту, правки по референсам и правки с маской.

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

Что нужно перед первым запросом?

Две вещи: API-ключ и ID модели.

Создайте ключ на странице API-ключей и храните его в переменной окружения на своём сервере, никогда — в браузерном коде:

export SEEDROUTER_API_KEY="your-key"

Затем выберите один из четырёх ID моделей GPT Image 2.5. Копируйте их точно; голого ID gpt-image-2.5 не существует.

Если не уверены, с какой модели начать, берите Flare; когда Sunburst того стоит, объясняет статья Flare vs Sunburst.

Как сгенерировать изображение на Python?

Отправка возвращается сразу. В ответ приходит ссылка на задачу, а не изображение.

import os
import requests

response = requests.post(
    "https://api.seedrouter.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "An amber glass bottle on a cream background, studio lighting",
        "size": "1024x1024",
        "quality": "low",
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

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

Как получить изображение?

Опрашивайте задачу каждые несколько секунд, пока она не завершится. Этот цикл ждёт до десяти минут; достижение дедлайна останавливает ваш цикл, а не задачу.

import time

print(f"Task ID: {task_id}")
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

Скачайте URL, которые хотите сохранить, и храните их у себя. URL результатов — это передача результата, а не долговременное хранилище.

Как тот же вызов выглядит на JavaScript?

Запрос идентичен; меняется только HTTP-клиент. Запускайте его на своём сервере, чтобы ключ никогда не попал в браузер.

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.5-flare',
    prompt: 'An amber glass bottle on a cream background, studio lighting',
    size: '1024x1024',
    quality: 'low',
  }),
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const { id: taskId } = await response.json();

Опрашивайте GET https://api.seedrouter.ai/v1/tasks/${taskId} с тем же заголовком — точно так же, как в цикле на Python.

Как отредактировать существующее изображение?

Добавьте референсные изображения в тот же запрос. Отдельной конечной точки для правок и поля режима нет: передача images делает запрос правкой, а добавление mask ограничивает изменение одной областью.

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Make the bottle blue. Preserve the composition and lighting.",
  "images": [{"image_url": "https://example.com/reference.png"}],
  "mask": {"image_url": "https://example.com/mask.png"}
}

Входные данные должны быть публичными HTTPS URL. Можно отправить до 16 референсных изображений в PNG, JPEG или WebP размером меньше 50 МБ каждое. Маска — это PNG меньше 4 МБ того же размера, что и первое референсное изображение, а её прозрачная область отмечает, что нужно изменить. Строки base64, URL data: и загрузка файлов отклоняются, поэтому сначала загрузите файлы в своё хранилище и отправляйте URL.

Почему API сообщает, что модель недоступна?

Код ошибки 20002 с HTTP 400 («The requested model is not available.») означает, что значение model не является ID, который обслуживает API. Обычная причина — почти правильное значение: gpt-image-2.5 без версии, gpt-image-2-5-flare с дефисом вместо точки или опечатка в sunburst. Скопируйте ID из таблицы выше.

Ошибки параметров сообщаются до проверки модели. Если в запросе ещё и недопустимое поле, вы получите 20001 с сообщением, которое называет поле, например quality. Сначала исправьте его; ошибка модели появится при следующей попытке, если ID всё ещё неверен.

Задача может завершиться сбоем и после того, как её приняли. Такой запрос всё равно возвращает HTTP 200 со status: "failed" и объектом error, например с кодом 60001 (политика контента) или 60002 (генерация не удалась). Неудачные задачи не оплачиваются. В каталоге ошибок перечислены все коды, включая ошибки баланса и лимита запросов, и следующий шаг для каждого.

Часто задаваемые вопросы

Есть ли официальный вызов Python SDK, который сразу возвращает изображение?

Не в этом API. Доставка асинхронная: вы всегда отправляете запрос, сохраняете ID задачи и опрашиваете её. stream и partial_images не поддерживаются.

Можно ли запросить несколько изображений сразу?

Да. Задайте n от 1 до 10. Завершённая задача перечисляет по одному URL на каждое доставленное изображение, а оплачиваются доставленные изображения.

Как получить прозрачный PNG?

Задайте background равным transparent и output_format равным png. У JPEG нет альфа-канала, поэтому такая комбинация отклоняется ещё до запуска.

Стройте интеграцию вокруг ID задачи

Сохраняйте ID задачи в момент получения, опрашивайте с дедлайном и считайте тайм-аут опроса признаком «ещё выполняется», а не «сбой». Всё остальное, включая каждое поле и ограничение, есть в справочнике GPT Image 2.5 API, а запрос без кода можно попробовать в Playground.