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 para obtener tu API Token, que debes guardar como respaldo.

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.

📘 Documentación completa: OpenAI Images Edits API →

​

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:

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:

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:

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

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:

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:

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:

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:

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

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:

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

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

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:

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.

​

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/, al abrir este sitio se obtiene una URL de Webhook, como se muestra en la imagen:

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:

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:

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

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

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