API de GPT Image 2: guía completa (Python, Node.js, curl)

Si quieres integrar GPT Image 2 en tu propio producto, en un pipeline de automatización o en un flujo de generación por lotes, la API es el único camino. Esta guía cubre todo lo que necesitas — autenticación, parámetros, ejemplos de código en Python y Node.js, edición de imágenes, manejo de errores y optimización de costes.

Al final tendrás una integración de GPT Image 2 funcional que aguanta tráfico real de producción.

Requisitos previos

Antes de empezar:

1. Una cuenta de developer en OpenAI (platform.openai.com)
2. Una cuenta de facturación con saldo (la generación de imágenes es de pago; las cuentas nuevas pueden recibir créditos de prueba)
3. Una API key — genera una en platform.openai.com/api-keys
4. Python 3.8+ o Node.js 18+ dependiendo del SDK que quieras usar

Acceso estable a la API para equipos de producción

Si tu equipo está en una región donde el acceso directo a OpenAI es inestable o necesitas un único relé que gestione failover, agregación de facturación y SLAs, también puedes obtener una API key gestionada de GPT Image 2 escribiendo a support@gpt-image2.art. El relé soporta el mismo nombre de modelo gpt-image-2, los mismos parámetros descritos abajo y el mismo formato de respuesta — así que tu código no tiene que cambiar.

Paso 1: Instala el SDK

Python

pip install openai pillow

pillow es opcional, solo lo necesitas si vas a hacer post-procesado de la imagen devuelta.

Node.js

npm install openai
# o
pnpm add openai

Paso 2: Configura tu API key

Nunca incrustes la API key en el código. Usa una variable de entorno.

Crea un fichero .env:

OPENAI_API_KEY=sk-proj-your-key-here

Y luego cárgalo en tu código (en Python con python-dotenv, en Node.js de forma nativa o con dotenv).

Paso 3: Genera tu primera imagen

Python — ejemplo mínimo funcional

import os
from openai import OpenAI
import base64

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

result = client.images.generate(
    model="gpt-image-2",
    prompt="A white stainless steel water bottle on a beige linen tablecloth, premium product photography, 1:1 aspect ratio.",
    size="1024x1024",
    quality="medium",
    n=1,
)

# Image is returned as base64
image_b64 = result.data[0].b64_json
with open("output.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

print("Saved to output.png")

Node.js — ejemplo mínimo funcional

import OpenAI from 'openai';
import fs from 'fs';

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const result = await client.images.generate({
  model: 'gpt-image-2',
  prompt:
    'A white stainless steel water bottle on a beige linen tablecloth, premium product photography, 1:1 aspect ratio.',
  size: '1024x1024',
  quality: 'medium',
  n: 1,
});

const imageB64 = result.data[0].b64_json;
fs.writeFileSync('output.png', Buffer.from(imageB64, 'base64'));
console.log('Saved to output.png');

curl — para scripts de shell y pruebas rápidas

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 white stainless steel water bottle on a beige linen tablecloth.",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1
  }'

Todos los parámetros, explicados

Edición de imágenes — la killer feature

La edición dirigida de GPT Image 2 es su mayor ventaja de API sobre los modelos de difusión. Subes una imagen existente y un prompt que describe qué cambiar.

Python

result = client.images.edit(
    model="gpt-image-2",
    image=open("original.png", "rb"),
    prompt="Change the bottle's color from white to navy blue. Keep everything else identical.",
    size="1024x1024",
    quality="medium",
)

with open("edited.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))

Node.js

import { toFile } from 'openai';

const result = await client.images.edit({
  model: 'gpt-image-2',
  image: await toFile(fs.createReadStream('original.png'), 'original.png'),
  prompt:
    "Change the bottle's color from white to navy blue. Keep everything else identical.",
  size: '1024x1024',
  quality: 'medium',
});

La frase "Keep everything else identical" en el prompt es crítica — sin ella, el modelo puede regenerar zonas no relacionadas.

Generación por lotes con concurrencia segura ante rate limits

No hagas un Promise.all() ingenuo con 100 peticiones — chocarás con el rate limit. Usa concurrencia acotada.

Python — usando asyncio con un semáforo

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"])

async def generate_one(prompt: str, semaphore: asyncio.Semaphore):
    async with semaphore:
        result = await client.images.generate(
            model="gpt-image-2",
            prompt=prompt,
            size="1024x1024",
            quality="medium",
        )
        return result.data[0].b64_json

async def batch_generate(prompts: list[str], concurrency: int = 5):
    semaphore = asyncio.Semaphore(concurrency)
    tasks = [generate_one(p, semaphore) for p in prompts]
    return await asyncio.gather(*tasks)

results = asyncio.run(batch_generate(["prompt 1", "prompt 2", ...]))

Node.js — usando p-limit

import pLimit from 'p-limit';

const limit = pLimit(5); // 5 concurrent requests

const tasks = prompts.map((prompt) =>
  limit(async () => {
    const result = await client.images.generate({
      model: 'gpt-image-2',
      prompt,
      size: '1024x1024',
      quality: 'medium',
    });
    return result.data[0].b64_json;
  })
);

const results = await Promise.all(tasks);

Manejo de errores para producción

La API puede fallar de varias formas distintas. Gestiona cada una:

from openai import OpenAI, APIError, RateLimitError, APIConnectionError, BadRequestError

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

def safe_generate(prompt: str, max_retries: int = 3):
    for attempt in range(max_retries):
        try:
            result = client.images.generate(
                model="gpt-image-2",
                prompt=prompt,
                size="1024x1024",
                quality="medium",
            )
            return result.data[0].b64_json

        except RateLimitError:
            # 429 — wait and retry
            wait = (2 ** attempt) * 5
            print(f"Rate limited; waiting {wait}s")
            time.sleep(wait)

        except BadRequestError as e:
            # 400 — usually a content policy violation, don't retry
            print(f"Bad request: {e}")
            return None

        except APIConnectionError:
            # network blip — retry
            time.sleep(2 ** attempt)

        except APIError as e:
            # 500-level — retry with backoff
            time.sleep(2 ** attempt)

    return None

Optimización de coste — tácticas concretas

1. Elige el tier de calidad adecuado

La mayoría de equipos paga de más porque tira de high por defecto. Usa medium para el ~95% del trabajo.

2. Itera con images.edit, no con images.generate

Una edición dirigida cuesta lo mismo que una generación, pero acierta a la primera en vez de en cinco intentos. En refinamiento multi-ronda, eso son 5× de ahorro.

3. Cachea de forma determinista cuando los prompts se repiten

Si generas el mismo prompt una y otra vez (p. ej., previsualizaciones de producto para usuarios), cachea por hash(prompt + size + quality) y sirve desde tu CDN.

4. Usa low para explorar prompts y luego sube de tier

Flujo habitual:

# Paso 1: prueba 5 variantes de prompt en low ($0,05 en total)
candidates = [generate(p, quality="low") for p in variants]

# Paso 2: elige la mejor y regenera en high
best_prompt = pick_winner(candidates)
final = generate(best_prompt, quality="high")  # $0,167

Coste total: ~0,22 $ en lugar de ~0,84 $ si hubieras corrido las 5 variantes en high.

5. Pon límites duros de gasto en el panel de OpenAI

No confíes en que tu código nunca tendrá un bug — fija un tope de uso en platform.openai.com/account/billing/limits.

Estado de la generación en streaming (opcional)

Para lotes largos puede que quieras mostrar progreso. El endpoint de generación de imágenes no es en streaming, pero puedes envolver tu lote en un reporter async de progreso:

let completed = 0;
const tasks = prompts.map((prompt) =>
  limit(async () => {
    const result = await client.images.generate({ /* ... */ });
    completed++;
    onProgress({ completed, total: prompts.length });
    return result.data[0].b64_json;
  })
);

Errores comunes de integración

Checklist listo para producción

Antes de desplegar una integración de GPT Image 2:

• API key en variable de entorno, nunca en código ni logs
• Tier de calidad adecuado al caso (por defecto medium)
• Concurrencia acotada (p-limit / Semaphore) para jobs por lotes
• El manejo de errores distingue 4xx vs 5xx
• Tope de gasto fijado en el panel de OpenAI
• Input del usuario saneado contra violaciones de la política de contenidos
• La salida se guarda en tu propio almacenamiento (sin depender de URLs de OpenAI)
• Capa de caché para prompts repetidos
• Monitoreo de coste por imagen y de tasa de error

Generación asíncrona con polling de tareas (para configuraciones de alta concurrencia)

Para cargas de producción de mucho volumen, algunos relés de GPT Image 2 ofrecen un modelo de tarea asíncrona: envías la petición, recibes un task ID al instante y luego haces polling o recibes un callback. Esto evita timeouts HTTP en lotes grandes.

Flujo asíncrono típico:

# 1. Envía la petición → obtienes task_id
response = client.images.generate(
    model="gpt-image-2",
    prompt="...",
    size="1024x1024",
    quality="high",
    callback_url="https://your-app.com/api/image-callback",  # optional
)
task_id = response.id

# 2. Hace polling del estado de la tarea cada pocos segundos
while True:
    status = client.images.retrieve(task_id)
    if status.status == "completed":
        image_url = status.data[0].url
        break
    elif status.status == "failed":
        raise Exception(status.error)
    time.sleep(3)

El modo asíncrono es ideal para:

• Tiendas de e-commerce que generan cientos de variantes de producto durante la noche
• Equipos de marketing haciendo tests A/B de prompts
• Apps donde los usuarios piden imágenes y vuelven a consultarlas más tarde (notificaciones)

FAQ de la API de GPT Image 2

P: ¿Cuál es el nombre del modelo en la API de GPT Image 2? gpt-image-2. Usa exactamente esta cadena en todas las peticiones.

P: ¿La API de GPT Image 2 soporta image-to-image / edición de imágenes? Sí. Usa images.edit con el parámetro image, o pasa image_urls (array de 1-16 imágenes de referencia) en los relés que lo soporten. Las imágenes de referencia son esenciales para consistencia de personaje, diseño de IP y fotografía de producto.

P: ¿La API de GPT Image 2 es gratis? No, se paga por token. Las cuentas nuevas de OpenAI pueden recibir créditos de prueba. Algunos relés de terceros ofrecen créditos de prueba gratuitos.

P: ¿Cuánto cuesta la API de GPT Image 2 por imagen? Aproximadamente 0,011 $ / 0,042 $ / 0,167 $ por imagen 1024×1024 en calidad low / medium / high respectivamente. Tamaños mayores e imágenes de referencia cuestan más.

P: ¿Cuál es la longitud máxima del prompt? Hasta 32.000 caracteres. En la práctica, los prompts por encima de ~1.500 caracteres muestran rendimientos decrecientes.

P: ¿Cómo genero PNGs de fondo transparente con la API? Establece background: "transparent" y output_format: "png".

P: ¿Qué resoluciones soporta GPT Image 2? Presets habituales: 1024x1024, 1536x1024, 1024x1536. Algunos relés exponen niveles 1K / 2K / 4K para control explícito.

P: ¿Cuál es el rate limit? Depende de tu tier de OpenAI. El tier gratuito tiene los límites más estrictos; el tier de uso escala con el tiempo. Usa concurrencia acotada (p-limit / Semaphore) para mantenerte por debajo del límite.

P: ¿Cómo gestiono los errores de la API de GPT Image 2? Distingue 4xx (no reintentar — suele ser violación de política de contenidos) de 5xx (reintentar con backoff exponencial). Mira la sección de manejo de errores de arriba.

P: ¿Puedo cancelar una petición en curso en la API de GPT Image 2? En peticiones síncronas, solo cerrando la conexión. Los relés con soporte asíncrono exponen un endpoint cancel que funciona mientras la tarea siga en cola.

P: ¿La API soporta streaming? La propia generación de imágenes no se hace en streaming (recibes la imagen completa al final). Para mostrar progreso, envuelve tu lote en un reporter de progreso propio (ver "Estado de la generación en streaming" más arriba).

¿Quieres una app de ejemplo funcionando?

Para una implementación de referencia completa — Next.js + GPT Image 2 + Stripe + almacenamiento de imágenes — explora gpt-image2.art y la página explore con salidas reales.

¿Necesitas una API key gestionada con SLA?

Si prefieres saltarte la configuración de cuenta, la facturación, los problemas regionales y el ajuste del rate limit, puedes comprar una API key gestionada de GPT Image 2 escribiendo a support@gpt-image2.art. Te damos:

• Un endpoint de API estable con failover incorporado
• Facturación agregada en tu moneda local (sin transferencia en USD)
• Modo de tarea asíncrono + soporte de callback de serie
• Precios por volumen para equipos que generan más de 10.000 imágenes/mes
• Mismo nombre de modelo gpt-image-2 y misma especificación de parámetros que la API oficial — compatible drop-in

Lecturas recomendadas

• Guía de redacción de prompts para GPT Image 2 — 7 reglas que llevan la tasa de acierto del 30% al 90%
• Biblioteca de estilos de GPT Image 2 — 12 prompts artísticos listos para producción
• ¿Qué es GPT Image 2? Introducción completa