> ## Documentation Index > Fetch the complete documentation index at: https://germeytechnology-docs-remove-4o-image-nav.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Solicitud y uso de la API OpenAI Images Edits > OpenAI generation 集成指南 - Ace Data Cloud El servicio de edición de imágenes de OpenAI permite enviar cualquier cantidad de imágenes e instrucciones para obtener imágenes modificadas. Actualmente, la API soporta los modelos `dall-e-2`, `gpt-image-1`, el más reciente **`gpt-image-2`**, así como la serie de modelos **`nano-banana` / `nano-banana-2` / `nano-banana-pro`** integrados a través de la misma interfaz. Este documento describe principalmente el flujo de uso de la API OpenAI Images Edits, con la cual podemos utilizar fácilmente la función oficial de edición de imágenes de OpenAI. ## Proceso de solicitud Para usar la API OpenAI Images Edits, primero puedes ir a la página [OpenAI Images Edits API](https://platform.acedata.cloud/documents/openai-images-edits) y hacer clic en el botón "Acquire" para obtener las credenciales necesarias para las solicitudes: ![](https://cdn.acedata.cloud/nyq0xz.png) Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión para registrarte o iniciar sesión; tras hacerlo, volverás automáticamente a esta página. Al solicitar por primera vez, recibirás un crédito gratuito para usar la API sin costo. ## Modelo GPT-Image-2 `gpt-image-2` presenta mejoras muy notables en escenarios de edición de imágenes en comparación con `gpt-image-1`: * **Mayor estabilidad en la estructura**: Al cambiar piel, colores o fondo, casi no se altera la composición ni el diseño original. * **Mejor preservación del texto**: En imágenes con texto como infografías, carteles o menús, el texto permanece claro y legible tras la edición. * **Soporte para URL directo**: Además de la tradicional subida de archivos `multipart/form-data`, `gpt-image-2` **permite pasar la URL de la imagen en formato JSON**, sin necesidad de descargarla localmente, ideal para integraciones en backend. * **Redibujo en alta resolución**: Se puede enviar una imagen original 1K y mediante el parámetro `size` solicitar salida en 2K o 4K; el modelo realizará la ampliación durante la edición. ### Valores soportados para `size` Las restricciones de `size` en la API de edición son idénticas a las de la generación: `gpt-image-2` acepta `size` como `auto`, vacío o en formato `WIDTHxHEIGHT`; cualquier otro formato devuelve error 400. **Todos los tamaños (1K / 2K / 4K / personalizados) se cobran por imagen, independientemente de la resolución original o el valor solicitado en `size`.** Las restricciones superiores para tamaños personalizados también aplican: ancho y alto deben ser múltiplos de 16, lado largo ≤ 3840, y total de píxeles ≤ 8,294,400. | Relación | Recomendado 1K | Recomendado 2K | Recomendado 4K | | -------- | -------------- | -------------- | -------------- | | 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á y entregará una imagen 2K; si se pasa `3840x2160`, se genera una imagen 4K horizontal; si se pasa `auto` o se omite, el modelo selecciona automáticamente. Los tres casos tienen el mismo costo. > **Sobre el parámetro `n`** > > Actualmente, la API de edición `gpt-image-2` **no soporta `n > 1`**: este parámetro se ignora silenciosamente, y siempre se devuelve una sola imagen por solicitud, cobrando solo por una. Si necesitas múltiples resultados, debes realizar solicitudes concurrentes. Esta limitación también aplica para `gpt-image-1` / `gpt-image-1.5` y la serie `nano-banana`. Solo `dall-e-2` soporta nativamente `n > 1` en edición. A continuación, mostramos dos ejemplos reales para apreciar la capacidad de edición de `gpt-image-2`. ### Modo de llamada 1: JSON + URL de imagen (recomendado) Envía la solicitud con `application/json`, asignando en el campo `image` la URL de una imagen; el modelo descargará la imagen y la editará según el `prompt`. Por ejemplo, esta imagen original es una infografía generada con `gpt-image-2`:

Queremos convertirla a un esquema de “modo nocturno”. La llamada sería: ```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": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "size": "1024x1536" }' ``` O en 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": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "size": "1024x1536" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Respuesta: ```json theme={null} { "success": true, "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753", "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8", "created": 1777048863, "data": [ { "revised_prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "url": "https://platform.cdn.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png" } ], "elapsed": 83.859 } ``` Imagen editada:

Se observa que la estructura, división de información y tipografía se mantienen estrictamente, solo se invierte la paleta de colores a un tema oscuro. > **Consejo**: El campo `image` también acepta un arreglo, por ejemplo `"image": ["url1", "url2", "url3"]`, hasta 16 imágenes de referencia para que el modelo las considere en conjunto. ### Modo de llamada 2: JSON + múltiples imágenes de referencia `gpt-image-2` puede usar varias imágenes como referencia para generar un resultado final, por ejemplo, combinar varias fotos de productos en una sola cesta 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": "Combine all the items above into a single 'Relax & Unwind' gift basket on a clean white background, photorealistic, soft natural lighting.", "size": "1024x1024" } ``` ### Ejemplo de escenario: cambio de estilo manteniendo estructura Otro ejemplo: reemplazar una estantería de madera por una moderna flotante, manteniendo estrictamente la cantidad y disposición de libros en cada nivel. 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": "Replace the wooden bookshelf with a sleek modern white floating shelf mounted on a pastel blue wall. Keep the exact same arrangement of books (1 book on top, 3 in middle, 7 on bottom). Add a small potted succulent on the top shelf next to the book. Bright airy daylight from the left.", "size": "1024x1024" } ``` Resultado de la edición (`task_id`: `e9544dba-727e-44a2-81e1-223d49869380`):

Se aprecia que el estilo y ambiente se cambiaron según el prompt, pero la cantidad de libros en cada nivel (1 / 3 / 7) se mantiene, y se añadió la suculenta solicitada. ### Modo de llamada 3: multipart/form-data (compatible con OpenAI SDK) Si usas el SDK oficial de OpenAI para Python, la subida tradicional `multipart/form-data` también funciona, solo cambia el `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="Convert this image to dark mode while keeping the layout intact." ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) with open("edited.png", "wb") as f: f.write(image_bytes) ``` Para usar el SDK, primero configura dos variables de entorno: `OPENAI_BASE_URL` a `https://api.acedata.cloud/openai` y `OPENAI_API_KEY` con el token obtenido: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={token} ``` ## Serie Nano Banana La serie `nano-banana` también está integrada en `/openai/images/edits`; solo cambia el `model` a cualquiera de los siguientes: | Modelo | Costo (Créditos / llamada) | Escenario de uso | | ----------------- | -------------------------- | -------------------------------------------------------------- | | `nano-banana` | 0.14 | Edición común, más rápido y económico | | `nano-banana-2` | 0.28 | Mejor calidad y detalle | | `nano-banana-pro` | 0.35 | Tope de gama, mejor preservación de estructura, texto y estilo | > **Importante: parámetros soportados** > > Nano Banana usa una capa adaptadora para el protocolo OpenAI y solo soporta los parámetros: `model`, `prompt`, `image`. > > * `image` puede subirse como archivo `multipart/form-data` (internamente convertido a `data:;base64,...`) o pasarse como URL en campo de formulario. > * No soporta `mask`, `n`, `size`, `response_format`, etc.; si se envían, se ignoran. > * La respuesta sigue el formato OpenAI (`data[].url`), pero `created` siempre es `0`, no devuelve `b64_json`, y `revised_prompt` es igual al prompt original. ### Llamada con 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" ``` Respuesta: ```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 con 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 con `callback_url` también funciona para nano-banana, el flujo es idéntico al de otros modelos, ver sección [Callback asíncrono](#callback-asíncrono). ## Uso básico A continuación, un ejemplo de llamada con 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 la API por primera vez, debes completar al menos cuatro campos: `authorization` (seleccionado del menú desplegable), `model` (modelo OpenAI a usar, aquí principalmente uno de los modelos listados), `prompt` (texto que describe la imagen a generar) y `image` (ruta de la imagen a editar), como la imagen mostrada a continuación:

Código equivalente en Python: ```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 configura dos variables de entorno: `OPENAI_BASE_URL` a `https://api.acedata.cloud/openai` y `OPENAI_API_KEY` con el token obtenido: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={token} ``` Tras la llamada, se generará en el directorio actual la imagen `gift-basket.png`, con el siguiente resultado:

Así completamos la edición de la imagen. Actualmente, la API Edits soporta tres modelos: `dall-e-2`, `gpt-image-1` y `gpt-image-2`, siendo este último el recomendado, como se explicó en la sección [Modelo GPT-Image-2](#modelo-gpt-image-2). ## Callback asíncrono Dado que la edición de imágenes con OpenAI Images Edits API puede tardar, si la API no responde rápido, la conexión HTTP se mantiene abierta, consumiendo recursos. Por ello, la API soporta callbacks asíncronos. El flujo es: el cliente envía la solicitud incluyendo el campo `callback_url`. La API responde inmediatamente con un `task_id` que identifica la tarea. Cuando la edición termina, el resultado se envía en formato JSON mediante POST a la URL indicada en `callback_url`, incluyendo el `task_id` para relacionar la tarea. Ejemplo: Primero, el webhook es un servicio HTTP que recibe solicitudes; el desarrollador debe usar su propio servidor. Para demostración, usamos el sitio público [https://webhook.site/](https://webhook.site/), que genera una URL webhook como esta: ![](https://cdn.acedata.cloud/cjjfly.png) Copia esta URL, por ejemplo `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`. Luego, envía la solicitud con `callback_url`: ```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" ``` La respuesta inmediata será: ```json theme={null} { "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c" } ``` Después de un momento, en la URL webhook se recibirá el resultado: ```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 observa el campo `task_id` y el campo `data` con el resultado de la edición, igual que en la llamada síncrona, permitiendo relacionar el resultado con la tarea. ## Manejo de errores Si ocurre un error, la API devuelve un código y mensaje correspondiente, por ejemplo: * `400 token_mismatched`: Solicitud incorrecta, posiblemente por parámetros faltantes o inválidos. * `400 api_not_implemented`: Solicitud incorrecta, posiblemente por parámetros faltantes o inválidos. * `401 invalid_token`: No autorizado, token inválido o ausente. * `429 too_many_requests`: Demasiadas solicitudes, se excedió el límite de tasa. * `500 api_error`: Error interno del 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 Con este documento, has aprendido cómo usar la API OpenAI Images Edits para aprovechar fácilmente la función oficial de edición de imágenes de OpenAI. Esperamos que esta guía te ayude a integrar y usar mejor esta API. Si tienes alguna duda, no dudes en contactar a nuestro equipo de soporte técnico.