Solicitud y Uso de la API OpenAI Images Edits

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 y hacer clic en el botón “Acquire” para obtener las credenciales necesarias para las solicitudes:

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:

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:

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:

{
  "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:

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:

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:

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:

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:<mime>;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

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:

{
  "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

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.

Uso básico

A continuación, puede realizar llamadas con código. Aquí un ejemplo con CURL:

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[][email protected]" \
  -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:

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:

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.

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/, que genera una URL de webhook, como esta:

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:

curl -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[][email protected]" \
  -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á:

{
  "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:

{
  "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

{
  "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.

Documentation Index

​Proceso de Solicitud

​Modelo GPT-Image-2

​Valores soportados para size y niveles de facturación

​Método 1: JSON + URL de imagen (recomendado)

​Método 2: JSON + múltiples imágenes de referencia

​Ejemplo de escenario: cambio de estilo manteniendo estructura

​Método 3: multipart/form-data (compatible con OpenAI SDK)

​Serie de modelos Nano Banana

​Llamada con formulario + URL de imagen

​Llamada con formulario + archivo local

​Callback asíncrono

​Uso básico

​Callback asíncrono

​Manejo de errores

​Ejemplo de respuesta de error

​Conclusión

Proceso de Solicitud

Modelo GPT-Image-2

Valores soportados para `size` y niveles de facturación

Método 1: JSON + URL de imagen (recomendado)

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

Ejemplo de escenario: cambio de estilo manteniendo estructura

Método 3: multipart/form-data (compatible con OpenAI SDK)

Serie de modelos Nano Banana

Llamada con formulario + URL de imagen

Llamada con formulario + archivo local

Callback asíncrono

Uso básico

Callback asíncrono

Manejo de errores

Ejemplo de respuesta de error

Conclusión