> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Solicitud y Uso de la API OpenAI Images Edits > OpenAI generation 集成指南 - XHuoAPI El servicio de edición de imágenes de OpenAI permite enviar cualquier cantidad de imágenes e instrucciones, y obtener imágenes modificadas como resultado. Actualmente, la API soporta simultáneamente 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 las funciones oficiales de edición de imágenes de OpenAI. ## Proceso de Solicitud Para usar la API OpenAI Images Edits, primero puede ir a la página [OpenAI Images Edits API](https://api.xhuoapi.ai/documents/251f1efa-aaa6-462e-8af4-66854b1bc94d) y hacer clic en el botón "Acquire" para obtener las credenciales necesarias para las solicitudes: ![](https://cdn.xhuoapi.ai/nyq0xz.png) Si aún no ha iniciado sesión o registrado, será redirigido automáticamente a la página de inicio de sesión para registrarse y entrar; después de iniciar sesión, volverá automáticamente a esta página. Al solicitar por primera vez, se otorgará 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 estructural**: 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 carga de archivos con `multipart/form-data`, `gpt-image-2` **soporta pasar URLs de imágenes en formato JSON**, sin necesidad de descargar la imagen localmente, ideal para integración en pipelines del servidor. * **Soporte para redibujo en alta resolución**: Puede enviar una imagen original de 1K y solicitar salida en 2K o 4K mediante el parámetro `size`, el modelo ampliará la imagen durante el proceso de edición. ### Valores soportados para `size` y niveles de facturación Las restricciones para `size` en la API de edición son idénticas a las de la API de generación: `gpt-image-2` acepta `size` como `auto`, vacío, o en formato `WIDTHxHEIGHT`. Cualquier otro formato devolverá error 400. La facturación se divide en dos niveles, independiente de la resolución original, solo según el valor solicitado en `size`: * **Precio estándar 1K**: Cualquier tamaño recomendado 1K de la tabla a continuación, o alias comunes de salida 1K (`1254x1254`, `1672x941`, `941x1672`). * **Nivel superior (1.5×)**: Incluye los presets recomendados 2K / 4K de la tabla, así como cualquier tamaño personalizado `WIDTHxHEIGHT`. Las restricciones rígidas del upstream para tamaños personalizados también aplican: ancho y alto deben ser múltiplos de 16, lado mayor ≤ 3840, y total de píxeles ≤ 8,294,400. | Relación | 1K (precio estándar) | 2K recomendado (×1.5) | 4K recomendado (×1.5) | | -------- | -------------------- | --------------------- | --------------------- | | 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 devolverá una imagen 2K, cobrando en el nivel "otro"; si se pasa `3840x2160`, se obtiene una imagen 4K horizontal, también con cobro "otro"; si se pasa `auto` o se omite, se cobra al precio estándar 1K. > **Sobre el parámetro `n`** > > Actualmente, la API de edición `gpt-image-2` **no soporta `n > 1`**: este parámetro será ignorado silenciosamente, y sin importar si se envía `n=1` o `n=10`, la respuesta solo devolverá una imagen y se cobrará solo una. Si necesita múltiples resultados candidatos, debe realizar múltiples solicitudes concurrentes. Esta restricción también aplica para `gpt-image-1` / `gpt-image-1.5` y la serie `nano-banana`. `dall-e-2` es actualmente el único modelo de edición que soporta nativo `n > 1`. A continuación, se presentan dos ejemplos reales desde diferentes perspectivas para apreciar la capacidad de edición de `gpt-image-2`. ### Método 1: JSON + URL de imagen (recomendado) Envía la solicitud con `Content-Type: application/json`, colocando 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 cambiarla a un esquema de “modo nocturno”. La llamada sería: ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "image": "https://platform.cdn.xhuoapi.ai/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 con Python: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/openai/images/edits" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-image-2", "image": "https://platform.cdn.xhuoapi.ai/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.xhuoapi.ai/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png" } ], "elapsed": 83.859 } ``` Imagen editada:

Se observa que la estructura de módulos, la división de información y la tipografía se mantienen estrictamente, solo se invierte el esquema 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 simultáneamente para que el modelo las considere en conjunto. ### Método 2: JSON + múltiples imágenes de referencia `gpt-image-2` soporta usar múltiples imágenes de referencia para generar el 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.xhuoapi.ai/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 observa que el estilo y ambiente se cambiaron completamente según el prompt, pero la cantidad de libros por nivel (1 / 3 / 7) se mantiene estrictamente, y se añadió una pequeña suculenta en la repisa superior como se solicitó. ### Método 3: multipart/form-data (compatible con OpenAI SDK) Si ya usa el SDK oficial de OpenAI para Python, el método tradicional de carga con `multipart/form-data` sigue funcionando, solo cambie `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) ``` Al usar el SDK, debe importar dos variables de entorno: `OPENAI_BASE_URL` configurado como `https://api.xhuoapi.ai/v1/openai` y `OPENAI_API_KEY` con el token obtenido: ```shell theme={null} export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai export OPENAI_API_KEY={token} ``` ## Serie de modelos Nano Banana La serie `nano-banana` también está integrada en `/openai/images/edits`; solo cambie el valor de `model` por cualquiera de los siguientes: | Modelo | Costo (Créditos / solicitud) | Escenario de uso | | ----------------- | ---------------------------- | -------------------------------------------------------------- | | `nano-banana` | 0.14 | Edición de imágenes común, más rápido y económico | | `nano-banana-2` | 0.28 | Mejor calidad y detalles | | `nano-banana-pro` | 0.35 | Tope de gama, mejor preservación de estructura, texto y estilo | > **Importante: rango de parámetros soportados** > > Nano Banana se conecta a través de una capa adaptadora al protocolo OpenAI, soportando solo los parámetros: `model`, `prompt`, `image`. > > * `image` puede enviarse como archivo con `multipart/form-data` (internamente convertido a `data:;base64,...` para upstream), o como URL de imagen en un campo de formulario. > * No soporta `mask`, `n`, `size`, `response_format` ni otros; serán ignorados si se envían. > * La estructura de respuesta sigue el formato OpenAI (`data[].url`), pero `created` siempre es `0`, no devuelve `b64_json` y `revised_prompt` siempre es igual al `prompt` original. ### Llamada con formulario + URL de imagen ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" ``` Respuesta: ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.xhuoapi.ai/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.xhuoapi.ai/v1/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, con el mismo flujo que otros modelos, como se explica en la sección [Callback asíncrono](#callback-asíncrono). ## Uso básico A continuación, puede realizar llamadas con código. Aquí un ejemplo 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.xhuoapi.ai/v1/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 API por primera vez, debe completar al menos cuatro campos: `authorization` (selección directa en el menú desplegable), `model` (modelo oficial de OpenAI, aquí principalmente uno, ver modelos disponibles), `prompt` (texto que describe la imagen a generar) y `image` (ruta de la imagen a editar). La imagen a editar es la siguiente:

Código Python equivalente para la misma llamada: ```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, debe importar dos variables de entorno: `OPENAI_BASE_URL` configurado como `https://api.xhuoapi.ai/v1/openai` y `OPENAI_API_KEY` con el token obtenido en `authorization`. En Mac OS, puede establecerlas con: ```shell theme={null} export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai export OPENAI_API_KEY={token} ``` Después de la llamada, verá que se genera un archivo `gift-basket.png` en el directorio actual, con el siguiente resultado:

Así, hemos completado la operación de edición de imagen. Actualmente, la API Edits soporta tres modelos: `dall-e-2`, `gpt-image-1` y `gpt-image-2`, siendo `gpt-image-2` el modelo 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 la API OpenAI Images Edits puede tardar, si la API no responde rápidamente, la conexión HTTP se mantiene abierta, consumiendo recursos. Por ello, esta API también soporta callbacks asíncronos. El flujo es: el cliente envía la solicitud incluyendo un campo `callback_url`. La API responde inmediatamente con un resultado que incluye un `task_id` que identifica la tarea. Cuando la tarea termina, el resultado de la edición se envía mediante POST en formato JSON al `callback_url` especificado, incluyendo el mismo `task_id` para relacionar la tarea. Veamos un ejemplo. Primero, el webhook es un servicio HTTP que puede recibir solicitudes; el desarrollador debe reemplazarlo por la URL de su propio servidor HTTP. Para la demostración, usamos el sitio público [https://webhook.site/](https://webhook.site/), que genera una URL de webhook, como esta: ![](https://cdn.xhuoapi.ai/cjjfly.png) Copie esta URL, por ejemplo `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`, para usarla como webhook. Luego, incluya el campo `callback_url` con esta URL en la solicitud, junto con los demás parámetros: ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/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" } ``` Tras unos segundos, podrá ver en la URL del webhook el resultado de la edición, con contenido como: ```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 que incluye el campo `task_id` y el campo `data` con el resultado de la edición, igual que en la llamada síncrona, permitiendo relacionar la tarea por ID. ## Manejo de errores Al llamar a la API, si ocurre un error, la API devolverá 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 ha excedido 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, ha aprendido cómo usar la API OpenAI Images Edits para aprovechar fácilmente las funciones oficiales de edición de imágenes de OpenAI. Esperamos que esta guía le ayude a integrar y utilizar mejor esta API. Si tiene alguna duda, no dude en contactar a nuestro equipo de soporte técnico.