Cómo usar la API de GPT-Image-2.6

La API de GPT-Image-2.6 genera y edita imágenes mediante dos modelos de OpenAI, gpt-image-2.6-flare y gpt-image-2.6-sunburst. Envía un prompt a POST /v1/images/generations con tu clave de API y luego decodifica b64_json de la respuesta. La versión 2.6 incorpora marcado sobre imágenes, salida en SVG y GIF, y un parámetro complexity.

Prueba Apidog hoy

Esta guía abarca la autenticación, una primera generación, una edición con marcado, la exportación a SVG y la configuración de quality y complexity. Nos centramos en lo nuevo, así que consulta nuestra guía de la API de gpt-image-2.5 para streaming y la herramienta de la Responses API, y nuestro artículo explicativo sobre ChatGPT Images 2.6 para conocer todos los detalles del lanzamiento. Todas las peticiones que verás a continuación las elaboramos a partir de la documentación de OpenAI del 5 de noviembre de 2026. No las hemos ejecutado con una clave real, así que pruébalas antes de llevarlas a producción.

La API de GPT-Image-2.6 de un vistazo

Elemento	Detalle
IDs de modelo	gpt-image-2.6-flare, gpt-image-2.6-sunburst
Generación	POST /v1/images/generations
Edición	POST /v1/images/edits
Autenticación	Authorization: Bearer $OPENAI_API_KEY
Salida	b64_json; PNG por defecto, además de JPEG, WebP, GIF y SVG
quality	low, medium, high, xhigh, max, auto (por defecto)
complexity	low, medium, high (high si se omite)
Tarifas de tokens de imagen	$8 de entrada, $2 de entrada en caché, $30 de salida por 1M
Tarifas de tokens de texto	$5 de entrada, $1.25 de entrada en caché por 1M

Las tarifas provienen de la página de precios de OpenAI. Ambos modelos cuestan lo mismo por token, así que elige en función de la velocidad y la precisión de edición.

Flare o Sunburst: ¿qué modelo deberías usar?

Usa Flare para iterar rápido y para generaciones del día a día. OpenAI afirma que puede devolver una imagen en tan solo seis segundos con calidad low y que mejora la composición en pósteres e imágenes de producto. Usa Sunburst para trabajos detallados y ediciones repetidas, donde OpenAI asegura una mayor consistencia con calidad medium o high.

Estas son afirmaciones de OpenAI, no benchmarks independientes. Nuestra comparativa entre Flare y Sunburst para la versión 2.5 explica esta diferencia.

Autenticación y configuración

Necesitas tres cosas antes de tu primera llamada:

1. Crea una clave de API en el panel de OpenAI y expórtala como OPENAI_API_KEY.
2. Completa la verificación de organización de la API si tu organización lo requiere. OpenAI indica que es posible que tengas que hacerlo antes de poder usar los modelos GPT Image.
3. Instala jq para los ejemplos con curl, o el paquete openai para Python.

Si tu aplicación da servicio a usuarios individuales, envía también un safety_identifier con hash de hasta 128 caracteres. Sustituye al parámetro user, que está obsoleto.

Genera tu primera imagen

Esta petición usa Flare con calidad low, ideal para borradores.

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "prompt": "A minimal poster for a developer meetup, with the words SHIP IT in bold type",
    "size": "1024x1536",
    "quality": "low",
    "complexity": "low"
  }' | jq -er '.data[0].b64_json' | base64 --decode > poster.png

La misma llamada en Python:

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

result = client.images.generate(
    model="gpt-image-2.6-sunburst",
    [REDACTED PROMPT],
    size="1536x1024",
    quality="medium",
    extra_body={"complexity": "low"},
)

Path("mug.png").write_bytes(base64.b64decode(result.data[0].b64_json))

Pasamos complexity a través de extra_body para que la llamada no dependa de que tu versión del SDK lo exponga como argumento con nombre. Los modelos GPT Image siempre devuelven base64, así que no envíes response_format ni busques un campo url.

La guía de OpenAI recomienda leer el objeto usage de la respuesta para medir el uso de tokens. No obstante, la referencia de la API describe ese campo como exclusivo de gpt-image-1, aunque su respuesta de ejemplo lo incluya, así que confirma que aparece en tus respuestas de la 2.6 antes de basar en él tu seguimiento de costes.

Edita una imagen con marcado

El marcado le indica al modelo dónde debe hacer un cambio. Envías la imagen original, un PNG transparente con tus círculos o bocetos, y un prompt que describe la edición.

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/images/edits \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "images": [{"image_url": "https://your-bucket.example/kitchen.png"}],
    "markup": {"image_url": "https://your-bucket.example/vase-overlay.png"},
    "prompt": "Recolor the vase inside the red circle to solid cobalt blue. Keep everything else unchanged. Remove the red circle.",
    "quality": "medium",
    "complexity": "low"
  }' | jq -er '.data[0].b64_json' | base64 --decode > vase.png

Las peticiones JSON usan el array images y un objeto markup que contiene exactamente uno de estos campos: image_url o file_id. Un image_url puede ser una URL HTTPS o una URL de datos en base64. Las peticiones multipart aceptan en su lugar una carga de archivo, y la guía de generación de imágenes incluye esa versión en Python.

La superposición tiene reglas estrictas:

• Tras aplicar la orientación, debe coincidir con el ancho y el alto de la primera imagen.
• Debe contener píxeles transparentes, así que no la aplanes sobre la foto.
• Se aplica a la primera imagen de entrada. Cualquier otra actúa como referencia.
• Cada una de las dos imágenes puede tener como máximo 16.777.216 píxeles, y el archivo de superposición no puede superar los 50 MB.
• No puedes combinar markup con mask ni con prompt_rewriter.

Indícale al modelo que elimine la anotación, tal como hace el propio ejemplo de OpenAI. El marcado cuesta lo mismo que cualquier otra edición. La Responses API no lo admite, así que ahí tendrás que usar una máscara.

Exporta a SVG

Configura output_format como svg en el endpoint de generaciones para iconos, logotipos e ilustraciones que necesiten trazados editables.

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-sunburst",
    "prompt": "A flat two-color wheat logo for a bakery called Field and Flour",
    "output_format": "svg",
    "quality": "medium",
    "n": 1
  }' | jq -er '.data[0].b64_json' | base64 --decode > logo.svg

La API primero genera una imagen de referencia, que quality controla, y luego escribe el SVG a partir de ella. Los bytes decodificados son XML en UTF-8, sin scripts, recursos externos ni rásteres incrustados.

Se aplican cuatro límites:

• n debe ser 1.
• El streaming, las imágenes parciales, output_compression y prompt_rewriter no funcionan.
• El endpoint de ediciones no puede generar SVG, y no aceptará un SVG como entrada ráster.
• El objeto opcional svg elige el modelo de autoría, pero solo si tu cuenta tiene selección de modelo SVG. De lo contrario, omítelo.

Pagas dos veces: la tarifa de imagen por la imagen de referencia y la tarifa del modelo de autoría por sus tokens. La referencia de la API incluye un objeto svg_usage aparte para esa segunda parte, así que regístralo.

Genera un GIF

La API devuelve un GIF terminado, no una hoja de sprites. Añade tres campos a una petición de generaciones:

{
  "model": "gpt-image-2.6-flare",
  "prompt": "A small orange robot waves, blinks and returns to its starting pose. Make it loop.",
  "output_format": "gif",
  "frame_count": 9,
  "frame_duration_ms": 200,
  "size": "auto"
}

Decodifica b64_json de la misma forma y guárdalo como .gif. Antes, comprueba dos cosas:

• Límite de fotogramas. La guía indica que frame_count va de 2 a 64. La referencia de la API dice de 2 a 16. Quédate en 16 o menos hasta que hayas probado valores superiores.
• Acceso. La referencia indica que la salida GIF requiere acceso a la vista previa de GIF del modelo seleccionado, mientras que la guía no lo menciona. Una petición de GIF rechazada puede deberse a un problema de acceso, no a un payload incorrecto.

La salida GIF no admite streaming, imágenes parciales ni output_compression personalizado, y el endpoint de ediciones no puede devolverla. OpenAI no publica una fórmula de facturación específica para GIF, así que haz una prueba pequeña y revisa tu factura antes de escalar.

Configura quality y complexity

quality controla el nivel de detalle del renderizado e influye en el coste de tokens. complexity controla cuánto planifica el modelo antes de renderizar, y cambiarlo no conlleva ningún cargo adicional.

Configura complexity en cada petición. El valor por defecto es high, pero OpenAI recomienda low para la mayoría de las ediciones. La guía advierte de que los valores más altos pueden aumentar la latencia e introducir cambios no deseados.

La calidad también determina tu factura de salida. Esta tabla usa la calculadora de OpenAI para una imagen de 1024x1024, consultada el 5 de noviembre, y excluye los tokens de entrada:

quality	Tokens de salida	Coste de salida
low	823	$0.02469
medium	1,449	$0.04347
high	1,756	$0.05268
xhigh	3,122	$0.09366
max	7,024	$0.21072

La diferencia entre medium y high es de aproximadamente un centavo, así que compara ambos. La pestaña Batch de la página de precios aún no incluye la 2.6, así que no des por hecho que se aplica el descuento por lotes de la 2.5.

Gestiona errores y tiempos de espera

Clasifica los fallos según si un reintento puede ayudar:

Fallo	Qué hacer
Límite de tasa o error del servidor	Reintentar con retroceso exponencial
Error de cuota	No reintentar; solucionar la facturación
error.type es image_generation_user_error	Cambiar primero el prompt o la entrada
error.code es moderation_blocked	Leer moderation_details y luego revisar

Usa error.code como tu comprobación estable y registra el ID de la petición. moderation_details incluye moderation_stage y categories generales, que deben ir en tus logs, no en los mensajes dirigidos al usuario. Configura tiempos de espera del cliente superiores a dos minutos, porque OpenAI indica que los prompts complejos pueden tardar tanto.

Deja que tu agente de programación lo pruebe con Apidog CLI

Tu agente de programación puede convertir estas peticiones y límites en un conjunto de pruebas con Apidog CLI. Configúralo una vez:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

Después, dale un prompt a Claude Code, Codex o Cursor:

In Apidog project <id>, add POST /v1/images/generations and POST /v1/images/edits
on https://api.openai.com. Read the Bearer [REDACTED] from OPENAI_API_KEY.
Create test cases for gpt-image-2.6-flare at low quality and low complexity:
1. PNG generation: assert status 200 and data[0].b64_json exists.
2. SVG generation: assert status 200 and output_format equals svg.
3. GIF with frame_count 6: assert status 200 and output_format equals gif.
4. SVG with n set to 2: assert a 4xx status and that error.message exists.
5. GIF with frame_count 17: record the status, because OpenAI's docs disagree.
Put them in a test suite named "GPT-Image-2.6", run it against environment
<envId>, and summarize every failure.

El agente lee cada esquema, valida su payload y luego escribe y ejecuta el conjunto de pruebas:

apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <id> --file endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file case.json
apidog cli-schema validate test-suite-create --file suite.json
apidog test-suite create --project <id> --file suite.json
apidog test-suite run <suiteId> --project <id> -e <envId> \
  --env-var "OPENAI_API_KEY=$OPENAI_API_KEY" --on-error continue -r cli,json

El caso 5 determina el límite de fotogramas para tu cuenta, y el caso 3 muestra si tienes acceso a GIF. Los casos que se ejecutan correctamente generan imágenes reales y facturables, así que mantén la calidad baja. Cambia a -r junit para ejecutar el conjunto en un pipeline de CI, y consulta la guía de configuración de Claude Code para más detalles sobre el agente.

Preguntas frecuentes

¿Cuáles son los nombres de los modelos de la API de GPT-Image-2.6? gpt-image-2.6-flare y gpt-image-2.6-sunburst. La referencia de la API aún no incluye instantáneas con fecha para ellos, a diferencia de los modelos 2.5.

¿Cuánto cuesta la API de GPT-Image-2.6? Los tokens de imagen cuestan $8 por 1M de entrada y $30 por 1M de salida. Una imagen de 1024x1024 cuesta unos $0.025 de salida con low y unos $0.053 con high, sin contar los tokens de entrada.

¿Debería migrar desde gpt-image-2.5? Migra si necesitas SVG, GIF o complexity. Prueba antes tus costes: una imagen en low usa aproximadamente 4,2 veces los tokens que usaba en la 2.5, y los modelos 2.6 aún no tienen precios por lotes publicados.

¿Puedo usar complexity en el endpoint de ediciones? Sí. OpenAI recomienda low para la mayoría de las ediciones.

¿Puedo convertir una imagen subida en un GIF a través de la API? No. El endpoint de ediciones no devuelve GIF ni SVG, así que ambos formatos parten de un prompt de texto en el endpoint de generaciones.

¿La API devuelve una URL? No. Los modelos GPT Image siempre devuelven base64 en b64_json, así que decodifícalo y guarda el archivo tú mismo.