Cómo usar la API gpt-image-2.5 (Flare y Sunburst) con curl, Python y Node

OpenAI lanzó ChatGPT Images 2.5 el 8 de septiembre de 2026, con dos nuevos modelos de API: gpt-image-2.5-flare y gpt-image-2.5-sunburst. Ambos se encuentran detrás de los mismos endpoints que gpt-image-2, por lo que si siguió nuestra guía de la API de gpt-image-2, la mayor parte de su código sobrevive a un intercambio de ID de modelo. Lo que cambió es la escala de calidad y cómo la API de Respuestas le permite elegir un modelo por cada llamada a la herramienta.

Esta guía cubre solo la ruta del desarrollador: generaciones, ediciones multiparte con una imagen de referencia y una máscara, la herramienta de la API de Respuestas, streaming y la lectura del usage para el costo real. Para saber qué significa el lanzamiento para los usuarios de ChatGPT, lea nuestro resumen de ChatGPT Images 2.5; la publicación de lanzamiento de OpenAI tiene el marco del producto. Cada número a continuación proviene de la documentación de OpenAI, la página de precios o la calculadora, tal como se leyeron el 9 de septiembre de 2026.

API de gpt-image-2.5 de un vistazo

Las tarifas por token coinciden con gpt-image-2; el costo por imagen aún varía porque los recuentos de tokens por nivel de calidad cambiaron.

Requisitos previos

• Una cuenta de desarrollador de OpenAI en un nivel de uso de pago. Los endpoints de imágenes necesitan el Nivel 1 o superior, lo que significa añadir un método de pago; una suscripción a ChatGPT no cuenta. Nuestro tutorial de clave API de OpenAI cubre las claves con ámbito de proyecto.
• El SDK oficial de openai para Python o Node.
• Una forma de previsualizar las respuestas de las imágenes. curl imprime base64, lo que es molesto para la iteración; Apidog renderiza la imagen decodificada en línea, y la última sección traslada el flujo de trabajo allí.

Exporte la clave una vez:

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

Generar una imagen con curl

Use Flare primero; la página del modelo de OpenAI lo llama "la elección predeterminada para la mayoría de las aplicaciones".

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Product photo of a matte black mechanical keyboard, studio lighting, no text",
    "size": "1536x1024",
    "quality": "medium",
    "output_format": "webp",
    "background": "transparent"
  }'

La respuesta contiene un array data con un b64_json por imagen, además de un objeto usage con input_tokens y output_tokens. Conserve usage; es la única señal precisa de costo que obtiene. Notas de los parámetros de la guía de generación de imágenes: output_format por defecto es png y OpenAI dice que "usar jpeg es más rápido que png"; output_compression (0-100) se aplica solo a jpeg y webp; background: "transparent" falla en jpeg.

Python: generar y luego editar con una imagen de referencia

La llamada al SDK refleja el cuerpo de curl. Decodifique b64_json y escriba los bytes.

import base64
from openai import OpenAI

client = OpenAI()

gen = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Clean API analytics dashboard mockup, dark theme, latency chart top right",
    size="1536x1024",
    quality="high",
    output_format="png",
)
open("dashboard.png", "wb").write(base64.b64decode(gen.data[0].b64_json))
print(gen.usage.output_tokens, "output tokens")

Las ediciones son donde los modelos 2.5 demuestran su valía; la publicación de lanzamiento dice que son "mejores editando solo lo que se les ha pedido, manteniendo el resto de los detalles iguales", y OpenAI posiciona a Sunburst para un "control más estricto en las ediciones". El endpoint de ediciones es multiparte: una imagen de referencia, una máscara opcional y un prompt. Donde la máscara es transparente, el modelo repinta; en cualquier otro lugar mantiene el original.

edit = client.images.edit(
    model="gpt-image-2.5-sunburst",
    image=open("dashboard.png", "rb"),
    mask=open("chart-area-mask.png", "rb"),
    prompt="Replace the latency chart with a bar chart of error rates per endpoint; keep everything else",
    size="1536x1024",
    quality="high",
)
open("dashboard-v2.png", "wb").write(base64.b64decode(edit.data[0].b64_json))
print(edit.usage.input_tokens, "input tokens (includes the reference image)")

Omita mask y el modelo decidirá qué cambiar solo a partir del prompt. La imagen de referencia se factura como tokens de entrada de imagen a $8 por 1M; OpenAI no publica un recuento de tokens de entrada por imagen, así que lea usage.input_tokens.

Node y TypeScript: escribir b64_json en el disco

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

const client = new OpenAI();

const res = await client.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "Hero image for API docs: floating JSON cards over a teal gradient, no text",
  size: "1536x1024",
  quality: "medium",
  output_format: "jpeg",
  output_compression: 80,
});

const b64 = res.data?.[0]?.b64_json;
if (!b64) throw new Error("no image returned");
await fs.writeFile("hero.jpg", Buffer.from(b64, "base64"));

Fije gpt-image-2.5-flare-2026-09-08 en producción para mantener la salida estable mientras el alias cambia.

API de Respuestas: generación de imágenes como herramienta

Aquí un modelo principal lee su prompt, lo revisa y llama a la herramienta image_generation. Usted elige el modelo de imagen configurando model dentro de la definición de la herramienta; el model de nivel superior debe ser un modelo principal, y la documentación de herramientas de OpenAI usa gpt-6-astra. Nuestra guía de la API de Respuestas cubre la forma de la solicitud. El campo action acepta auto (por defecto), generate o edit; configure edit cuando pase una imagen de referencia y quiera que se modifique, no que se reinterprete.

import base64

with open("product.png", "rb") as f:
    ref = base64.b64encode(f.read()).decode()

first = client.responses.create(
    model="gpt-6-astra",
    input=[{"role": "user", "content": [
        {"type": "input_text", "text": "Put this bottle on a white marble surface with soft daylight"},
        {"type": "input_image", "image_url": f"data:image/png;base64,{ref}"},
    ]}],
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)
calls = [o for o in first.output if o.type == "image_generation_call"]
open("bottle-marble.png", "wb").write(base64.b64decode(calls[0].result))

second = client.responses.create(
    model="gpt-6-astra",
    previous_response_id=first.id,
    input="Same scene, but add a second bottle behind it, slightly out of focus",
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)

El seguimiento con previous_response_id mantiene la primera imagen en contexto, por lo que "misma escena" se resuelve sin volver a subir el archivo. Los tokens del modelo principal se facturan además de los tokens de imagen, y la reescritura del prompt significa que no puede reproducir la salida solo a partir del texto del prompt.

Streaming de imágenes parciales

Ambas APIs aceptan partial_images (0 a 3). Cada parcial cuesta 100 tokens de salida adicionales, por lo que tres suman 300 tokens, o $0.009 por imagen. Vale la pena para una interfaz de usuario que muestra el progreso; desperdiciado en un trabajo por lotes.

stream = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Isometric illustration of an API gateway routing requests to three services",
    size="1024x1024",
    quality="medium",
    stream=True,
    partial_images=2,
)
for event in stream:
    if event.type.endswith("partial_image"):
        open(f"gateway-partial-{event.partial_image_index}.png", "wb").write(
            base64.b64decode(event.b64_json))
    elif event.type.endswith("completed"):
        open("gateway.png", "wb").write(base64.b64decode(event.b64_json))

Las cadenas exactas de tipo de evento se encuentran en la guía de generación de imágenes; la verificación de sufijo mantiene el bucle funcionando en ambas variantes de API. Para inspeccionar eventos en streaming fuera del código, consulte nuestra guía para probar respuestas SSE de APIs de IA.

Leer el uso y convertir tokens en dólares

Advertencia de OpenAI: "Las tarifas de tokens iguales no significan un costo igual por imagen: el consumo de tokens puede diferir según el modelo y la configuración de calidad". La calculadora en la guía de generación de imágenes proporciona estas estimaciones solo para tokens de salida de imagen, a una tarifa de $30 por 1M en la página de precios:

Observe el nuevo etiquetado. high en 2.5 usa 1,756 tokens, el antiguo presupuesto medium en gpt-image-2; max usa 7,024 tokens, el antiguo presupuesto high. Mantenga quality: "high" durante una migración y cada imagen será aproximadamente 4 veces más barata con el antiguo presupuesto medio; para el antiguo presupuesto high, cambie a max. Nuestra comparación de Flare vs Sunburst vs gpt-image-2 calcula el costo mensual completo.

Los números de la calculadora son estimaciones. El costo real proviene de la respuesta:

OUTPUT_RATE = 30 / 1_000_000  # dólares por token de salida de imagen
usd = gen.usage.output_tokens * OUTPUT_RATE
print(f"{gen.usage.output_tokens} tokens = ${usd:.4f}")

Regístrelo por solicitud; según OpenAI, un tamaño no cuadrado más grande puede producir menos tokens que uno cuadrado más pequeño. Una pregunta abierta: la pestaña Batch de la página de precios solo lista gpt-image-2, por lo que el soporte de la API por lotes para 2.5 debe tratarse como no confirmado.

Errores, límites de tasa y tiempos de espera

• Límite de tasa 429. Retroceda con fluctuación (jitter) y respete Retry-After. Las páginas del modelo 2.5 no publican límites por nivel. Como referencia, gpt-image-2 funciona en el Nivel 1 a 5 imágenes por minuto y 100k TPM, escalando al Nivel 5 a 250 IPM y 8M TPM.
• insufficient_quota. Sin créditos o todavía en el nivel gratuito. Añada facturación; no reintente.
• Denegaciones de moderación. El prompt o la imagen de referencia activaron el filtro. Reformule en lugar de reintentar; moderation: "low" relaja el umbral.
• Tiempos de espera. OpenAI documenta que "los prompts complejos pueden tardar hasta 2 minutos en procesarse". Configure los tiempos de espera del cliente por encima de eso; Sunburst tarda más que Flare por diseño.

Probar Flare y Sunburst uno al lado del otro en Apidog

La iteración en terminal de los prompts de imagen es lenta porque no se puede ver la salida, y un valor quality incorrecto cuesta dinero real en cada envío. Apidog es un cliente API y una plataforma de pruebas: envía las llamadas y verifica las respuestas; los servidores de OpenAI realizan la renderización.

1. Almacene la clave una vez. Añada OPENAI_API_KEY como variable de entorno y referénciela como Bearer {{OPENAI_API_KEY}} en el encabezado de Autorización; la clave nunca se guarda en una solicitud almacenada.
2. Dos entornos, una solicitud. Cree entornos llamados flare y sunburst, cada uno con una variable MODEL, y configure "model": "{{MODEL}}" en el cuerpo. Cambie, reenvíe y compare las imágenes y el usage lado a lado. Para ediciones, use un cuerpo form-data con image y mask como campos de archivo.
3. Decodifique b64_json en un post-procesador. Un script corto extrae data[0].b64_json, lo decodifica y guarda el archivo, de modo que cada envío produce una imagen visible junto al JSON en bruto.
4. Afirme el costo, luego prográmelo. Afirme que usage.output_tokens se mantiene dentro de un presupuesto, por ejemplo, 2,000 para una renderización high de 1536x1024, y ejecute la solicitud como una prueba de regresión programada. Si alguien eleva la calidad a max o una instantánea cambia los recuentos de tokens, la prueba falla antes de que lo haga la factura.

Descargue Apidog, apúntelo a su clave de OpenAI y tendrá una biblioteca de prompts compartida con límites de costo.

Preguntas frecuentes

• ¿Necesito cambiar mi código de gpt-image-2 para usar 2.5? Cambie el ID del modelo y vuelva a verificar la quality. Los endpoints, la autenticación y la forma de la respuesta no han cambiado, pero high ahora se asigna a un presupuesto de tokens menor. La guía de la API de gpt-image-2 todavía cubre el modelo anterior.
• ¿Flare o Sunburst para la API? Comience con Flare. OpenAI lo posiciona como el predeterminado con una "latencia un 50% menor" que gpt-image-2 al mismo precio por token. Pase a Sunburst cuando la precisión de la edición sea más importante que la velocidad, como en imágenes de productos construidas a partir de fotos de referencia. Ambos comparten los mismos recuentos de tokens de la calculadora, por lo que el intercambio es tiempo, no dinero.
• ¿Puedo usar estos modelos en Chat Completions? No. La generación de imágenes reside en la API de Imágenes y en la herramienta image_generation de la API de Respuestas. Chat Completions no la expone.
• ¿Hay alguna forma gratuita de probar 2.5 a través de la API? No existe un nivel de API gratuito perpetuo, y los endpoints de imágenes necesitan el Nivel 1. La ruta real más barata es quality: "low" con 196 tokens, aproximadamente $0.006 por imagen de 1024x1024. La aplicación de consumo es otra cuestión; vea cómo usar ChatGPT Images 2.5 gratis.

A dónde ir a continuación

Comience con la llamada curl, confirme usage.output_tokens con la tabla de la calculadora, luego mueva la solicitud a un cliente donde pueda ver la imagen. La reseña de Simon Willison muestra a Sunburst manteniendo un gráfico intacto mientras añade un sujeto; pruebe ese comportamiento de edición en sus propias imágenes de referencia antes de comprometerse.