GPT Image 2.5

GPT Image 2.5 acepta un prompt de texto y, opcionalmente, imágenes de referencia. Envía una vez, conserva el identificador de tarea devuelto y consulta esa tarea para obtener las imágenes terminadas. Se ofrece como dos modelos que leen los mismos parámetros: Flare para el trabajo del día a día y Sunburst cuando la precisión en las ediciones es lo más importante.

ID de modelo

Los cuatro ID aceptan los mismos parámetros. Los canales se diferencian en la facturación; consulta la página del modelo para ver los precios actuales.

Ejemplo rápido

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "An amber glass bottle on a cream background, studio lighting",
    "size": "1024x1024",
    "quality": "low"
  }'

Endpoint

POST https://api.seedrouter.ai/v1/images/generations

El mismo endpoint gestiona la generación, las ediciones con referencia y las ediciones con máscara. La respuesta contiene un identificador de tarea, no la imagen terminada. Mantén las claves API en código del servidor.

Parámetros

Reglas de tamaño

Las opciones habituales son 1024x1024, 1536x1024 y 1024x1536. Las dimensiones personalizadas deben cumplir todas las reglas:

• El ancho y el alto son múltiplos de 16.
• Ningún lado supera los 3840 píxeles.
• La relación de aspecto está entre 1:3 y 3:1.
• El área total está entre 655.360 y 8.294.400 píxeles, ambos inclusive.

auto deja las dimensiones de salida en manos del modelo. No envíes relaciones de aspecto como 16:9 en size.

El Playground ofrece los controles Auto, Proporción y Personalizado. El modo Proporción combina una relación de aspecto con un preajuste de presupuesto de píxeles de 1K, 2K o 4K, y luego envía solo el size resultante. Son preajustes de interfaz, no parámetros de API independientes: no envíes resolution ni aspect_ratio. Por ejemplo, 16:9 + 4K envía size: "3840x2160"; 9:16 + 4K envía "2160x3840"; 1:1 + 2K envía "2048x2048". El redondeo y el límite de lado pueden reducir el número de píxeles de un nivel elegido. Las dimensiones exactas se muestran antes de enviar.

OpenAI describe como experimentales las resoluciones superiores a 2560×1440. Se aceptan dentro de los límites anteriores; una resolución mayor no garantiza mejor detalle.

Niveles de calidad

xhigh y max son nuevos en GPT Image 2.5; GPT Image 2 llega hasta high. Los niveles superiores tardan más en renderizar y, en los ID facturados por tokens, consumen más tokens de salida. Medido a 1024x1024, un renderizado informó 196, 439, 1.756, 3.122 y 7.024 tokens de salida para low, medium, high, xhigh y max. Son muestras observadas, no garantías: el uso también depende del tamaño y del contenido.

Usa low para borradores y compara los resultados antes de elegir un nivel superior. auto deja que el modelo elija; no garantiza un nivel ni un coste concretos.

Fondos transparentes

GPT Image 2.5 admite transparencia. Para un fondo transparente, define background: "transparent" y usa PNG. JPEG no admite transparencia. La compresión solo se aplica a JPEG.

user está disponible para integraciones de API, pero no se muestra ni se rellena automáticamente en el Playground.

Los ajustes escalares opcionales (n, size, quality, background, output_format, output_compression, moderation) aceptan null como omisión. Los campos desconocidos se rechazan. input_fidelity no es un parámetro de GPT Image 2.5. style y response_format pertenecen a otros modelos de imagen y aquí no se aceptan.

Modos

No hay un parámetro de modo aparte ni un endpoint de edición que elegir.

Editar imágenes de referencia

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "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"},
    "output_format": "jpeg",
    "output_compression": 90
  }'

Sustituye las dos URL de ejemplo por imágenes propias accesibles. Omite mask para una edición con referencia sin región seleccionada.

Entradas multimedia

Esta API solo acepta referencias por URL. No se aceptan identificadores de OpenAI Files, data URL en base64 ni subidas multipart. El Playground sube los archivos seleccionados al almacenamiento antes de enviar sus URL.

Las imágenes de referencia deben ser URL HTTP(S) públicas que apunten a archivos PNG, JPEG o WebP de menos de 50 MB cada uno. Una máscara debe ser un PNG de menos de 4 MB, con las mismas dimensiones que la primera imagen de referencia; su zona transparente marca qué se edita. La máscara guía al modelo y no garantiza bordes exactos al píxel. Con varias referencias, la máscara se aplica a la primera imagen. Los medios por URL se validan durante el procesamiento; un medio inválido o inaccesible puede hacer que la tarea falle.

El Playground sube los archivos seleccionados y envía sus URL. Las solicitudes de la API usan objetos URL en JSON: no envíes bytes de archivo, base64, URL data:, URL blob: ni datos de formulario multipart.

Factores de coste

Consulta la sección de precios del modelo para ver las tarifas actuales. Los ID Standard cobran un precio fijo por imagen entregada, sin importar la calidad, el tamaño ni el prompt. En los ID Official, el coste final depende del consumo de entrada y salida: la calidad, las dimensiones de salida, las imágenes de referencia, la longitud del prompt y el número de imágenes pueden influir en él.

La estimación del Playground se basa en una muestra medida y en las tarifas actuales; no es un presupuesto garantizado. Consulta los cargos definitivos en el historial de uso de tu cuenta. Las tareas fallidas no se cobran.

Esquema de salida

El envío devuelve una referencia de tarea:

{
  "id": "task_...",
  "model": "gpt-image-2.5-flare",
  "status": "processing",
  "created_at": 1789970508
}

Sondear la tarea

curl https://api.seedrouter.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

Sondea a un ritmo moderado, por ejemplo cada tres segundos, hasta que status sea completed o failed. Que se agote el tiempo de red durante el sondeo no significa que la generación haya fallado: conserva el identificador de tarea y reanuda la comprobación. No crees otra tarea para consultar el progreso.

Ejemplo completo de sondeo

Ejecuta esto después del ejemplo de envío en Python anterior. Usa el task_id devuelto y espera hasta diez minutos. Alcanzar este plazo local solo detiene el sondeo; conserva el identificador y reanuda la consulta de la misma 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}.")

Tarea completada

Una tarea completada devuelve las URL de las imágenes alojadas y el uso:

{
  "id": "task_...",
  "model": "gpt-image-2.5-flare",
  "status": "completed",
  "created_at": 1789970508,
  "finished_at": 1789970538,
  "output": {
    "created": 1789970532,
    "data": [{"url": "https://static.seedrouter.ai/media/tasks/task_example/0.png"}],
    "usage": {
      "input_tokens": 29,
      "output_tokens": 196,
      "total_tokens": 225
    }
  }
}

Esta API entrega los resultados de forma asíncrona mediante tareas. No sustituye a un SDK de Images síncrono; stream y partial_images no son compatibles.

Errores

Las solicitudes rechazadas antes de crear una tarea devuelven un error HTTP con un objeto error. Una tarea que falla tras ser aceptada devuelve HTTP 200 al consultarla, con status: "failed" y un objeto error.

Consulta el catálogo de errores común para ver códigos, estados HTTP y pautas de reintento. Todas las API de modelos usan la misma envoltura de error.

{
  "id": "task_...",
  "status": "failed",
  "error": {
    "code": 60002,
    "message": "Generation could not be completed. Please try again."
  }
}

Si el propio envío agota el tiempo de espera, revisa tu historial de tareas antes de volver a enviarlo: puede que la primera solicitud ya se haya aceptado.

Consejos

• Describe materiales, composición e iluminación en el prompt.
• En una edición, indica tanto el cambio como lo que debe permanecer igual.
• Usa una máscara cuando solo deba cambiar una zona seleccionada.
• Guarda las imágenes devueltas en tu propio almacenamiento si necesitas una copia duradera.

Relacionado

• Playground y precios de GPT Image 2.5
• Descargar OpenAPI
• Markdown copiable