dall-e-2, gpt-image-1, el más reciente gpt-image-2, así como la serie de modelos nano-banana / nano-banana-2 / nano-banana-pro integrados a través de la misma interfaz.
Este documento describe principalmente el flujo de uso de la API OpenAI Images Edits, con la cual podemos utilizar fácilmente la función oficial de edición de imágenes de OpenAI.
Proceso de solicitud
Para usar la API OpenAI Images Edits, primero puedes ir a la página OpenAI Images Edits API y hacer clic en el botón “Acquire” para obtener las credenciales necesarias para las solicitudes: Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión para registrarte o iniciar sesión; tras hacerlo, volverás automáticamente a esta página. Al solicitar por primera vez, recibirás un crédito gratuito para usar la API sin costo.Modelo GPT-Image-2
gpt-image-2 presenta mejoras muy notables en escenarios de edición de imágenes en comparación con gpt-image-1:
- Mayor estabilidad en la estructura: Al cambiar piel, colores o fondo, casi no se altera la composición ni el diseño original.
- Mejor preservación del texto: En imágenes con texto como infografías, carteles o menús, el texto permanece claro y legible tras la edición.
- Soporte para URL directo: Además de la tradicional subida de archivos
multipart/form-data,gpt-image-2permite pasar la URL de la imagen en formato JSON, sin necesidad de descargarla localmente, ideal para integraciones en backend. - Redibujo en alta resolución: Se puede enviar una imagen original 1K y mediante el parámetro
sizesolicitar salida en 2K o 4K; el modelo realizará la ampliación durante la edición.
Valores soportados para size
Las restricciones de size en la API de edición son idénticas a las de la generación: gpt-image-2 acepta size como auto, vacío o en formato WIDTHxHEIGHT; cualquier otro formato devuelve error 400. Todos los tamaños (1K / 2K / 4K / personalizados) se cobran por imagen, independientemente de la resolución original o el valor solicitado en size.
Las restricciones superiores para tamaños personalizados también aplican: ancho y alto deben ser múltiplos de 16, lado largo ≤ 3840, y total de píxeles ≤ 8,294,400.
Por ejemplo: si la imagen original es1024x1024y se pasasizecomo2048x2048, el modelo redibujará y entregará una imagen 2K; si se pasa3840x2160, se genera una imagen 4K horizontal; si se pasaautoo se omite, el modelo selecciona automáticamente. Los tres casos tienen el mismo costo.
Sobre el parámetroA continuación, mostramos dos ejemplos reales para apreciar la capacidad de edición denActualmente, la API de edicióngpt-image-2no soportan > 1: este parámetro se ignora silenciosamente, y siempre se devuelve una sola imagen por solicitud, cobrando solo por una. Si necesitas múltiples resultados, debes realizar solicitudes concurrentes. Esta limitación también aplica paragpt-image-1/gpt-image-1.5y la serienano-banana. Solodall-e-2soporta nativamenten > 1en edición.
gpt-image-2.
Modo de llamada 1: JSON + URL de imagen (recomendado)
Envía la solicitud conapplication/json, asignando en el campo image la URL de una imagen; el modelo descargará la imagen y la editará según el prompt.
Por ejemplo, esta imagen original es una infografía generada con gpt-image-2:
Queremos convertirla a un esquema de “modo nocturno”. La llamada sería:
Consejo: El campoimagetambién acepta un arreglo, por ejemplo"image": ["url1", "url2", "url3"], hasta 16 imágenes de referencia para que el modelo las considere en conjunto.
Modo de llamada 2: JSON + múltiples imágenes de referencia
gpt-image-2 puede usar varias imágenes como referencia para generar un resultado final, por ejemplo, combinar varias fotos de productos en una sola cesta de regalo:
Ejemplo de escenario: cambio de estilo manteniendo estructura
Otro ejemplo: reemplazar una estantería de madera por una moderna flotante, manteniendo estrictamente la cantidad y disposición de libros en cada nivel. Imagen original (estantería de madera generada congpt-image-2):
Llamada:
task_id: e9544dba-727e-44a2-81e1-223d49869380):
Se aprecia que el estilo y ambiente se cambiaron según el prompt, pero la cantidad de libros en cada nivel (1 / 3 / 7) se mantiene, y se añadió la suculenta solicitada.
Modo de llamada 3: multipart/form-data (compatible con OpenAI SDK)
Si usas el SDK oficial de OpenAI para Python, la subida tradicionalmultipart/form-data también funciona, solo cambia el model a gpt-image-2:
OPENAI_BASE_URL a https://api.acedata.cloud/openai y OPENAI_API_KEY con el token obtenido:
Serie Nano Banana
La serienano-banana también está integrada en /openai/images/edits; solo cambia el model a cualquiera de los siguientes:
Importante: parámetros soportados Nano Banana usa una capa adaptadora para el protocolo OpenAI y solo soporta los parámetros:model,prompt,image.
imagepuede subirse como archivomultipart/form-data(internamente convertido adata:<mime>;base64,...) o pasarse como URL en campo de formulario.- No soporta
mask,n,size,response_format, etc.; si se envían, se ignoran.- La respuesta sigue el formato OpenAI (
data[].url), perocreatedsiempre es0, no devuelveb64_json, yrevised_promptes igual al prompt original.
Llamada con formulario + URL de imagen
Llamada con formulario + archivo local
Callback asíncrono
El mecanismo de callback asíncrono concallback_url también funciona para nano-banana, el flujo es idéntico al de otros modelos, ver sección Callback asíncrono.
Uso básico
A continuación, un ejemplo de llamada con CURL:authorization (seleccionado del menú desplegable), model (modelo OpenAI a usar, aquí principalmente uno de los modelos listados), prompt (texto que describe la imagen a generar) y image (ruta de la imagen a editar), como la imagen mostrada a continuación:
Código equivalente en Python:
OPENAI_BASE_URL a https://api.acedata.cloud/openai y OPENAI_API_KEY con el token obtenido:
gift-basket.png, con el siguiente resultado:
Así completamos la edición de la imagen. Actualmente, la API Edits soporta tres modelos: dall-e-2, gpt-image-1 y gpt-image-2, siendo este último el recomendado, como se explicó en la sección Modelo GPT-Image-2.
Callback asíncrono
Dado que la edición de imágenes con OpenAI Images Edits API puede tardar, si la API no responde rápido, la conexión HTTP se mantiene abierta, consumiendo recursos. Por ello, la API soporta callbacks asíncronos. El flujo es: el cliente envía la solicitud incluyendo el campocallback_url. La API responde inmediatamente con un task_id que identifica la tarea. Cuando la edición termina, el resultado se envía en formato JSON mediante POST a la URL indicada en callback_url, incluyendo el task_id para relacionar la tarea.
Ejemplo:
Primero, el webhook es un servicio HTTP que recibe solicitudes; el desarrollador debe usar su propio servidor. Para demostración, usamos el sitio público https://webhook.site/, que genera una URL webhook como esta:
Copia esta URL, por ejemplo https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab.
Luego, envía la solicitud con callback_url:
task_id y el campo data con el resultado de la edición, igual que en la llamada síncrona, permitiendo relacionar el resultado con la tarea.
Manejo de errores
Si ocurre un error, la API devuelve un código y mensaje correspondiente, por ejemplo:400 token_mismatched: Solicitud incorrecta, posiblemente por parámetros faltantes o inválidos.400 api_not_implemented: Solicitud incorrecta, posiblemente por parámetros faltantes o inválidos.401 invalid_token: No autorizado, token inválido o ausente.429 too_many_requests: Demasiadas solicitudes, se excedió el límite de tasa.500 api_error: Error interno del servidor.

