Skip to main content
El servicio de edición de imágenes de OpenAI permite enviar imágenes y comandos, y recibir imágenes modificadas como resultado. La serie de modelos GPT Image permite enviar hasta 16 imágenes de referencia al mismo tiempo. Actualmente, la interfaz soporta gpt-image-1, la más reciente gpt-image-2, así como los modelos de la serie nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro que se conectan a través de la misma interfaz. Este documento describe principalmente el proceso de uso de la API de OpenAI Images Edits, que nos permite utilizar fácilmente la función de edición de imágenes oficial de OpenAI.

Proceso de Solicitud

Para usar la API de OpenAI Images Edits, primero dirígete a la consola de Ace Data Cloud para obtener tu Token de API, que debes guardar como respaldo. Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invitará a registrarte e iniciar sesión; una vez completado, regresarás automáticamente a la página actual. Un Token de API es suficiente para acceder a todos los servicios de la plataforma, sin necesidad de solicitar uno por cada servicio. La primera solicitud incluirá un crédito gratuito para que puedas probarlo; si el crédito se agota, puedes recargar el saldo general en la consola.
📘 Documentación completa: OpenAI Images Edits API →

Modelo GPT-Image-2

gpt-image-2 presenta mejoras significativas en comparación con gpt-image-1 en el contexto de edición de imágenes:
  • La estructura se mantiene más estable: al cambiar la piel, los colores o el fondo, casi no se altera la composición y el diseño de la imagen original.
  • La retención de texto es más precisa: imágenes que contienen texto, como infografías, carteles y menús, mantienen el texto claro y legible después de la edición.
  • Soporta la transmisión directa de URL: además de la carga de archivos tradicional multipart/form-data, gpt-image-2 también soporta la entrada de URL de imágenes en formato JSON, sin necesidad de descargar primero la imagen localmente, lo que es muy adecuado para la integración en líneas de servicio del servidor.
  • Soporta la transmisión directa de base64: de acuerdo con lo oficial, el campo image también puede recibir base64 directamente (data:image/png;base64,... o base64 puro), permitiendo editar imágenes locales sin necesidad de subirlas a un servidor de imágenes primero.
  • Soporta redibujo en alta resolución: se puede enviar una imagen original de 1K y solicitar una salida de 2K / 4K a través del parámetro size, el modelo completará el aumento durante el proceso de edición.

Variantes de Ruta (:official / :reverse)

gpt-image-2 utiliza por defecto la ruta estándar. Se puede seleccionar explícitamente la ruta mediante el sufijo del nombre del modelo:
  • gpt-image-2:official: canal oficial, estable y conforme. Los costos son determinados por el Token de entrada de texto, el Token de entrada de imagen durante la edición y el Token de salida de imagen, y se liquidan según el uso real en la respuesta; el precio de calidad/tamaño mostrado en la página es solo una estimación; el precio para el cliente es aproximadamente el 80% del precio estándar oficial de OpenAI, calculado según el paquete de uso máximo. El servicio manejará automáticamente la tolerancia entre canales disponibles, y la capacidad y costos se basarán en los resultados devueltos.
  • gpt-image-2:reverse: completamente equivalente al gpt-image-2 por defecto, con una mejor relación calidad-precio, sin cambios en el precio.
Fórmula de facturación :official Costo final = Token de entrada de texto + Token de entrada de imagen (solo edición) + Token de salida de imagen. El precio mostrado de quality × size es una estimación previa a la solicitud, y el cargo real se basa en el usage de la respuesta exitosa. Por ejemplo, el costo de salida de imagen para low, 1024x1024 es generalmente alrededor de 0.0505 Créditos, más una pequeña cantidad de Tokens de entrada; al usar auto, el modelo puede elegir una calidad más alta, y el monto preautorizado se revisará de manera conservadora según el nivel más alto.

Valores de size soportados

La verificación de formato para size en la interfaz de edición es consistente con la interfaz de generación: gpt-image-2 solo necesita que size sea auto, esté vacío, o cumpla con el formato WIDTHxHEIGHT, cualquier otra forma devolverá 400. Por defecto, gpt-image-2 y :reverse cobran de manera uniforme por cada imagen; :official calculará simultáneamente los Tokens de entrada de texto, de imagen de referencia y de salida de imagen, donde la imagen original, el tamaño y la calidad pueden afectar el costo final. Límites de tamaño: los tamaños personalizados deben cumplir con que ambos lados sean múltiplos de 16, el lado más largo ≤ 3840, y el número total de píxeles ≤ 8,294,400; exceder esto devolverá 4xx.
Por ejemplo: si la imagen original es 1024x1024, al pasar size como 2048x2048, el modelo redibujará y producirá una imagen de 2K; si size se pasa como 3840x2160, se generará una imagen de 4K en formato horizontal. La facturación para las tres dimensiones de gpt-image-2 y :reverse es la misma; :official se basa en el uso real de Tokens. Omitir el campo size es completamente equivalente a pasar explícitamente auto: gpt-image-2 primero leerá la intención de tamaño explícita en las palabras clave, incluyendo píxeles, proporciones, orientación, niveles de resolución (por ejemplo, 4K / alta resolución) o nombres de lienzo. Cuando se identifica la intención de tamaño, se utilizará el tamaño específico planificado; si no hay requisitos de tamaño en las palabras clave o no se puede determinar automáticamente, se revertirá al tamaño de la primera imagen de referencia. El tamaño final específico se normalizará a múltiplos de 16, y se aplicarán límites de lado más largo y total de píxeles antes de enviar la solicitud; si se necesita un control absoluto, se debe pasar directamente WIDTHxHEIGHT. Una vez completada la generación, no se volverá a intentar automáticamente debido a diferencias en los píxeles de salida, para evitar costos de generación duplicados. Sobre el parámetro n La interfaz de edición de gpt-image-2 admite n > 1: se pueden devolver múltiples resultados de edición en una sola solicitud. Por defecto, gpt-image-2 y :reverse se cobran según la cantidad de imágenes exitosas; :official se cobra según el uso real de tokens de la respuesta completa (valores de n de 1 a 10). Esto también se aplica a gpt-image-1 / gpt-image-1.5, así como a las series nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro. Tenga en cuenta que response_format=b64_json solo admite n=1, y para n>1 utilice la URL de retorno predeterminada. Si algunas imágenes fallan en su generación, solo se devolverán y cobrarán las que tengan éxito.
A continuación, se presentan dos ejemplos reales desde diferentes perspectivas para experimentar la capacidad de edición de gpt-image-2.

Método de llamada uno: JSON + URL de imagen (recomendado)

Envía la solicitud directamente en formato application/json, llenando el campo image con la URL de una imagen, el modelo recuperará esa imagen y la editará según el prompt. Por ejemplo, la siguiente imagen original fue generada con gpt-image-2 como un infográfico de divulgación científica:

Queremos cambiarla a un esquema de color de “modo nocturno”. Podemos hacer la llamada de esta manera:
O usando Python:
El resultado devuelto es el siguiente:
La imagen editada es la siguiente:

Se puede observar que la estructura del módulo, la partición de información y la tipografía se han mantenido estrictamente, solo se ha invertido el esquema de color a un tema oscuro.
Consejo: El campo image también admite la entrada de un array, por ejemplo, "image": ["url1", "url2", "url3"], permitiendo un máximo de 16 imágenes de referencia para que el modelo las considere al editar.
Transmisión directa en base64: image (y cada elemento del array) puede ser una URL o base64 — data:image/png;base64,... o base64 puro, adecuado para imágenes locales que no se desean subir a un servidor de imágenes primero. Por ejemplo:

Método de llamada dos: JSON + múltiples imágenes de referencia

gpt-image-2 admite la referencia a múltiples imágenes para generar el resultado final, por ejemplo, combinar varias fotos de productos en una sola cesta de regalo:

Ejemplo de escenario: cambiar estilo + mantener estructura

Aquí hay otro ejemplo, reemplazando una estantería de madera por una estantería flotante moderna, pero manteniendo estrictamente la cantidad y disposición de los libros en cada estante. Imagen original (estantería de madera generada con gpt-image-2):

Llamada:
Resultado de la edición (task_id: e9544dba-727e-44a2-81e1-223d49869380):

Se puede observar que el estilo y el entorno se han reemplazado completamente según las instrucciones, pero la cantidad de libros en cada estante (1 / 3 / 7) se ha mantenido estrictamente, y se ha añadido una maceta con una planta suculenta como se solicitó.

Método de llamada tres: multipart/form-data (compatible con OpenAI SDK)

Si ya estás utilizando el SDK oficial de OpenAI para Python, el método de carga multipart/form-data anterior también es aplicable, solo necesitas cambiar model a gpt-image-2:
Al usar el SDK, necesitas importar primero dos variables de entorno, OPENAI_BASE_URL se establece en https://api.acedata.cloud/openai, y OPENAI_API_KEY se establece en el token solicitado:

Modelos de la serie Nano Banana

La serie nano-banana también se conecta a /openai/images/edits en el escenario de edición, solo necesitas cambiar model a cualquiera de los que se muestran en la tabla a continuación.
Importante: Rango de soporte de parámetros Nano Banana se conecta al protocolo de OpenAI a través de una capa de adaptación, solo soporta los siguientes parámetros: model, prompt, image, n.
  • image se puede cargar como archivo a través de multipart/form-data (los archivos locales se convertirán automáticamente a base64), o se puede pasar directamente como una cadena de URL de imagen a través de un campo de formulario.
  • No se soportan parámetros como mask, size, response_format, etc.; si se incluyen, serán ignorados. n > 1 es soportado (1–10), y devolverá y cobrará por la cantidad correspondiente de resultados de edición.
  • La estructura de retorno sigue el formato de OpenAI (data[].url), pero created es fijo en 0, y no se devolverá b64_json, revised_prompt siempre será igual al prompt original.

Llamada a través de formulario + URL de imagen

El resultado devuelto es el siguiente:
Imagen editada:

Llamada a través de formulario + archivo local

Callback asíncrono

El mecanismo de callback asíncrono callback_url también es efectivo para nano-banana, el flujo de llamada es completamente idéntico al de otros modelos, consulta la sección Callback asíncrono a continuación.

Uso básico

A continuación, puedes usar el código para realizar la llamada, aquí hay un ejemplo usando CURL:
Al usar esta interfaz por primera vez, necesitamos llenar al menos cuatro contenidos, uno es authorization, que se puede seleccionar directamente en la lista desplegable. Otro parámetro es model, model es la categoría del modelo de OpenAI que elegimos usar, aquí tenemos principalmente 1 tipo de modelo, los detalles se pueden ver en los modelos que proporcionamos. Otro parámetro es prompt, prompt es la frase que ingresamos para generar la imagen. El último parámetro es image, este parámetro necesita la ruta de la imagen que se va a editar, la imagen que se necesita editar se muestra a continuación:
Nota: image[] puede aparecer varias veces para cargar múltiples imágenes de referencia, por ejemplo -F "image[]=@a.png" -F "image[]=@b.png", los modelos de la serie GPT Image admiten hasta 16 imágenes (cada una no más de 50MB, en formato png/webp/jpg). Si se excede la cantidad, se devolverá un 400.

Código de ejemplo en Python con el mismo efecto de llamada:
Al usar Python para realizar la llamada, primero necesitamos importar dos variables de entorno, una OPENAI_BASE_URL, que se puede establecer en https://api.acedata.cloud/openai, y otra variable de credenciales OPENAI_API_KEY, cuyo valor se obtiene de authorization, en Mac OS se puede establecer la variable de entorno con el siguiente comando:
Después de la llamada, descubrimos que se generará una imagen gift-basket.png en el directorio actual, el resultado específico es el siguiente:

Así hemos completado la operación de edición de imágenes. Actualmente, la interfaz Edits admite dos modelos: gpt-image-1 y gpt-image-2, donde gpt-image-2 es el modelo recomendado para su uso, como se detalla en la sección anterior Modelo GPT-Image-2.

Callback Asíncrono

Dado que la API de Edits de OpenAI Images puede tardar un tiempo relativamente largo en editar imágenes, si la API no responde durante un tiempo prolongado, la solicitud HTTP mantendrá la conexión, lo que provocará un consumo adicional de recursos del sistema. Por lo tanto, esta API también ofrece soporte para callbacks asíncronos. El flujo general es el siguiente: cuando el cliente inicia la solicitud, especifica un campo adicional callback_url. Después de que el cliente realiza la solicitud a la API, la API devolverá inmediatamente un resultado que incluye un campo task_id, que representa el ID de la tarea actual. Cuando la tarea se completa, el resultado de la edición de la imagen se enviará al callback_url especificado por el cliente en formato JSON POST, que también incluirá el campo task_id, de modo que el resultado de la tarea se pueda asociar mediante el ID. A continuación, entenderemos cómo operar a través de un ejemplo. Primero, el callback de Webhook es un servicio que puede recibir solicitudes HTTP, y los desarrolladores deben reemplazarlo con la URL de su propio servidor HTTP. Para facilitar la demostración, utilizamos un sitio web de ejemplo de Webhook público https://webhook.site/, al abrir este sitio se obtiene una URL de Webhook, como se muestra en la imagen: Copie esta URL y podrá usarla como Webhook. El ejemplo aquí es https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab. A continuación, podemos establecer el campo callback_url como la URL de Webhook mencionada anteriormente, al mismo tiempo que llenamos los parámetros correspondientes, como se muestra en el siguiente código:
Después de la llamada, se puede observar que se recibe inmediatamente un resultado, como se muestra a continuación:
Después de un momento, podemos observar el resultado de la edición de la imagen en la URL de Webhook, que es el siguiente:
Se puede ver que en el resultado hay un campo task_id, y el campo data contiene el mismo resultado de edición de imagen que en la llamada sincrónica. A través del campo task_id, se puede realizar la asociación de la tarea.

Manejo de Errores

Al llamar a la API, si se encuentra con un error, la API devolverá el código de error y la información correspondiente. Por ejemplo:
  • 400 token_mismatched: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
  • 400 api_not_implemented: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
  • 401 invalid_token: No autorizado, token de autorización inválido o faltante.
  • 429 too_many_requests: Demasiadas solicitudes, ha superado el límite de tasa.
  • 500 api_error: Error interno del servidor, algo salió mal en el servidor.

Ejemplo de Respuesta de Error

Conclusión

A través de este documento, ha aprendido cómo utilizar la API de Edits de OpenAI Images para usar fácilmente la función de edición de imágenes oficial de OpenAI. Esperamos que este documento le ayude a integrar y utilizar mejor esta API. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico.