OpenAI Image Generation API Example: JavaScript, Python y cURL actuales

Si hoy buscas un OpenAI image generation API example, el punto de partida más seguro sigue siendo Images API con gpt-image-1.5. A 23 de marzo de 2026, esa es la ruta más limpia para una petición directa de generación. Cambia a Responses API solo cuando la generación de imágenes sea una herramienta dentro de un workflow multimodal más amplio.

Este keyword sigue siendo más confuso de lo que debería porque OpenAI reparte la respuesta entre varias páginas. El image generation guide cubre generación y edición directas. El tool guide de image_generation enseña la ruta con responses.create(). Y la referencia de Images API aclara los endpoints crudos. Si lees una sola página, es fácil copiar código válido en la superficie equivocada.

La secuencia más segura es simple: primero haz que una petición directa genere una imagen y la guarde en disco; después añade edits, transparencia, compresión o streaming. Si más adelante tu producto necesita conversación, tools o razonamiento multimodal, entonces sí tiene sentido pasar a Responses.

El ejemplo más rápido que hoy debería funcionar

Para esta búsqueda, el mejor punto de partida es Images API. El endpoint actual es POST /v1/images/generations, y el modelo más razonable para un ejemplo nuevo es gpt-image-1.5. Si solo quieres lanzar una petición y obtener una imagen, no necesitas empezar por un assistant workflow.

El modelo mental más útil es:

• mandas un prompt
• recibes una imagen en base64
• la decodificas
• la guardas en disco

Ejemplo mínimo en JavaScript:

js
import fs from "fs";
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",
});

const imageBase64 = result.data[0].b64_json;
const imageBuffer = Buffer.from(imageBase64, "base64");
fs.writeFileSync("openai-image-example.png", imageBuffer);

La versión equivalente en Python:

python
from openai import OpenAI
import base64

client = OpenAI()

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

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)

with open("openai-image-example.png", "wb") as f:
    f.write(image_bytes)

Y la versión en cURL, útil para backend o debugging:

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"
  }' \
  | jq -r '.data[0].b64_json' \
  | base64 --decode > openai-image-example.png

Si tu shell no acepta base64 --decode, usa la bandera equivalente de tu sistema. En macOS normalmente es base64 -D.

Este es el mejor ejemplo por defecto porque enseña el contrato actual sin obligarte a introducir tools o conversation state demasiado pronto. Otro detalle que muchos tutorials viejos omiten es que los modelos GPT de imagen devuelven base64 por defecto, no una URL alojada. Por eso un ejemplo útil tiene que incluir el paso de decodificar y guardar el archivo.

Cuándo elegir Images API y cuándo Responses

Si solo quieres generar o editar imágenes, Images API es más fácil de entender y de depurar. Si estás construyendo un assistant que mezcla texto, tools, imágenes y contexto conversacional, entonces Responses encaja mejor.

La regla que page one todavía no deja suficientemente clara es esta: no empieces con Responses solo porque parezca más moderno. Empieza con Responses cuando tu producto realmente necesite orquestación multimodal. Si no, haces más difícil el primer ejemplo sin ganar nada.

Hay un segundo error muy común. En la ruta de Responses, el campo model debe ser un modelo principal como gpt-5, no gpt-image-1.5. La guía del tool deja claro que el image_generation tool usa GPT Image por detrás, mientras que el modelo superior sigue siendo el que decide cuándo y cómo llamar al tool.

Eso también cambia la forma de depurar. En Images API casi siempre revisas access, shape del request o cómo guardas el archivo. En Responses además puedes perder tiempo en la invocación del tool o en el parseo del output. Por eso este artículo mantiene el primer ejemplo en la ruta directa.

Si buscas una explicación más amplia de rutas y no solo el ejemplo mínimo, puedes seguir con el tutorial OpenAI Image API en español.

Antes de ejecutar el ejemplo: revisa access y model IDs

Muchos errores de “este ejemplo no funciona” son en realidad problemas de acceso. A 23 de marzo de 2026, la página de GPT Image 1.5 indica Free not supported, y muestra Tier 1 desde 100,000 TPM y 5 IPM. Eso significa que puedes tener código correcto y aun así no poder llamar al modelo.

Hay otro matiz importante. El artículo de ayuda API model availability by usage tier and verification status explica que gpt-image-1 y gpt-image-1-mini están disponibles para usuarios API de tiers 1 a 5, con parte del acceso sujeta a organization verification. Así que, si copias un ejemplo válido y sigues viendo errores de access, primero revisa la cuenta.

El orden correcto es:

1. Instalar el SDK actual.
2. Confirmar OPENAI_API_KEY.
3. Verificar que tu cuenta está en un usage tier compatible.
4. Comprobar la organización activa.
5. Confirmar que usas un model ID actual.
6. Solo después tocar prompt o parámetros.

Node.js:

bash
npm install openai

Python:

bash
pip install openai

Si acabas de completar la verification y aún ves errores como not verified, el artículo de API Organization Verification recomienda esperar hasta 30 minutos, crear una nueva API key, refrescar la sesión y confirmar la organización correcta. Ese detalle merece estar en una guía de ejemplos porque es una de las primeras ramas reales de fallo.

La regla operativa aquí es clara: depura access primero, request shape después y prompt quality al final. Muchos developers lo hacen al revés y pierden tiempo innecesariamente.

Cómo añadir edits y output controls sin cambiar de API

Cuando el ejemplo base ya funciona, no cambies de superficie sin motivo. Image edits, transparent backgrounds y output tuning siguen perteneciendo a la ruta directa de Images API.

Ejemplo actual de edición:

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-photo.png"),
    fs.createReadStream("logo.png"),
  ],
  prompt: "Add the logo to the product box as if it were printed on the packaging.",
  input_fidelity: "high",
});

const imageBase64 = result.data[0].b64_json;
fs.writeFileSync("product-with-logo.png", Buffer.from(imageBase64, "base64"));

Ese input_fidelity: "high" conviene usarlo con criterio. El guide actual indica que ayuda a preservar mejor los detalles de la imagen de entrada, pero también aumenta el coste de image tokens. Úsalo cuando la fidelidad del input realmente importe; no como reflejo automático.

La misma API directa también soporta:

• size: para el primer test, 1024x1024 sigue siendo lo más estable
• quality: medium es un buen default para validar que todo funciona
• background: transparent para GPT image models en png y webp
• output_format: jpeg o webp cuando tamaño y latencia importan
• output_compression: útil para controlar la compresión de JPEG o WebP

La mejor regla práctica es mantener aburrida la primera petición. Una imagen cuadrada a calidad media te ayuda a aislar access, payload, decodificación y escritura del archivo. Cuando eso ya funciona, entonces sí añades transparencia, high quality o multi-image edits.

Si antes de escalar a producción quieres entender el coste, el siguiente paso lógico es la guía de pricing de OpenAI image generation API.

Cuándo sí conviene pasar a Responses

Si tu producto ya no es “generar una imagen” sino “un assistant que razona, usa tools y a veces devuelve imágenes”, entonces Responses es la abstracción correcta.

Ejemplo actual en JavaScript:

js
import fs from "fs";
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",
    },
  ],
});

const imageBase64 = response.output
  .filter((item) => item.type === "image_generation_call")
  .map((item) => item.result)[0];

fs.writeFileSync("paper-airplane.png", Buffer.from(imageBase64, "base64"));

Ese ejemplo es válido, pero resuelve otro problema. Es mejor cuando la generación de imagen es una pieza dentro de una interacción más amplia. No es mejor solo porque use Responses.

Usa Responses cuando:

• la misma llamada puede devolver texto e imagen
• la imagen es un tool dentro de un assistant workflow
• quieres que el modelo decida cuándo generar o continuar
• la parte visual convive con otros tools

Mantente en Images API cuando:

• quieres el onboarding más corto
• tu endpoint backend hace solo una tarea de imagen
• estás depurando generación o edición
• necesitas un ejemplo limpio para que otro developer lo copie rápido

Troubleshooting: los fallos que muchos tutorials omiten

El primer error es usar nombres de modelo antiguos porque un tutorial viejo todavía rankea bien. Esta query sigue mezclando material legacy, incluidos ejemplos de GPT Image 1 e incluso de la época DALL·E. Si hoy publicas un ejemplo nuevo, el nombre por defecto debe ser gpt-image-1.5.

El segundo error es poner gpt-image-1.5 directamente en el campo model de Responses. La guía del tool es clara: los modelos GPT Image viven detrás del tool image_generation, mientras que el model superior sigue siendo algo como gpt-5.

El tercer error es confundir un error de access con un error de código. Si el request devuelve problemas de availability, permission o verification, revisa tier y organization verification antes de tocar el payload. Si necesitas profundizar en esa rama, tienes la guía de verification en español.

El cuarto error es esperar el comportamiento viejo de DALL·E. Con GPT image models, la salida por defecto de Images API es base64. Por eso un ejemplo serio tiene que incluir el paso de decodificar y guardar el archivo.

El quinto error es intentar resolver todos los requisitos en la primera petición. Mucha gente mete portrait size, transparencia, high quality, multi-image edit y assistant orchestration antes de demostrar que la ruta directa básica ya funciona. Ese orden es malo. Primero prueba la ruta directa; después añade solo la siguiente capacidad que de verdad necesitas.

Otra rama práctica es comparar SDK y cURL. Si ambos fallan de la misma manera, el problema rara vez es tu app. Suele ser access, model naming o organization context. Si cURL funciona y tu aplicación no, entonces es más probable que el fallo esté en las variables de entorno, el parseo del request o la escritura del archivo.

También conviene conservar la primera petición exitosa como baseline interno del equipo. Guarda el prompt, el model name, el size, el quality, el payload exacto de cURL y el archivo ya decodificado. Cuando más adelante alguien active transparency, cambie el aspect ratio o pruebe edits, ese baseline te deja ver mucho más rápido si el problema apareció por access, por disponibilidad del modelo o solo por el nuevo parámetro que acabas de introducir.

Otra mejora operativa es separar el rollout por etapas. Primero confirma que el request cuadrado básico funciona igual desde el SDK y desde cURL. Después valida por separado el decode-and-save, porque una parte de los fallos no está en la API sino en cómo tu entorno escribe el archivo. Solo cuando esa base esté estable merece la pena añadir output tuning, multi-image edits o Responses orchestration. Ese orden reduce ruido en los logs y acelera mucho la depuración cuando varias personas tocan el mismo flujo.

También ayuda acordar un runbook interno corto para este caso. Si el equipo deja por escrito “este example quedó validado con Images API, con este model name y con estos access checks”, el siguiente developer no tiene que reabrir toda la discusión sobre docs fragmentadas, availability o verification. En esta query eso importa especialmente porque buena parte de la confusión no nace de un payload complicado, sino de mezclar una ruta directa pensada para generar una imagen con una ruta de assistant workflow que resuelve otra necesidad.

Con esa referencia mínima, además, es mucho más fácil distinguir un cambio real del producto de un simple error de entorno. Y evita debates innecesarios dentro del equipo.

FAQ

¿Debo usar gpt-image-1.5 o gpt-image-1 en un ejemplo nuevo?

Para un ejemplo directo nuevo, usa gpt-image-1.5. La página oficial de GPT Image 1.5 la marca como el modelo de generación de imágenes más reciente. gpt-image-1 sigue siendo útil para migración y comparación legacy, pero no como default principal.

¿Por qué el ejemplo directo devuelve base64 y no una URL de imagen?

Porque los modelos GPT de imagen devuelven base64 por defecto. Esa es una de las razones por las que tantos tutorials viejos siguen generando confusión: asumían una salida más parecida a DALL·E con URL alojada.

¿Necesito Responses para transparent PNGs o image edits?

No. La ruta directa de Images API ya soporta edits, input_fidelity, transparent backgrounds y output tuning con output_format y output_compression. Pasa a Responses cuando necesites orquestación, no solo un parámetro más.

Recomendación final

Para la búsqueda openai image generation api example, la respuesta más honesta hoy es más estrecha de lo que sugiere page one: empieza con Images API, usa gpt-image-1.5, mantén la primera petición pequeña y cuadrada, y guarda en disco la imagen base64 devuelta. Esa sigue siendo la ruta más rápida para un ejemplo útil a 23 de marzo de 2026.

Pasa a Responses image_generation solo cuando tu producto realmente necesite que la imagen sea un tool dentro de un workflow más grande. Si mantienes clara esa frontera, desaparece la mayor parte de la confusión actual.