Skip to main content
El servicio de edición de imágenes de OpenAI permite enviar múltiples imágenes y comandos, y devuelve las imágenes modificadas. Actualmente, la API soporta simultáneamente dall-e-2, 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 integran a través de la misma API. 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 para uso futuro. 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, no es necesario solicitar uno por cada servicio. La primera solicitud te otorgará un crédito gratuito para que lo pruebes; 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: Cambiar la piel, los colores o el fondo casi no destruye la composición y el diseño de la imagen original.
  • La retención de texto es más precisa: Las 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 tradicional carga de archivos 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: Al igual que en la 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.

Variante de intermediación oficial / inversa (:official / :reverse)

gpt-image-2 utiliza por defecto la ruta inversa. Se puede seleccionar explícitamente la ruta mediante el sufijo del nombre del modelo:
  • gpt-image-2:official: Ruta de intermediación oficial. Soporta n > 1 (devuelve múltiples imágenes a la vez) y verdaderas salidas de 2K / 4K, cobrando por cada imagen, con un precio que es el doble del precio por defecto de gpt-image-2. Actualmente, solo está disponible a través del canal openai-hk; si la ruta no está disponible, devolverá un error directamente y no se degradará a la ruta inversa.
  • gpt-image-2:reverse: Equivalente completo a gpt-image-2 por defecto (ruta inversa), sin cambio de precio.
Las restricciones sobre el parámetro “n” que se mencionan a continuación solo se aplican a la ruta por defecto / inversa; gpt-image-2:official soporta n > 1 y cobra por imagen.

Valores soportados para size

Las restricciones de la interfaz de edición sobre size son completamente consistentes con la interfaz de generación: gpt-image-2 solo necesita que size sea auto, vacío, o que cumpla con el formato WIDTHxHEIGHT, cualquier otra forma devolverá 400. Todos los tamaños (1K / 2K / 4K / personalizado) se cobran de manera uniforme por imagen, sin relación con la resolución de la imagen original y el valor solicitado de size. Las restricciones estrictas sobre tamaños personalizados también son aplicables: tanto el ancho como la altura deben ser múltiplos de 16, el lado más largo ≤ 3840, y el número total de píxeles ≤ 8,294,400.
Por ejemplo: si la imagen original es 1024x1024, al pasar size como 2048x2048, el modelo redibujará y devolverá una imagen de 2K; si size se pasa como 3840x2160, devolverá una imagen de 4K en horizontal; si se pasa auto o se omite, el modelo elegirá por sí mismo. Los cargos son los mismos para los tres casos.
Sobre el parámetro n La interfaz de edición de gpt-image-2 actualmente no soporta n > 1: este parámetro será ignorado silenciosamente, ya sea que se pase n=1 o n=10, la solicitud única solo devolverá 1 imagen y se cobrará solo por 1 imagen. Si necesitas obtener múltiples resultados de edición candidatos a la vez, por favor inicia múltiples solicitudes concurrentes por tu cuenta. Esta restricción también se aplica a gpt-image-1 / gpt-image-1.5, así como a la serie nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro. dall-e-2 es actualmente el único modelo de edición que soporta nativamente n > 1.
A continuación, se presentan dos ejemplos reales desde diferentes ángulos 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 irá a buscar esa imagen y la editará según el prompt. Por ejemplo, la siguiente imagen original fue generada con gpt-image-2 como una ilustración científica:

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

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

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

gpt-image-2 admite la referencia de múltiples imágenes para generar el resultado final, por ejemplo, combinar varias fotos de productos en una sola canasta 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 editado (task_id: e9544dba-727e-44a2-81e1-223d49869380):

Se puede ver 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 agregado 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 en Python, el método de carga multipart/form-data también es aplicable, solo necesitas cambiar model a gpt-image-2:
Al usar el SDK, necesitas importar dos variables de entorno, OPENAI_BASE_URL debe establecerse en https://api.acedata.cloud/openai, y OPENAI_API_KEY debe establecerse en el token solicitado:

Modelos de la serie Nano Banana

La serie nano-banana también se ha integrado en el escenario de edición a través de /openai/images/edits, solo necesitas cambiar model a cualquiera de los que se encuentran 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: modelpromptimage
  • image se puede subir como archivo a través de multipart/form-data (el worker lo convertirá internamente a data:<mime>;base64,... para enviarlo al upstream), 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 masknsizeresponse_format; si se rellenan, serán ignorados.
  • 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, consulte la sección Callback asíncrono a continuación.

Uso básico

A continuación, se puede utilizar el código para realizar la llamada, a continuación se muestra cómo realizar la llamada mediante CURL:
En la primera vez que se utiliza esta interfaz, 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 palabra clave que ingresamos para generar la imagen. El último parámetro es image, este parámetro necesita la ruta de la imagen a editar, la imagen a editar se muestra a continuación:

Código de ejemplo de llamada en Python con el mismo efecto:
Para llamar a la API en Python, 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 soporta tres modelos: dall-e-2gpt-image-1 y gpt-image-2, donde gpt-image-2 es el modelo recomendado actualmente, consulte la sección Modelo GPT-Image-2 anterior.

Callback asíncrono

Dado que el tiempo de edición de imágenes de la API de OpenAI Images Edits puede ser relativamente largo, si la API no responde durante mucho tiempo, la solicitud HTTP mantendrá la conexión, lo que provocará un consumo adicional de recursos del sistema, por lo que esta API también ofrece soporte para callbacks asíncronos. El flujo general es: cuando el cliente inicia la solicitud, especifica un campo adicional callback_url, después de que el cliente inicia la solicitud de API, la API devolverá inmediatamente un resultado que incluye un campo de información 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, veamos un ejemplo para entender cómo operar específicamente. Primero, el callback de Webhook es un servicio que puede recibir solicitudes HTTP, los desarrolladores deben reemplazarlo con la URL de su propio servidor HTTP. Para facilitar la demostración, se utiliza 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: Copia esta URL y podrás 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 del Webhook mencionada, 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 obtiene un resultado inmediato, 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 del Webhook, el contenido es el siguiente:
Se puede ver que en el resultado hay un campo task_id, el campo data contiene el mismo resultado de edición de imagen que en la llamada sincrónica, y a través del campo task_id se puede realizar la asociación de tareas.

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, has 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, ya has aprendido cómo utilizar la API de Ediciones de Imágenes de OpenAI para usar fácilmente la función de edición de imágenes oficial de OpenAI. Esperamos que este documento te ayude a integrar y utilizar mejor esta API. Si tienes alguna pregunta, no dudes en contactar a nuestro equipo de soporte técnico.