Guía de la API de GPT Image 2.5: Generación y edición de imágenes con Sunburst y Flare

Usa la Image API para generación y edición directa en un solo paso. Cuando la creación de imágenes forme parte de un diálogo o flujo de varios pasos, usa la Responses API. En la Image API, selecciona directamente gpt-image-2.5-sunburst o gpt-image-2.5-flare.

Selecciona primero la interfaz

La API de imágenes proporciona puntos finales de generación y edición. La API de respuesta admite la generación iterativa de imágenes como herramienta y puede mantener la entrada y salida de imágenes en contexto. Esta decisión arquitectónica es más importante que la sintaxis del SDK.

Modo de generación mínimo

{
  "header": "Configuración de Integración",
  "rows": [
    {
      "key": "videoUrl",
      "value": "URL de video"
    },
    {
      "key": "apiKey",
      "value": "Clave API"
    }
  ]
}

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

const client = new OpenAI(); const result = await client.images.generate({ model: "gpt-image-2.5-flare", prompt: "Una ilustración de diseño limpio que representa una biblioteca solar, sin elementos de texto" size: "1536x1024", quality: "media", output_format: "png" });

fs.writeFileSync("library.png", Buffer.from(result.data[0].b64_json, "base64"));

Guarde la clave API en el lado del servidor y manténgala fuera del control de código fuente.

## Control de salida

Ambos modelos son compatibles con configuraciones desde automáticas hasta la máxima calidad, tamaños personalizados dentro de los límites oficiales, formatos PNG/JPEG/WebP, compresión JPEG/WebP, y fondos transparentes u opacos. Para el canal Alpha, use los formatos PNG o WebP.

## Modo de edición

Utiliza una o más imágenes para llamar al endpoint de edición y proporciona un prompt que separe los cambios de los detalles que se conservan. Verifica el tipo y el tamaño de la entrada antes de enviarla. Asigna un rol a cada referencia.

## Verificación de producción

Almacenar ID de solicitud, modelo o instantánea, versión de prompt, tamaño, calidad, formato de salida, información de referencia, latencia y resultado aceptado. Reintentar solo fallos transitorios; sin cambiar la solicitud, no reintentar automáticamente salidas con errores semánticos.

## Enrutamiento de modelos

Enruta las tareas diarias a Flare y las de alta precisión a Sunburst. Usa una referencia fija, evita asumir que un modelo más rápido es más barato, ya que las tarifas de tokens actuales coinciden.

## Manejo de errores

Manejar autenticación, verificación de organización, límites de velocidad, dimensiones no válidas, moderación de contenido y salida vacía. Usar una estrategia de retroceso exponencial con jitter para errores transitorios elegibles, y limitar el número de reintentos. Nunca registrar datos de imágenes privadas innecesariamente.

## Animación posterior

Después de decodificar y aprobar la imagen, almacena la información de origen y pasa el activo al flujo de trabajo descendente. Cuando una imagen estática necesita convertirse en un storyboard, video o animación editorial liderado por personajes, [Elser AI](https://www.elser.ai/) es relevante. Por favor, verifica las opciones de carga y modelo compatibles en el producto en tiempo real.

## Puntos finales de generación y edición

Usa la función de generación al crear nuevas imágenes a partir de texto. Usa la función de edición cuando una o más imágenes existentes definan el sujeto o el estado inicial. Para ediciones con múltiples referencias, envía las entradas en un orden estable e identifica ese orden en el mensaje. Verifica el tipo y tamaño de archivo antes de la solicitud para que las entradas incorrectas fallen localmente.

## API de respuesta para trabajo iterativo

La API de Responses es muy útil cuando los usuarios crean imágenes, las evalúan de forma conversacional y solicitan cambios posteriores. La herramienta de generación de imágenes puede participar en un flujo de respuesta más amplio, y el ID del archivo de imagen puede mantenerse en el contexto. Esto reduce el trabajo de integración en el lado de la aplicación, pero el producto aún requiere un control de estado y versiones explícito. "Igual que antes" no es suficiente como restricción clave; por favor, reformúlelo.

## Arquitectura de aplicaciones más segura

Mantén el cliente, la cola de tareas, el almacenamiento de activos y el almacenamiento de metadatos independientes entre sí. El cliente envía una breve descripción. El servidor verifica la descripción y crea una tarea. El proceso de trabajo llama a OpenAI, decodifica el resultado y lo almacena bajo el ID de activo generado. Los metadatos registran la instantánea del modelo, las indicaciones, la configuración, las referencias y los resultados de la revisión. El cliente recibe una URL de activo de corta duración, en lugar de las credenciales originales.

Las llamadas de larga duración no deben ocupar solicitudes frágiles del navegador. Las indicaciones complejas pueden requerir mucho tiempo, por lo que se deben mostrar los estados pendiente, completado y fallido. Haga que el envío de tareas sea idempotente para evitar cargos duplicados cuando el cliente reintente.

## Reglas de verificación

Verifique que las dimensiones personalizadas cumplan con los múltiplos de 16, los bordes, la proporción y el límite total de píxeles especificados en la documentación. Cuando el fondo sea transparente, se requiere usar formato PNG o WebP. Limite el valor de compresión dentro del rango compatible. Solo se permiten parámetros de calidad y modelo conocidos. Rechace los casos de falta de prompt antes de la llamada a la API.

## Fiabilidad y observabilidad

Registra el ID de solicitud, el estado HTTP, la categoría de error, el número de intentos y la latencia, sin registrar imágenes privadas ni información confidencial. Para reintentos ante límites de tasa y errores de servidor elegibles, usa retroceso exponencial con fluctuación. No reintentes errores de autenticación, parámetros no válidos o errores de política. Establece un límite máximo de intentos y devuelve mensajes útiles del producto.

Monitor:

- Tasa de éxito y tasa de aceptación de imágenes.
- Latencia p50 y p95 por modelo y calidad.
- Tokens de entrada y salida.
- Tareas de reintento y repetición.
- Resultado de la revisión.
- Fallo en el almacenamiento y la entrega.

## Seguridad y Derechos

Almacene las claves API en el administrador de claves del servidor. Implemente control de acceso a las imágenes de origen y a las imágenes generadas. Establezca reglas de retención, elimine metadatos que no deban exponerse y registre los derechos de los usuarios sobre el material subido. OpenAI señala que el acceso al modelo de imágenes GPT puede requerir verificación organizacional; trátelo como un requisito previo de incorporación, no como una sorpresa en tiempo de ejecución.

## Política de instantáneas

Utiliza IDs sin fecha para obtener actualizaciones continuas del modelo. Cuando la repetibilidad sea más importante, fija una instantánea con fecha. Antes de cambiar el tráfico de producción, evalúa la nueva instantánea con la misma referencia. Almacena el identificador real del modelo devuelto o configurado para cada activo.

Si el artículo de inicio contiene código, muestre junto a él la fecha de verificación con la fecha correspondiente. Los lectores deben entender que la disponibilidad del modelo, la sintaxis del SDK, los límites de velocidad y los requisitos organizativos pueden cambiar independientemente de la arquitectura conceptual del artículo.

## Contrato de solicitud tipado

Incluso si el modelo de imagen no proporciona una salida estructurada, defina un esquema interno. Una tarea puede incluir `prompt` (indicación), `workflow` (flujo de trabajo), `model` (modelo), `quality` (calidad), `width` (ancho), `height` (alto), `format` (formato), `background` (fondo), `compression` (compresión), un ID de recurso de referencia y una clave idempotente. Valídelo antes de convertirlo en una llamada al SDK.

No expongas nombres de modelos ni rutas de archivo arbitrarios desde el navegador. Debes mapear las pocas opciones visibles para el cliente a valores aprobados por el servidor. Resuelve las referencias mediante IDs de activos controlados por acceso y verifica que el usuario actual tenga permiso para leer dichos activos.

## Borrador de solicitud de edición

```javascript
import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI();

const result = await client.images.edit({
  model: "gpt-image-2.5-sunburst",
  image: [fs.createReadStream("approved-character.png")],
  prompt: `Solo cambia el abrigo a lana verde oscuro.
Conserva el rostro, el color del cabello, el color de los ojos, la postura, las manos, la composición y el fondo.
No añadas texto, joyas ni otras personas.
  size: "1024x1536",
  quality: "alto",
  output_format: "png"
});

const bytes = Buffer.from(result.data[0].b64_json, "base64");
fs.writeFileSync("character-green-coat.png", bytes);

La interfaz exacta del SDK puede evolucionar, por lo tanto, antes de la implementación, verifique los ejemplos con la guía oficial actual. El código de producción debe transmitir o almacenar en búfer de manera responsable, verificar la existencia de la respuesta y almacenar de forma atómica, en lugar de asumir que cada llamada devuelve datos utilizables.

Idempotencia y costo de la repetición

El doble clic del usuario o los reintentos de red pueden provocar que la misma tarea costosa de generación se envíe dos veces. Asigne una clave idempotente al crear la tarea, persista la tarea antes de distribuirla y, cuando aparezca la misma clave, devuelva la tarea existente. El proceso de trabajo debe obtener la tarea solo una vez y registrar el estado final.

Si tienes la intención de generar múltiples variantes, por favor represéntalo como una operación de producto clara, y no como un reintento accidental. La API de imágenes admite la generación de múltiples imágenes a través del parámetro n en la documentación, pero tus costos y modelo de revisión deben contabilizar cada salida.

Experiencia del usuario en revisión y fallos

Todos los avisos e imágenes deben pasar por un filtro de seguridad. Evite revelar detalles internos sensibles de la revisión, pero brinde a los usuarios la orientación suficiente para modificar solicitudes legítimas. Diferencie los rechazos por políticas de configuraciones no válidas, autorización, límites de velocidad y fallos temporales del servicio.

Cuando Sunburst no esté disponible, nunca lo reemplace silenciosamente por otro modelo, ya que esto podría violar acuerdos de calidad o contractuales. Debe devolver un estado claro, o utilizar un plan de respaldo solo si el producto ha divulgado y documentado dicho comportamiento.

Almacenamiento y entrega de activos

Decodificar base64 en memoria y establecer límites de tamaño, validar el formato declarado, generar sumas de verificación y almacenar el archivo original inmutable. Generar miniaturas por separado. Servir mediante URL firmadas de corta duración y con tipos de contenido adecuados. Conservar el canal alfa de PNG/WebP transparentes, evitando que conversiones con pérdida dañen los entregables.

Almacenar sugerencias y referencias con controles de acceso adecuados que coincidan con su nivel de sensibilidad. Definir comportamientos de retención y eliminación. Los archivos generados sin fuente son difíciles de auditar, reproducir o entregar de manera segura al proyecto de animación Elser.

Lista de verificación previa al lanzamiento

• Se ha confirmado el acceso a la cuenta y a la organización.
• La clave API es del lado del servidor y se puede rotar.
• El ID del modelo y las reglas de dimensión han sido incluidos en la lista blanca.
• La entrega de tareas es idempotente.
• Número de reintentos limitado y clasificado.
• El uso, la latencia y la aceptación están bajo monitoreo.
• Las imágenes y los metadatos tienen reglas de retención.
• Para salidas sensibles en cuanto a identidad, marca y texto, existe revisión humana.
• Se ha registrado una política de instantáneas con fecha y una ruta de reversión.

Preguntas Frecuentes

¿Qué API debería elegir?

La API de imágenes se utiliza para generar/editar directamente; la API de respuestas se utiliza para experiencias de imágenes conversacionales o de múltiples pasos.

¿Puedo solicitar varias imágenes?

La API de imágenes admite el parámetro n para múltiples salidas en la documentación.

¿La API devuelve una URL?

La guía actual muestra los datos de imagen codificados en base64 de la API de imágenes; decodifíquelos y guárdelos de forma segura.

Conclusión

Una integración confiable combina un enrutamiento claro de modelos con una verificación estricta, observabilidad y revisión de activos. Primero construye la solicitud directa más pequeña, y solo cuando la ruta de imagen central sea confiable, agrega estado de conversación o animaciones posteriores.