OpenAI Image Generation API Endpoint: cuál debes usar

Si hoy estás integrando generación de imágenes con OpenAI, el default más seguro sigue siendo la Images API directa, no Responses. Usa POST /v1/images/generations para generar una imagen desde un prompt, usa POST /v1/images/edits cuando ya tienes imágenes de entrada y solo cambia a Responses con image_generation cuando la salida de imagen sea una parte de un workflow multimodal o agentic más grande.

Esa distinción importa porque la documentación actual de OpenAI sigue repartiendo la respuesta entre varias superficies. El image generation guide explica la división entre Images API y Responses API. El Images API reference da los paths crudos. El tool guide de image_generation aclara cómo funciona la generación de imágenes dentro de Responses. Y la página Images and vision, revisada el 23 de marzo de 2026, todavía dice que el latest image generation model es gpt-image-1, algo que no encaja con el catálogo actual.

Por eso este keyword no se resuelve bien con una sola URL. Lo que de verdad necesita el lector es una regla de decisión: qué superficie debería usar primero para el trabajo que está haciendo ahora. Si solo quieres demostrar que una llamada de imagen funciona, empieza por la Images API directa. Si más tarde necesitas meter la generación de imágenes dentro de una conversación, otras tools y un modelo de razonamiento, entonces sí merece la pena pasar a Responses.

El mapa actual de endpoints de OpenAI en una sola tabla

La forma más clara de entender la pila actual de imágenes de OpenAI es separar trabajo de imagen directo de orquestación multimodal basada en tools.

Esta tabla es la respuesta más honesta porque sigue exactamente cómo OpenAI documenta hoy la plataforma. El image generation guide dice que hay dos rutas principales y empuja el caso de una sola imagen hacia la Image API. El tool guide cubre la situación contraria: cuando la generación de imagen está incrustada en un flujo de razonamiento más grande.

La regla operativa es simple: si no tienes una razón real para complicarlo, empieza con la Images API directa. Eso hace que la primera petición sea más fácil de documentar, de reproducir y de depurar.

Si todavía estás eligiendo el model ID correcto, compáralo antes en la guía local de OpenAI image generation API models. Esta página es deliberadamente más estrecha: aquí lo importante es no empezar por la superficie equivocada.

Para generación directa, empieza con POST /v1/images/generations

Para la mayoría de integraciones nuevas, este endpoint es la mejor primera prueba. El actual Images API reference enumera POST /images/generations como el endpoint crudo de generación, lo que en la práctica significa llamar a https://api.openai.com/v1/images/generations desde tu backend. Y para la elección del modelo actual, la referencia más segura es la página de GPT Image 1.5, porque la trata como la línea actual de imagen.

La primera llamada debería ser aburrida a propósito: un prompt, una imagen cuadrada y el modelo actual. Eso te dice si de verdad funcionan la API key, el proyecto, el acceso al modelo y la forma del payload. Es una mejor secuencia que intentar resolver generación, edición, transparencia, tool orchestration y access issues en el mismo primer experimento.

Ejemplo mínimo con cURL:

bash
curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1.5",
    "prompt": "Create a clean editorial illustration of a robot camera operator in a bright studio",
    "size": "1024x1024",
    "quality": "medium"
  }'

Y la versión corta en JavaScript:

js
import OpenAI from "openai";

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

const result = await client.images.generate({
  model: "gpt-image-1.5",
  prompt: "Create a clean editorial illustration of a robot camera operator in a bright studio",
  size: "1024x1024",
  quality: "medium",
});

Aquí hay un detalle práctico que muchos articles flojos saltan: según el Images API reference, los modelos GPT Image devuelven b64_json por defecto. Eso significa que la primera prueba exitosa no debería limitarse a comprobar si la petición devuelve 200, sino si tu backend puede decodificar esa respuesta y guardarla o reenviarla correctamente.

Esta rama es la mejor primera recomendación porque responde a la pregunta operativa real: ¿puedo obtener una imagen usable del stack actual de OpenAI sin meter más orquestación de la necesaria? Si la respuesta es sí, luego ya puedes añadir edits, transparencia, formatos de salida o Responses. Si la respuesta es no, el problema suele estar en acceso, organización o naming del modelo, no en que te falte una capa agentic.

Si quieres ejemplos más completos con JavaScript, Python y cURL, sigue con la guía local de OpenAI image generation API example. Esta página se queda a propósito en la pregunta de endpoint.

Si ya tienes imágenes de entrada, usa POST /v1/images/edits

Muchos usuarios buscan “image generation endpoint” y a mitad de integración descubren que el trabajo real no es generar desde cero, sino modificar una imagen existente. Para ese caso, la ruta adecuada sigue siendo la Images API directa, solo que en la rama de edición.

El Images API reference enumera POST /images/edits como endpoint de edición, y el image generation guide ya enseña ejemplos actuales de edición con GPT Image 1.5 en esa misma superficie. Eso importa porque deja claro que editar no obliga a cambiar de API surface.

La forma corta en SDK se ve así:

js
import fs from "fs";
import OpenAI from "openai";

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

const result = await client.images.edit({
  model: "gpt-image-1.5",
  image: [fs.createReadStream("product-shot.png")],
  prompt: "Keep the product shape, but place it on a clean studio shelf with warm lighting",
  input_fidelity: "high",
});

Vale la pena mencionar input_fidelity: "high" incluso en un artículo centrado en endpoints porque demuestra que la ruta directa de edición no es una opción “básica”. Es la superficie oficial actual para edits serios. Solo deberías abandonarla cuando el workflow es lo que se vuelve más complejo, no simplemente porque la tarea de imagen deje de ser trivial.

Ahí es donde muchos tutorials se desvían. Tratan cualquier trabajo de imagen más rico como si automáticamente debiera moverse a Responses. Eso añade capas innecesarias. Mientras el trabajo siga siendo “modifica esta imagen” o “combina estas entradas”, la ruta directa sigue siendo más limpia.

Si tu siguiente duda ya no es el endpoint sino masks, input_fidelity, preservación o composiciones multiimagen, la guía correcta es OpenAI image editing API. Esta página solo necesita dejar fijada la regla más importante: editar es un caso nativo de Images API, no una razón automática para saltar a Responses.

Cambia a Responses solo cuando la imagen sea una tool dentro de un flujo mayor

Responses vale la pena cuando la generación de imágenes ya no es el centro del endpoint, sino una herramienta dentro de un sistema más grande. Si tu producto necesita un modelo que lea instrucciones, razone, quizá llame otras tools y luego genere una imagen en una fase concreta del flujo, entonces el image_generation tool sí se vuelve la abstracción correcta.

El error de implementación más común en este punto es poner gpt-image-1.5 directamente en el model superior de Responses. El actual tool guide de image_generation es explícito: los modelos GPT Image se usan detrás de la tool, pero no son valores válidos para el campo model superior.

La forma correcta se parece más a esto:

js
import OpenAI from "openai";

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

const response = await client.responses.create({
  model: "gpt-5",
  input: "Generate a transparent sticker-style icon of a paper airplane for a travel app",
  tools: [{ type: "image_generation", background: "transparent", quality: "high" }],
});

Esta ruta es válida, pero resuelve otro problema. Es mejor cuando:

1. la misma petición puede devolver texto e imágenes
2. la generación de imagen es una tool más entre varias
3. quieres que el modelo decida cuándo generar, cuándo seguir razonando y cuándo continuar la conversación

Es peor cuando tu problema actual solo es “qué endpoint debería usar primero para sacar una imagen”. En ese caso, Responses introduce más capas: un modelo principal, invocación de tools, parseo de tool outputs y una cadena de depuración más indirecta.

Por eso la regla no es “Responses es más nuevo, luego mejor”. La regla es: Responses es mejor cuando la orquestación es el problema real. Si todavía no estás resolviendo orquestación, no te des una complejidad extra demasiado pronto.

Si después de esta página quieres una vista más amplia de toda la ruta de integración, la continuación natural es el OpenAI Image API tutorial.

El desajuste de la documentación y los checks de acceso hacen que un endpoint correcto parezca incorrecto

Aquí es donde la SERP actual sigue fallando más. Mucha gente cree que eligió el endpoint equivocado cuando el problema real es confusión de frescura o acceso de cuenta.

La confusión de frescura existe de verdad. A 23 de marzo de 2026, el all-model catalog presenta GPT Image 1.5 como la línea actual de imagen. La página de GPT Image 1.5 también la trata como el flagship actual. Pero la página oficial Images and vision sigue diciendo que el latest image generation model es gpt-image-1. El cookbook example antiguo también usa gpt-image-1.

Eso no significa que las docs oficiales no sirvan. Significa que no están perfectamente sincronizadas. La forma más segura de usarlas es esta:

1. usa el API reference para los paths crudos
2. usa el all-model catalog y la página de GPT Image 1.5 para la frescura actual
3. usa el image generation guide para elegir superficie
4. usa el tool guide solo cuando ya estés en la ruta de Responses

El segundo gran problema es el acceso. La página de GPT Image 1.5 muestra Free not supported y empieza el acceso público en Tier 1 con 100,000 TPM y 5 IPM. La guía de API model availability añade que gpt-image-1 y gpt-image-1-mini dependen de tiers 1 through 5 y, en algunos casos, de organization verification. Eso significa que puedes haber acertado con el endpoint y aun así fallar por estado de cuenta.

Además, el ecosistema sigue arrastrando ruido de rollout. En el propio hilo de lanzamiento de GPT Image 1.5, varios desarrolladores reportaron problemas de disponibilidad y model-not-found durante el despliegue. Ese tipo de respuestas puede seguir vivo en tutorials viejos, foros y snippets cacheados.

El orden de depuración más seguro es:

1. confirmar la ruta correcta: Images API primero, Responses solo cuando haga falta
2. confirmar el modelo actual correcto: GPT Image 1.5 como default fresco
3. revisar tier, organización activa y verification
4. solo después tocar payloads o SDK calls

Si tu problema real es de acceso y no de superficie, la mejor continuación es la guía local de OpenAI image generation API verification. Cambiar endpoints al azar casi nunca arregla esa rama.

Recomendación final

Si quieres una regla corta y útil para el 23 de marzo de 2026, quédate con esta:

• usa POST /v1/images/generations para generación directa
• usa POST /v1/images/edits cuando ya tienes imágenes de entrada
• usa Responses con image_generation solo cuando la imagen sea una tool dentro de un workflow mayor
• usa el API reference para los paths y el all-model catalog más la página de GPT Image 1.5 para la frescura

Esta secuencia es mejor que la media actual de page one porque no solo repite facts oficiales: los convierte en una decisión operativa. La mayoría de resultados siguen obligando al lector a ensamblar la respuesta entre reference pages, help center pages y ejemplos antiguos. La forma más segura de trabajar es otra: elige primero la surface correcta, prueba una petición directa mínima y solo luego añade la complejidad extra que tu producto de verdad necesita.

FAQ

¿Necesito Responses para editar imágenes normales?

No. Para workflows corrientes de edición, la documentación actual de OpenAI sigue soportando POST /v1/images/edits y client.images.edit() como ruta principal. Responses solo gana cuando la edición de imágenes es parte de un flujo multimodal o agentic más amplio.

¿Todavía debería usar gpt-image-1 porque aparece en algunas páginas oficiales?

No como default para trabajo nuevo. A fecha del 23 de marzo de 2026, el catálogo de modelos y la página de GPT Image 1.5 dejan claro que GPT Image 1.5 es la línea actual. gpt-image-1 sirve mejor para migración o compatibilidad legacy.

¿Por qué falla una llamada aunque el endpoint sea correcto?

Porque elegir bien el endpoint y tener acceso listo no son la misma cosa. La página actual de GPT Image 1.5 muestra que Free no está soportado, y la guía de disponibilidad de modelos sigue vinculando parte del acceso a paid tiers y organization verification. Si la ruta parece correcta pero la llamada falla, revisa acceso antes de reescribir el código.