> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI Images Edits API Solicitud y Uso > OpenAI generation API guide - Ace Data Cloud 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](https://platform.acedata.cloud/console/applications) para obtener tu token de API, que debes guardar para uso futuro. ![](https://cdn.acedata.cloud/5hmkdg.jpg) 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](https://platform.acedata.cloud/console/coin). > 📘 Documentación completa: [OpenAI Images Edits API →](https://platform.acedata.cloud/documents/openai-images-edits) ## 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. | Proporción | 1K Recomendado | 2K Recomendado | 4K Recomendado | | ---------- | -------------- | -------------- | -------------- | | 1:1 | `1024x1024` | `2048x2048` | `2880x2880` | | 4:3 | `1536x1024` | `2048x1536` | `3264x2448` | | 3:4 | `1024x1536` | `1536x2048` | `2448x3264` | | 16:9 | `1792x1024` | `2048x1152` | `3840x2160` | | 9:16 | `1024x1792` | `1152x2048` | `2160x3840` | > 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: ```shell theme={null} curl -X POST "https://api.acedata.cloud/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "Convierte esta infografía a modo oscuro: fondo azul marino oscuro, texto crema claro, tarjetas de módulo redondeadas en gris profundo con sombras suaves. Mantén todo el diseño, estructura y disposición de los módulos idénticos — solo invierte el esquema de color.", "size": "1024x1536" }' ``` O usa Python: ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/edits" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "Convierte esta infografía a modo oscuro: fondo azul marino oscuro, texto crema claro, tarjetas de módulo redondeadas en gris profundo con sombras suaves. Mantén todo el diseño, estructura y disposición de los módulos idénticos — solo invierte el esquema de color.", "size": "1024x1536" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` El resultado es el siguiente: ```json theme={null} { "success": true, "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753", "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8", "created": 1777048863, "data": [ { "revised_prompt": "Convierte esta infografía a modo oscuro: fondo azul marino oscuro, texto crema claro, tarjetas de módulo redondeadas en gris profundo con sombras suaves. Mantén todo el diseño, estructura y disposición de los módulos idénticos — solo invierte el esquema de color.", "url": "https://platform.cdn.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png" } ], "elapsed": 83.859 } ``` 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: > > ```python theme={null} > import base64, requests > b64 = base64.b64encode(open("input.png", "rb").read()).decode() > payload = { > "model": "gpt-image-2", > "image": f"data:image/png;base64,{b64}", > "prompt": "Convierte esta infografía a modo oscuro.", > "size": "1024x1536" > } > requests.post("https://api.acedata.cloud/openai/images/edits", json=payload, > headers={"authorization": "Bearer {token}"}) > ``` ### 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: ```python theme={null} payload = { "model": "gpt-image-2", "image": [ "https://example.com/item1.png", "https://example.com/item2.png", "https://example.com/item3.png" ], "prompt": "Combina todos los artículos anteriores en una sola canasta de regalo 'Relájate y Desconéctate' sobre un fondo blanco limpio, fotorealista, con luz natural suave.", "size": "1024x1024" } ``` ### 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: ```python theme={null} payload = { "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png", "prompt": "Reemplaza la estantería de madera por una elegante estantería flotante blanca moderna montada en una pared azul pastel. Mantén la misma disposición exacta de los libros (1 libro en la parte superior, 3 en el medio, 7 en la parte inferior). Agrega una pequeña suculenta en la estantería superior junto al libro. Luz brillante y aireada desde la izquierda.", "size": "1024x1024" } ``` 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`: ```python theme={null} import base64 from openai import OpenAI client = OpenAI() result = client.images.edit( model="gpt-image-2", image=[open("test.png", "rb")], prompt="Convierte esta imagen a modo oscuro mientras mantienes el diseño intacto." ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) with open("edited.png", "wb") as f: f.write(image_bytes) ``` 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: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={token} ``` ## 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. | Modelo | Facturación (Créditos / vez) | Escenarios aplicables | | -------------------- | ---------------------------- | ----------------------------------------------------------------------------- | | `nano-banana` | 0.14 | Edición de imágenes común, la más rápida y de menor costo | | `nano-banana-2-lite` | 0.14 | Modelo de imagen ligero Gemini 3.1, solo soporta 1K, edición de baja latencia | | `nano-banana-2` | 0.28 | Mejora notable en calidad y detalles | | `nano-banana-pro` | 0.35 | El buque insignia de la serie, mejor retención de estructura, texto y estilo | > **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`。 > > * `image` se puede subir como archivo a través de `multipart/form-data` (el worker lo convertirá internamente a `data:;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 `mask`、`n`、`size`、`response_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 ```shell theme={null} curl -X POST "https://api.acedata.cloud/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=nano-banana" \ -F "prompt=agregar una hoja verde encima de la manzana" \ -F "image=https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" ``` El resultado devuelto es el siguiente: ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.acedata.cloud/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg", "revised_prompt": "agregar una hoja verde encima de la manzana" } ] } ``` Imagen editada:

### Llamada a través de formulario + archivo local ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/edits" headers = { "authorization": "Bearer {token}" } files = { "image": open("apple.png", "rb"), } data = { "model": "nano-banana-pro", "prompt": "agregar una hoja verde encima de la manzana" } response = requests.post(url, headers=headers, files=files, data=data) print(response.text) ``` ### 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: ```curl theme={null} curl -s -D >(grep -i x-request-id >&2) \ -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \ -X POST "https://api.acedata.cloud/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F 'prompt=Crear una hermosa cesta de regalo con estos artículos en ella' ``` 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: ```python theme={null} import base64 from openai import OpenAI client = OpenAI() prompt = """ Generar una imagen fotorrealista de una cesta de regalo sobre un fondo blanco etiquetada 'Relájate y Desconéctate' con un lazo y una fuente similar a la escritura a mano, conteniendo todos los artículos en las imágenes de referencia. """ result = client.images.edit( model="gpt-image-1", image=[ open("test.png", "rb") ], prompt=prompt ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) # Guardar la imagen en un archivo with open("gift-basket.png", "wb") as f: f.write(image_bytes) ``` 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: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={token} ``` 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-2`、`gpt-image-1` y `gpt-image-2`, donde `gpt-image-2` es el modelo recomendado actualmente, consulte la sección [Modelo GPT-Image-2](#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/](https://webhook.site/), al abrir este sitio se obtiene una URL de Webhook, como se muestra en la imagen: ![](https://cdn.acedata.cloud/cjjfly.png) 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: ```shell theme={null} curl -X POST "https://api.acedata.cloud/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F "prompt=Create a lovely gift basket with these items in it" \ -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab" ``` Después de la llamada, se puede observar que se obtiene un resultado inmediato, como se muestra a continuación: ```json theme={null} { "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c" } ``` 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: ```json theme={null} { "success": true, "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c", "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc", "data": { "created": 1721626477, "data": [ { "b64_json": "iVBORw0KGgo..." } ] } } ``` 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 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## 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.