Cómo usar la API gpt-image-2

La API gpt-image-2 es el nuevo endpoint de generación de imágenes de OpenAI, lanzado junto con ChatGPT Images 2.0 el 21 de abril de 2026. Si ya usas las APIs de chat o de embeddings de OpenAI, agregar generación de imágenes solo requiere una solicitud diferente, una clave de API con el scope adecuado y unos diez minutos de implementación.

Prueba Apidog hoy

Esta guía es totalmente práctica: cubre autenticación, parámetros de solicitud, ejemplos de código en Python y TypeScript, el modo de pensamiento, generación por lotes, manejo de errores, límites de velocidad y un flujo de trabajo de pruebas eficiente para ahorrar créditos. Si buscas el resumen a nivel producto de las novedades de ChatGPT Images 2.0, revisa nuestro desglose de ChatGPT Images 2.0.

Al final, tendrás llamadas funcionales, una colección Apidog reutilizable y claridad sobre el impacto de cada parámetro en el costo.

Requisitos previos

Antes de tu primera solicitud, necesitas:

• Cuenta de OpenAI con acceso a la API (no basta ChatGPT Plus; la API es independiente).
• Nivel facturable (Nivel 1 o superior). Las cuentas nuevas deben agregar método de pago para activar endpoints de imagen.
• Clave de API con scope images:write. En producción, usa claves de proyecto.
• Herramienta de pruebas que permita previsualizar respuestas de imagen. curl sirve para la primera prueba, pero luego usa un cliente de API real.

Configura la clave en tu shell para ejecutar los ejemplos sin modificaciones:

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

Punto final y autenticación

El endpoint para gpt-image-2 es:

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

Autenticación vía bearer token en el header Authorization. El body es JSON con el modelo, prompt y parámetros de salida. Ejemplo:

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

La respuesta exitosa incluye un array data con las imágenes. Los errores devuelven un objeto estándar de OpenAI con code y message. Consulta la tabla de errores más abajo.

Parámetros de la solicitud

Los parámetros del cuerpo determinan costo y resultado. Mapa completo para gpt-image-2:

Parámetro	Tipo	Valores	Notas
model	string	gpt-image-2	Obligatorio.
prompt	string	Hasta 32.000 caracteres	Obligatorio. Prompts largos consumen más tokens.
size	string	1024x1024, 1024x1536, 1536x1024, 2000x1000, 1000x2000, 2000x667, 667x2000	Define los tokens de salida.
quality	string	standard, high	high cuesta el doble; útil para texto/UI.
n	integer	1–10	Batch: comparte estilo entre imágenes.
thinking	string	off, low, medium, high	Presupuesto de razonamiento previo.
response_format	string	url, b64_json	Las URL expiran en 1h.
user	string	Libre	Para detección de abuso; pasa un hash de usuario.
background	string	auto, transparent, opaque	Transparente = PNG con alfa.
seed	integer	Cualquier int32	La misma semilla + prompt ≈ similar, no idéntico.

Los parámetros que más afectan al costo son size, quality y thinking. Por ejemplo, una imagen de 2000px de ancho, quality: "high" y thinking: "high" puede costar 4-5 veces más que 1024x1024 estándar.

Ejemplo en Python

El SDK oficial (openai>=1.50.0) soporta 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()}")

• response.data siempre es lista, aunque n=1. Itera por seguridad.
• b64_json es ideal para scripts locales; url si necesitas enviar la imagen a una CDN/S3.

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

Recomendado: usa el SDK oficial en vez de fetch puro, para manejar reintentos, headers idempotentes y cambios de esquema.

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

thinking ajusta el razonamiento antes de renderizar:

• off: sin razonamiento, más rápido y barato. Útil para prompts creativos generales.
• low: planificación ligera. Bien para imágenes de producto o hero.
• medium: planificación más profunda. Elige para diagramas, infografías, slides o elementos contados.
• high: razonamiento máximo, útil solo para layouts multilingües complejos o diagramas técnicos estrictos. Mayor latencia y costo.

Regla práctica: si el prompt menciona números, etiquetas o posiciones, sube el nivel. Si es una escena genérica, bájalo.

El modo de pensamiento suma tokens de razonamiento (costo adicional). Consulta precios actuales; calcula 1.2x–2x sobre el costo base si usas medium o high.

Generación por lotes

Con n > 1 obtienes imágenes múltiples, con composición y estilo consistente (no igual a hacer n requests en paralelo).

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",
)

Paga por imagen (n=4 cuesta x4 respecto a n=1). La ventaja principal es la consistencia.

Formato de respuesta y almacenamiento

• b64_json: imagen embebida en la respuesta. Práctico para scripts, pero la respuesta puede ser pesada (>3MB para PNG de alta calidad).
• url: imagen servida vía CDN de OpenAI (expira en 1h). Útil en pipelines o funciones serverless.

En producción: descarga la imagen y súbela a tu bucket (S3, R2, Cloudflare, etc). No entregues URLs de OpenAI a usuarios finales.

Manejo de errores y límites de velocidad

gpt-image-2 devuelve errores estándar de OpenAI:

HTTP	code	Causa	Solución
400	invalid_request_error	Tamaño incorrecto, relación no soportada, prompt > 32k caracteres	Verifica tamaños y recorta prompt.
401	invalid_api_key	Clave faltante o inválida	Reexporta OPENAI_API_KEY.
403	insufficient_quota	Sin créditos o cuenta gratuita	Agrega facturación/verifica nivel.
429	rate_limit_exceeded	Demasiadas solicitudes/minuto	Haz backoff con jitter; respeta Retry-After.
429	image_generation_user_error	Rechazo por política de contenido	Reformula el prompt.
500	server_error	Error transitorio de OpenAI	Reintenta dos veces con backoff exponencial.
503	overloaded	Pico de carga regional	Espera y reintenta.

Límites de velocidad: desde 50 requests/minuto en Nivel 1 (escalan con niveles superiores). Lee x-ratelimit-remaining-requests y x-ratelimit-remaining-tokens en cada respuesta y frena antes de llegar al límite.

Ejemplo de reintentos en Python:

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 errores 400, 401 o 429 por política de contenido; solo reintenta errores transitorios.

Probando la API con Apidog

Iterar prompts desde terminal es lento y poco visual. Un cliente de API especializado como Apidog resuelve esto.

Apidog trata gpt-image-2 como endpoint de primera clase. Flujo recomendado:

1. Crea una solicitud POST en tu colección de OpenAI (https://api.openai.com/v1/images/generations).
2. Agrega Authorization: Bearer {{OPENAI_API_KEY}} como header; usa variables de entorno.
3. Pega el body JSON; Apidog valida tipos y detecta errores antes de enviar.
4. Haz clic en Enviar: la imagen se renderiza inline. Guarda las buenas, etiqueta las malas, duplica para variantes.
5. Guarda entornos de thinking: off, medium y high para comparar el mismo prompt.

La función de comparación de solicitudes de Apidog permite ver imágenes antes/después y elegir la mejor para tu equipo. Este workflow supera por mucho al uso de terminal.

Si usas Postman o clientes HTTP genéricos, descarga Apidog y configura tu clave OpenAI en menos de 5 minutos. También puedes leer nuestra guía de pruebas de API sin Postman y la descripción de la extensión de Apidog para VS Code.

Errores comunes

• Usar quality: "standard" con mucho texto. La calidad estándar distorsiona texto pequeño. Usa high para etiquetas o UI.
• Prompts demasiado largos. 32k es el límite, no el objetivo. Mantén prompts por debajo de 500 palabras y usa thinking para restricciones complejas.
• Esperar reproducibilidad de seed. La seed solo reduce la varianza. Si necesitas la misma imagen, guarda los bytes.
• Entregar URLs de OpenAI. Expiran en 1h. Descarga siempre antes de servir a downstream.
• Loop cerrado sobre el endpoint. La generación es lenta. Paraleliza, respeta límites y evita bucles cerrados secuenciales.

Preguntas frecuentes

¿Qué cambia entre gpt-image-2 y gpt-image-1? Mismo endpoint y autenticación. Nuevos parámetros (thinking, size hasta 2000px, n hasta 10). Integra los nuevos parámetros en SDK según necesidad. Consulta la visión general de ChatGPT Images 2.0.

¿Prototipar integración rápido? Crea una solicitud en Apidog, guarda dos entornos (estándar vs. thinking), itera en el prompt sin código, exporta a curl o SDK cuando esté listo.

¿Soporta edición o inpainting? Los endpoints de edición/variación siguen el mismo patrón bajo el nuevo ID. Revisa la referencia de modelo para parámetros de máscaras o imagen de entrada.

¿Uso comercial? Sí, bajo políticas estándar de OpenAI. Eres dueño de las imágenes generadas, OpenAI monitorea abusos. Personajes de marca y figuras públicas activan salvaguardas.

¿Costos en producción? ~$0.21 por imagen 1024×1024 de alta calidad modo estándar; 10,000 imágenes/mes ≈ $2,100 sin "thinking". Suma 20-80% si usas "thinking". Compara con opciones autoalojadas: GLM 5V Turbo o Qwen 3.5 Omni si el presupuesto es crítico.

¿Alternativas más baratas con texto similar? Aún no con la misma calidad multilingüe. Open source ha mejorado en composición, pero sigue por detrás en scripts CJK e índicos.