API de GPT Image 2 en Python: un ejemplo completo

Para usar la API de GPT Image 2 desde Python, envía tu solicitud por POST a https://api.seedrouter.ai/v1/images/generations con la librería requests, guarda el id de tarea que devuelve, sondea /v1/tasks/{id} hasta que la tarea esté en completed y descarga las URL de imagen que incluye. El script de abajo hace los cuatro pasos en unas 40 líneas y guarda las imágenes en disco.

Funciona tal cual en cuanto defines SEEDROUTER_API_KEY. Si todavía no tienes una clave, consigue una primero.

¿Cómo es un script completo de GPT Image 2?

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}


def submit(body):
    response = requests.post(f"{API}/images/generations", headers=HEADERS, json=body, timeout=60)
    if response.status_code >= 400:
        error = response.json()["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']}")
    return response.json()["id"]


def wait(task_id, limit_seconds=600):
    deadline = time.monotonic() + limit_seconds
    while time.monotonic() < deadline:
        task = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=30).json()
        if task["status"] == "completed":
            return [image["url"] for image in task["output"]["data"]]
        if task["status"] == "failed":
            raise RuntimeError(f"{task['error']['code']}: {task['error']['message']}")
        time.sleep(3)
    raise TimeoutError(f"Still running. Resume polling task {task_id}.")


def download(urls, prefix):
    paths = []
    for index, url in enumerate(urls):
        path = f"{prefix}-{index}.png"
        with open(path, "wb") as file:
            file.write(requests.get(url, timeout=60).content)
        paths.append(path)
    return paths


task_id = submit({
    "model": "gpt-image-2",
    "prompt": "A matte ceramic vase on a sunlit table, soft shadows",
    "size": "1024x1024",
    "quality": "low",
    "n": 2,
})
print("task", task_id)
print(download(wait(task_id), "vase"))

Ejecútalo con python example.py. Primero imprime el ID de la tarea y después las rutas de dos archivos PNG, vase-0.png y vase-1.png.

¿Qué hace cada función?

submit envía la solicitud y devuelve el ID de la tarea. Una respuesta de error siempre lleva un objeto error con un code numérico y un message, así que la excepción te dice qué corregir. Un 400 con el código 20001 y el mensaje «Check the size parameter against the API documentation.», por ejemplo, significa que el tamaño incumplió una de las reglas de la guía de parámetros.

wait sondea cada tres segundos hasta que la tarea termina. Un plazo límite en tu lado detiene el bucle, no la tarea: el render sigue adelante y puedes reanudar el sondeo del mismo ID más tarde. Una tarea que termina en failed lanza una excepción con su código de error y no se cobra.

download descarga cada URL que devolvió la tarea y la escribe en disco. Las URL de resultado son un punto de entrega, no almacenamiento permanente, así que guarda lo que quieras conservar. El ejemplo usa requests tanto para las descargas como para las llamadas a la API; mantén un único cliente HTTP en todo el script en lugar de mezclarlo con urllib de la biblioteca estándar.

¿Cómo se cambian los ajustes de la imagen?

Todo está en el cuerpo de la solicitud. Los campos que la mayoría cambia primero:

Si cambias output_format, cambia también la extensión .png en download para que coincida. La lista completa de campos y límites está en la referencia de la API de GPT Image 2.

¿Cómo se edita una imagen desde Python?

Pasa las imágenes de referencia como URL en la misma llamada. No hay un endpoint de edición aparte; añadir images convierte la solicitud en una edición, y una mask limita el cambio a una región:

task_id = submit({
    "model": "gpt-image-2",
    "prompt": "Make the vase deep blue. Keep the table and the light unchanged.",
    "images": [{"image_url": "https://example.com/vase.png"}],
})

Las URL deben ser enlaces HTTPS públicos a archivos PNG, JPEG o WebP. Puedes enviar hasta 16. Los archivos locales y las cadenas base64 se rechazan, así que sube primero la imagen a tu propio almacenamiento y pasa su URL.

¿Qué debe hacer el script si el envío agota el tiempo de espera?

No vuelvas a enviar de inmediato. Que el POST agote el tiempo no demuestra que la solicitud se haya rechazado; la tarea puede estar ya en marcha y cobrada. Revisa tus tareas recientes, o reintenta la solicitud solo después de confirmar que no se creó ninguna tarea. La guía de tareas explica cómo distinguir ambos casos.

El sondeo es distinto: un tiempo agotado mientras sondeas es inofensivo. Vuelve a llamar a wait con el mismo ID.

Preguntas frecuentes

¿Puedo usar el SDK de Python de OpenAI en su lugar?

No directamente. Esta API entrega los resultados de forma asíncrona mediante un ID de tarea, mientras que la llamada de imágenes del SDK espera la imagen terminada en la respuesta. Unas pocas líneas de requests, como las de arriba, cubren todo el flujo.

¿Cómo ejecuto varios prompts?

Envía cada prompt, guarda todos los IDs de tarea y después sondéalos. La guía de generación por lotes muestra una versión que sobrevive a reinicios sin pagar dos veces.

¿gpt-image-2-official necesita un código distinto?

No. Cambia la cadena de model y nada más. Los dos IDs aceptan los mismos campos y devuelven la misma respuesta de tarea; solo cambia la facturación.

Guarda el ID de la tarea; lo demás es fontanería

Envía, guarda el ID, sondea con un plazo límite y descarga lo que vuelva. Ese patrón es toda la integración. Prueba un prompt sin código en el Playground de GPT Image 2 antes de escribir el script.