Cómo usar la API gpt-image-2

La API gpt-image-2 es el nuevo punto final de generación de imágenes de OpenAI, lanzado junto con ChatGPT Images 2.0 el 21 de abril de 2026. Si ya utilizas las API de chat o de incrustaciones de OpenAI, añadir la generación de imágenes requiere una única nueva forma de solicitud, una clave de API con el ámbito correcto y unos diez minutos.

Esta guía trata estrictamente sobre la API: autenticación, parámetros de solicitud, ejemplos de código en tres lenguajes, modo de pensamiento (thinking mode), generación por lotes, manejo de respuestas, códigos de error, límites de velocidad y el flujo de trabajo de pruebas que te evita quemar créditos en solicitudes fallidas. Para obtener una visión general a nivel de producto de las novedades en ChatGPT Images 2.0, consulta nuestro desglose de ChatGPT Images 2.0.

Al final, tendrás llamadas funcionales, una colección Apidog reutilizable para iterar y una imagen clara de lo que cuesta cada parámetro.

Requisitos previos

Antes de tu primera solicitud, necesitas cuatro cosas:

• Una cuenta de OpenAI con acceso a la API. Las cuentas de desarrollador son independientes de ChatGPT Plus; una suscripción a ChatGPT no incluye créditos de API.
• Un nivel de uso facturable. gpt-image-2 está disponible en el Nivel 1 y superiores. Las cuentas nuevas comienzan en el Nivel Gratuito y deben añadir un método de pago antes de que se activen los puntos finales de imagen.
• Una clave de API con el ámbito images:write. Se recomiendan las claves con ámbito de proyecto sobre las claves con ámbito de usuario para producción.
• Una herramienta de prueba que previsualice las respuestas de imagen. La terminal curl funciona para una primera solicitud; después de eso, usa un cliente de API real. Más sobre esto a continuación.

Configura la clave una vez en tu shell para que cada ejemplo de esta guía se ejecute sin ediciones:

export OPENAI_API_KEY="sk-proj-..."

Punto final y autenticación

gpt-image-2 utiliza el mismo punto final de generación de imágenes que el modelo anterior:

POST https://api.openai.com/v1/images/generations

La autenticación es un token de portador en el encabezado Authorization. Cada solicitud también lleva un cuerpo JSON con el ID del modelo, el prompt y los parámetros de salida.

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A sharp product hero image for an API testing platform, dark background",
    "size": "1024x1024",
    "n": 1,
    "quality": "high"
  }'

Si la llamada es exitosa, recibirás un objeto JSON con un array data de imágenes. Los fallos devuelven un sobre de error estándar de OpenAI con un code y un message legible; la tabla de errores más adelante en esta guía cubre los más comunes.

Parámetros de la solicitud

Cada campo en el cuerpo de la solicitud cambia lo que pagas y lo que obtienes. Aquí tienes el mapa completo de parámetros para gpt-image-2.

Los tres parámetros que más cambian el costo son size, quality y thinking. Una imagen de 2000 píxeles de ancho con calidad high y thinking: "high" puede costar entre 4 y 5 veces más que una renderización base 1024x1024 standard.

Ejemplo en Python

El SDK oficial (openai>=1.50.0) añade soporte nativo para gpt-image-2:

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

response = client.images.generate(
    model="gpt-image-2",
    prompt=(
        "A minimalist diagram of an OAuth 2.1 authorization code flow with PKCE. "
        "Five boxes labeled in English: User, Client, Auth Server, Resource Server, Token. "
        "Sharp sans-serif text, off-white background, teal accent arrows."
    ),
    size="1536x1024",
    quality="high",
    n=2,
    thinking="medium",
    response_format="b64_json",
)

out_dir = Path("out")
out_dir.mkdir(exist_ok=True)

for i, image in enumerate(response.data):
    png_bytes = base64.b64decode(image.b64_json)
    (out_dir / f"oauth_{i}.png").write_bytes(png_bytes)

print(f"Generated {len(response.data)} images into {out_dir.resolve()}")

Dos cosas a destacar:

• response.data es una lista incluso cuando n=1. Siempre itera.
• b64_json es más fácil para scripts locales; url es mejor cuando reenvías la imagen a una CDN o la subes a S3, ya que te saltas el ciclo de decodificar y luego recodificar.

Ejemplo en Node.js / TypeScript

import fs from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI();

const response = await client.images.generate({
  model: "gpt-image-2",
  prompt:
    "Dashboard UI mockup for a REST client, sentence-case labels, latency sparkline in the top-right, cool grey palette.",
  size: "1536x1024",
  quality: "high",
  n: 4,
  thinking: "medium",
  response_format: "b64_json",
});

await Promise.all(
  response.data.map(async (image, i) => {
    if (!image.b64_json) return;
    await fs.writeFile(`dash_${i}.png`, Buffer.from(image.b64_json, "base64"));
  }),
);

console.log(`Saved ${response.data.length} images`);

Usa el SDK oficial en lugar de fetch puro, a menos que tengas una razón para no hacerlo. El SDK maneja reintentos, encabezados de idempotencia y streaming, y rastrea los cambios de esquema que rompen la compatibilidad entre revisiones del modelo.

Modo de pensamiento (Thinking mode): cuándo usarlo

thinking controla cuánto cómputo dedica el modelo a planificar el diseño antes de renderizar. Cuatro valores, aproximadamente:

• off: sin razonamiento. El más rápido, el más barato, el mejor para prompts creativos sueltos donde la composición no tiene que ser exacta.
• low: planificación ligera. Un buen valor predeterminado para fotos de productos e imágenes de héroe.
• medium: planificación más pesada. La opción correcta para diagramas, infografías, diapositivas y cualquier cosa con elementos contados ("cuatro paneles", "tres flechas").
• high: razonamiento máximo. Solo vale la pena en diseños multilingües complejos o diagramas técnicos estrictos; espera una latencia y un costo notablemente mayores.

Una regla práctica: si el prompt contiene un número, una etiqueta o una restricción posicional, sube un nivel. Si solo dice "una escena acogedora", baja un nivel.

El modo de pensamiento añade tokens de razonamiento a la factura, además de los tokens de salida de imagen. La página de precios de OpenAI enumera las tarifas actuales por token; presupuesta un 1.2-2x el costo base de tu imagen cuando medium o high estén activados.

Generación por lotes

Establecer n > 1 devuelve varias imágenes en una única respuesta que comparten composición y estilo. Esto no es lo mismo que llamar al punto final n veces en paralelo; eso te daría cuatro imágenes no relacionadas. La salida por lotes es coherente, lo que coincide con la forma en que itera un equipo de diseño.

response = client.images.generate(
    model="gpt-image-2",
    prompt="Four different hero illustrations for an API documentation landing page, shared color palette, shared line weight.",
    size="1536x1024",
    quality="high",
    n=4,
    thinking="low",
)

Pagaras por imagen, así que n=4 cuesta aproximadamente 4 veces n=1. La ventaja es la consistencia, no el rendimiento.

Formato de respuesta y almacenamiento

Dos formatos, dos casos de uso:

• b64_json: la imagen está incrustada en la respuesta. Fácil para scripts. Las cargas útiles de respuesta aumentan rápidamente; un PNG de alta calidad de 2000 píxeles de ancho puede hacer que el tamaño de la respuesta supere los 3 MB.
• url: la imagen reside en la CDN de OpenAI durante una hora, y tú la descargas. Mejor para funciones sin servidor con límites de tamaño de respuesta y para pipelines que reenvían la imagen a tu propio almacenamiento.

Para producción, descarga la URL y súbela a tu propio bucket de S3, R2 o Cloudflare Images inmediatamente. No envíes URLs de OpenAI a los usuarios finales; caducan.

Manejo de errores y límites de velocidad

gpt-image-2 devuelve las formas de error estándar de OpenAI. Aquí están las que encontrarás:

Los límites de velocidad en gpt-image-2 se basan en niveles. En el Nivel 1, comienzas con aproximadamente 50 solicitudes por minuto; los niveles superiores escalan. Siempre lee los encabezados x-ratelimit-remaining-requests y x-ratelimit-remaining-tokens en cada respuesta y frena antes de alcanzar el límite.

Errores reintentables en producción:

import time
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI()

def generate_with_retry(prompt: str, tries: int = 3):
    delay = 1.0
    for attempt in range(tries):
        try:
            return client.images.generate(
                model="gpt-image-2",
                prompt=prompt,
                size="1024x1024",
                quality="high",
                n=1,
            )
        except RateLimitError:
            time.sleep(delay)
            delay *= 2
        except APIStatusError as e:
            if 500 <= e.status_code < 600 and attempt < tries - 1:
                time.sleep(delay)
                delay *= 2
                continue
            raise
    raise RuntimeError("gpt-image-2 retries exhausted")

No reintentes los errores 400, 401 o 429 por política de contenido; esos fallan por una razón y reintentar desperdicia créditos.

Probando la API con Apidog

Iterar en prompts de generación de imágenes desde una terminal es lento: no puedes ver el resultado, no puedes diferenciar los cambios de parámetros y no puedes versionar los prompts buenos. Un cliente de API diseñado específicamente resuelve los tres problemas.

Apidog trata el punto final gpt-image-2 como una solicitud de primera clase. Flujo de trabajo típico:

1. Crea una nueva solicitud en tu colección de OpenAI, método POST, URL https://api.openai.com/v1/images/generations.
2. Añade Authorization: Bearer {{OPENAI_API_KEY}} como encabezado; establece OPENAI_API_KEY en una variable de entorno para que nunca esté en el código fuente.
3. Pega el cuerpo JSON con tu prompt; Apidog valida contra la especificación OpenAPI y detecta las discrepancias de tipo antes de que envíes.
4. Haz clic en Enviar. Las respuestas de imagen se renderizan en línea; guarda las buenas, etiqueta las malas, duplica la solicitud para variantes.
5. Guarda entornos para thinking: off, thinking: medium y thinking: high para comparar el mismo prompt en diferentes niveles de razonamiento.

La función de comparación de solicitudes de Apidog es lo más importante aquí. Ajustas un parámetro; ves la imagen antes y después una al lado de la otra; confirmas el ganador en una biblioteca de prompts que todo tu equipo comparte. Este es el flujo de trabajo que la terminal no puede ofrecerte.

Si vienes de un cliente HTTP genérico o de un espacio de trabajo de Postman bloqueado, descarga Apidog y apúntalo a tu clave de OpenAI; la configuración lleva menos de cinco minutos. Los equipos que evalúan alternativas también pueden leer nuestra guía de pruebas de API sin Postman y la descripción general de la extensión de Apidog para VS Code.

Errores comunes

Un puñado de errores queman créditos y tiempo en la primera semana con gpt-image-2.

• Usar quality: "standard" para prompts con mucho texto. La calidad estándar garabatea texto pequeño. Salta a high cuando importan las etiquetas, los iconos o el texto de la interfaz de usuario.
• Exceso de prompts. 32k caracteres es el techo, no el objetivo. Después de unos cientos de tokens, el modelo comienza a ignorar las instrucciones anteriores. Mantén los prompts por debajo de 500 palabras y usa thinking para imponer restricciones complejas.
• Esperar reproducibilidad de seed. La semilla reduce la varianza pero no fija la salida. Si necesitas la misma imagen exacta, guarda los bytes en caché; no vuelvas a generar.
• Enviar URLs de OpenAI. Caducan en una hora. Siempre copia a tu propio almacenamiento antes de servir a downstream.
• Llamar al punto final en un bucle cerrado. La generación de imágenes es lenta. Paraleliza entre workers y respeta los encabezados de límite de velocidad; los bucles cerrados secuenciales solo hacen cola y agotan el tiempo de espera.

Preguntas frecuentes

¿Cómo se diferencia gpt-image-2 de gpt-image-1 a nivel de API?Mismo punto final, misma autenticación. Nuevos parámetros: thinking (off/low/medium/high), valores extra de size hasta 2000 px, y n hasta 10 con estilo compartido. Las integraciones SDK existentes siguen funcionando después de un cambio de ID de modelo; solo añades los nuevos parámetros donde ayudan. Para ver la diferencia completa, consulta la visión general de ChatGPT Images 2.0.

¿Cuál es la forma más rápida de prototipar una integración de gpt-image-2?Crea una solicitud en Apidog, guarda dos entornos (estándar vs. con pensamiento), e itera en los prompts sin tocar el código. Exporta la solicitud final como curl o código SDK cuando estés listo para confirmar.

¿La API admite la edición o el inpainting de imágenes?Los puntos finales de edición y variación siguen el mismo patrón que la generación anterior bajo el nuevo ID de modelo. Consulta la referencia del modelo gpt-image-2 para ver el esquema más reciente; los parámetros para máscaras e imágenes de entrada están documentados allí.

¿Puedo usar gpt-image-2 para resultados comerciales?Sí, bajo las políticas de uso estándar de OpenAI. Tú eres el propietario de las imágenes generadas; OpenAI conserva los derechos para usar las entradas y salidas para monitorear abusos. Los personajes con marca registrada y las figuras públicas conocidas aún activan las salvaguardias.

¿Qué hay del costo para una carga de trabajo de producción?Aproximadamente $0.21 por imagen de 1024×1024 de alta calidad en modo estándar, 10,000 imágenes al mes cuestan alrededor de $2,100 sin "thinking". Añade un 20-80% para el modo "thinking". Compara esto con alternativas autoalojadas como nuestra guía de la API GLM 5V Turbo y la integración de Qwen 3.5 Omni si el presupuesto importa más que la calidad máxima.

¿Existe una alternativa más barata con una renderización de texto similar?Todavía no con la misma calidad para texto multilingüe. Los modelos de código abierto han cerrado la brecha en la composición, pero aún se quedan atrás en los scripts CJK e índicos.