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-2tambié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
imagetambié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 algpt-image-2por defecto, con una mejor relación calidad-precio, sin cambios en el precio.
Fórmula de facturación:officialCosto final = Token de entrada de texto + Token de entrada de imagen (solo edición) + Token de salida de imagen. El precio mostrado dequality × sizees una estimación previa a la solicitud, y el cargo real se basa en elusagede la respuesta exitosa. Por ejemplo, el costo de salida de imagen paralow,1024x1024es generalmente alrededor de 0.0505 Créditos, más una pequeña cantidad de Tokens de entrada; al usarauto, 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 esA continuación, se presentan dos ejemplos reales desde diferentes perspectivas para experimentar la capacidad de edición de1024x1024, al pasarsizecomo2048x2048, el modelo redibujará y producirá una imagen de 2K; sisizese pasa como3840x2160, se generará una imagen de 4K en formato horizontal. La facturación para las tres dimensiones degpt-image-2y:reversees la misma;:officialse basa en el uso real de Tokens. Omitir el camposizees completamente equivalente a pasar explícitamenteauto:gpt-image-2primero 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 directamenteWIDTHxHEIGHT. 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ámetronLa interfaz de edición degpt-image-2admiten > 1: se pueden devolver múltiples resultados de edición en una sola solicitud. Por defecto,gpt-image-2y:reversese cobran según la cantidad de imágenes exitosas;:officialse cobra según el uso real de tokens de la respuesta completa (valores dende 1 a 10). Esto también se aplica agpt-image-1/gpt-image-1.5, así como a las seriesnano-banana/nano-banana-2-lite/nano-banana-2/nano-banana-pro. Tenga en cuenta queresponse_format=b64_jsonsolo admiten=1, y paran>1utilice 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.
gpt-image-2.
Método de llamada uno: JSON + URL de imagen (recomendado)
Envía la solicitud directamente en formatoapplication/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:


Consejo: El campoimagetambié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 congpt-image-2):

task_id: e9544dba-727e-44a2-81e1-223d49869380):

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 cargamultipart/form-data anterior también es aplicable, solo necesitas cambiar model a gpt-image-2:
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 serienano-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.
imagese puede cargar como archivo a través demultipart/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 > 1es 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), perocreatedes fijo en0, y no se devolveráb64_json,revised_promptsiempre será igual alpromptoriginal.
Llamada a través de formulario + URL de imagen

Llamada a través de formulario + archivo local
Callback asíncrono
El mecanismo de callback asíncronocallback_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: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.

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:
gift-basket.png en el directorio actual, el resultado específico es el siguiente:

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 adicionalcallback_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:
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.

