> ## 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 imágenes e instrucciones, y recibir imágenes modificadas como resultado. La serie de modelos GPT Image puede recibir hasta 16 imágenes de referencia al mismo tiempo. Actualmente, la interfaz soporta simultáneamente `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 [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) para obtener tu API Token, que debes guardar como respaldo. ![](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 API Token es suficiente para acceder a todos los servicios de la plataforma, no es necesario 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](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**: al cambiar la piel, los colores o el fondo, casi no se destruye 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 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**: 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 línea (`:official` / `:reverse`) `gpt-image-2` utiliza por defecto la línea estándar. Se puede seleccionar explícitamente la línea mediante el sufijo del nombre del modelo: * **`gpt-image-2:official`**: canal oficial, estable y conforme. Soporta verdaderas resoluciones de 2K / 4K, **cobrando por cada imagen, con un precio que es el doble del precio por defecto de `gpt-image-2`**. Si la línea no está disponible, devolverá un error directamente, sin degradación automática. * **`gpt-image-2:reverse`**: completamente equivalente a `gpt-image-2` por defecto, con una mejor relación calidad-precio, sin cambios en el precio. ### Valores soportados para `size` 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. **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`.** Restricciones de tamaño: los tamaños personalizados deben cumplir 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; si se excede, se devolverá 4xx. | 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`, y se pasa `size` como `2048x2048`, el modelo redibujará según las instrucciones de edición y devolverá una imagen de 2K; si se pasa `size` como `3840x2160`, devolverá una imagen de 4K en formato horizontal. Los cargos son los mismos para los tres. > Si se pasa `auto` (o se omite `size`), la salida **mantendrá la relación de aspecto de la imagen de referencia**: en el ejemplo anterior, si la imagen original es 1:1, se obtendrá un resultado 1:1, y no se comprimirá a otro formato. Esto es diferente de la interfaz de generación: la interfaz de generación no tiene imagen de referencia, y `auto` selecciona el formato según el significado de las palabras clave. Si deseas cambiar el formato, debes especificar explícitamente `size`. > **Sobre el parámetro `n`** > La interfaz de edición de `gpt-image-2` soporta `n > 1`: se pueden devolver múltiples resultados de edición en una sola solicitud y se cobrará según la cantidad de resultados (valores de `n` de 1 a 10). Esto 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`. Ten en cuenta que `response_format=b64_json` solo soporta `n=1`, y para `n>1` se debe usar la devolución de URL por defecto. Si algunas imágenes fallan en su generación, solo se devolverán y cobrarán las partes exitosas. 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`、`n`。 > > * `image` se puede subir 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 en el campo del formulario. > * No se soportan parámetros como `mask`、`size`、`response_format`; si se rellenan, serán ignorados. `n > 1` es soportado (1–10), se devolverán y se facturarán los resultados de edición correspondientes. > * 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=add a green leaf on top of the apple" \ -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": "add a green leaf on top of the apple" } ] } ``` 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": "add a green leaf on top of the apple" } 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=Create a lovely gift basket with these this items in it' ``` 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 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: > **Nota**: `image[]` puede aparecer varias veces para subir múltiples imágenes de referencia, por ejemplo `-F "image[]=@a.png" -F "image[]=@b.png"`, la serie de modelos GPT Image admite un máximo de 16 imágenes (cada una no más de 50MB, en formato png/webp/jpg). Superar esta cantidad devolverá 400.

Código de ejemplo de llamada en Python con el mismo efecto: ```python theme={null} import base64 from openai import OpenAI client = OpenAI() prompt = """ Generate a photorealistic image of a gift basket on a white background labeled 'Relax & Unwind' with a ribbon and handwriting-like font, containing all the items in the reference pictures. """ 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 usar 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 admite dos modelos: `gpt-image-1` y `gpt-image-2`, donde `gpt-image-2` es el modelo recomendado para su uso, consulte la sección anterior [Modelo GPT-Image-2](#gpt-image-2-模型). ## 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, se 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 `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 específicamente a través de un ejemplo. 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. Aquí, para facilitar la demostración, se utiliza un sitio web de muestra 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) 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 se ingresan 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 de 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 de 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, 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, 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 ```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, ha 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 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.