API de GPT Image 2.5 en Python: un ejemplo que funciona

Para llamar a la API de GPT Image 2.5, envía un POST a https://api.seedrouter.ai/v1/images/generations con un ID de modelo como gpt-image-2.5-flare y un prompt, guarda el id de tarea de la respuesta y sondea GET /v1/tasks/{id} hasta que el estado sea completed. La tarea terminada contiene las URL de tus imágenes. El mismo endpoint sirve para texto a imagen, ediciones con referencia y ediciones con máscara.

Esta guía es un recorrido completo y ejecutable en Python, con su equivalente en JavaScript, seguido de los errores más frecuentes y lo que significa cada uno.

¿Qué necesitas antes de la primera solicitud?

Dos cosas: una clave de API y un ID de modelo.

Crea una clave en claves de API y guárdala en una variable de entorno en tu servidor, nunca en código del navegador:

export SEEDROUTER_API_KEY="your-key"

Después elige uno de los cuatro ID de modelo de GPT Image 2.5. Cópialos tal cual; no existe un ID gpt-image-2.5 a secas.

Si no sabes con qué modelo empezar, usa Flare; Flare vs Sunburst explica cuándo merece la pena Sunburst.

¿Cómo se genera una imagen con Python?

El envío responde al instante. La respuesta es una referencia a la tarea, no la imagen.

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"]

Guarda task_id antes de hacer nada más. Es lo único que te permite acceder al trabajo que acabas de pagar, y es la forma de recuperarlo si tu proceso se reinicia mientras la imagen se renderiza.

¿Cómo obtienes la imagen?

Sondea la tarea cada pocos segundos hasta que termine. Este bucle espera hasta diez minutos; alcanzar ese límite detiene tu bucle, no la tarea.

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}.")

Descarga las URL que quieras conservar y guárdalas tú mismo. Las URL de resultado sirven para entregar el resultado, no como almacenamiento a largo plazo.

¿Cómo es la misma llamada en JavaScript?

La solicitud es idéntica; solo cambia el cliente HTTP. Ejecútala en tu servidor para que la clave nunca llegue a un navegador.

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();

Sondea GET https://api.seedrouter.ai/v1/tasks/${taskId} con la misma cabecera, exactamente igual que en el bucle de Python.

¿Cómo se edita una imagen existente?

Añade imágenes de referencia a la misma solicitud. No hay un endpoint de edición aparte ni un campo de modo: enviar images la convierte en una edición, y añadir una mask limita el cambio a una zona.

{
  "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"}
}

Las entradas deben ser URL HTTPS públicas. Puedes enviar hasta 16 imágenes de referencia en PNG, JPEG o WebP de menos de 50 MB cada una. La máscara es un PNG de menos de 4 MB, del mismo tamaño que la primera imagen de referencia, y su zona transparente marca lo que hay que cambiar. Las cadenas base64, las URL data: y las subidas de archivos se rechazan, así que sube primero los archivos a tu propio almacenamiento y envía las URL.

¿Por qué la API dice que el modelo no está disponible?

El código de error 20002 con HTTP 400 («The requested model is not available.») significa que el valor de model no es un ID que la API sirva. La causa habitual es un casi acierto: gpt-image-2.5 sin versión, gpt-image-2-5-flare con un guion en lugar del punto, o una errata en sunburst. Copia un ID de la tabla de arriba.

Los errores de parámetros se informan antes de comprobar el modelo. Si una solicitud además tiene un campo no válido, recibes 20001 con un mensaje que indica el campo, por ejemplo quality. Corrígelo primero; el error de modelo aparecerá en el siguiente intento si el ID sigue siendo incorrecto.

Una tarea también puede fallar después de haber sido aceptada. Esa consulta sigue devolviendo HTTP 200, con status: "failed" y un objeto error como el código 60001 (política de contenido) o 60002 (fallo de generación). Las tareas fallidas no se cobran. El catálogo de errores enumera todos los códigos, incluidos los de saldo y límite de frecuencia, con el siguiente paso para cada uno.

Preguntas frecuentes

¿Hay una llamada del SDK oficial de Python que devuelva la imagen directamente?

No en esta API. La entrega es asíncrona: siempre envías, guardas el ID de tarea y sondeas. stream y partial_images no están disponibles.

¿Puedo pedir varias imágenes a la vez?

Sí. Pon n entre 1 y 10. La tarea terminada incluye una URL por cada imagen entregada, y se te facturan las imágenes entregadas.

¿Cómo obtengo un PNG transparente?

Pon background en transparent y output_format en png. JPEG no tiene canal alfa, así que esa combinación se rechaza antes de ejecutarse.

Construye la integración en torno al ID de tarea

Guarda el ID de tarea en cuanto lo recibas, sondea con un límite de tiempo y trata un tiempo de espera agotado al sondear como «sigue en curso», no como «fallida». Todo lo demás, incluidos cada campo y cada límite, está en la referencia de la API de GPT Image 2.5, y puedes probar una solicitud sin código en el Playground.