API de edición de imágenes GPT Image 2 / 2.5

OpenAI generation API guide - Ace Data Cloud

​

1. Obtener API Key

Abre la lista de aplicaciones de Ace Data Cloud, entra en una aplicación disponible y copia la API Key.

​

2. Editar usando la URL de una imagen

Imagen original:

curl https://api.acedata.cloud/openai/images/edits \
  -H "Authorization: Bearer 你的 API Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "image": "https://cdn.acedata.cloud/assets/examples/gpt-image/d56455e2-e7f7-4bcd-b935-475b0a1e0948_0-18240dc44b9c.png",
    "prompt": "Keep the mug, tabletop, camera angle, portrait layout, and soft shadow unchanged. Change only the mug color from white to vivid orange and the pale cream background to solid dark navy blue. No text and no logo.",
    "size": "1024x1536"
  }'

Respuesta exitosa:

{
  "success": true,
  "task_id": "49848451-c624-4df9-9dc2-494018daaf4c",
  "trace_id": "5ac021c2-2891-4eed-bfcf-4c6668ac1be1",
  "created": 1788831893,
  "model": "gpt-image-2",
  "data": [
    {
      "url": "https://cdn.acedata.cloud/assets/examples/gpt-image/49848451-c624-4df9-9dc2-494018daaf4c_0-b6d780a732ca.png"
    }
  ],
  "usage": {
    "input_tokens": 775,
    "output_tokens": 1372,
    "total_tokens": 2147
  }
}

Este es el resultado de edición realmente completado a través de Ace Data Cloud el 8 de septiembre de 2026: la taza se vuelve naranja, el fondo se vuelve azul marino oscuro y se mantienen la composición original y el tamaño de 1024×1536:

​

3. Subir una imagen local

Usa multipart/form-data:

curl https://api.acedata.cloud/openai/images/edits \
  -H "Authorization: Bearer 你的 API Key" \
  -F "model=gpt-image-2" \
  -F "image=@input.png" \
  -F "prompt=Replace the background with a bright modern studio"

Se puede enviar repetidamente image; la serie GPT Image admite un máximo de 16 imágenes de referencia. El image en las solicitudes JSON puede ser una única URL o una matriz de URL; los archivos locales se suben mediante multipart.

​

Modelos y métodos de facturación

Modelo	Escenarios aplicables y método de facturación
gpt-image-2	Canal inverso predeterminado, facturación fija por número de imágenes exitosas
gpt-image-2:reverse	Selección explícita del canal inverso, facturación fija por número de imágenes exitosas
gpt-image-2:official	Canal de API oficial, mayor estabilidad, facturación según el uso real de Tokens
gpt-image-2.5-flare	Prioriza la velocidad de generación, facturación fija por número de imágenes exitosas
gpt-image-2.5-flare:official	Canal de API oficial, mayor estabilidad y prioriza la velocidad de generación, facturación según el uso real de Tokens
gpt-image-2.5-sunburst	Prioriza la alta fidelidad y el control preciso, facturación fija por número de imágenes exitosas
gpt-image-2.5-sunburst:official	Canal de API oficial, mayor estabilidad y prioriza la alta fidelidad y el control preciso, facturación según el uso real de Tokens

El precio mostrado de los canales de API oficiales es una estimación previa a la solicitud; el importe final se basa en el uso real de Tokens en la respuesta y en los registros de uso.

​

4. Usar una máscara para edición local

La interfaz oficial Images Edit utiliza mask para especificar las áreas que se permite modificar. Los modelos :official de Ace Data Cloud siguen el mismo contrato multipart:

• mask debe ser un PNG con canal Alpha, con un tamaño máximo de 4 MB;
• El tamaño de la máscara debe ser exactamente igual al de la primera image;
• Los píxeles transparentes con Alpha de 0 indican que se permite editar, y los píxeles no transparentes indican que se deben conservar;
• Las imágenes RGB que solo son en blanco y negro, pero no tienen un canal transparente, no pueden utilizarse como máscaras válidas;
• El prompt debe describir la imagen completa que se espera obtener, al mismo tiempo que aclara las modificaciones locales y el contenido que debe permanecer sin cambios.

A continuación, primero se genera una máscara a partir de la imagen original. El ejemplo establece el rectángulo central como transparente y solo permite que el modelo modifique esa área:

from PIL import Image, ImageDraw

source = Image.open("input.png").convert("RGBA")
mask = Image.new("RGBA", source.size, (0, 0, 0, 255))
draw = ImageDraw.Draw(mask)
width, height = source.size
draw.rectangle(
    (width // 4, height // 4, width * 3 // 4, height * 3 // 4),
    fill=(0, 0, 0, 0),
)
mask.save("mask.png")

Luego sube la imagen original y la máscara juntas:

curl https://api.acedata.cloud/openai/images/edits \
  -H "Authorization: Bearer 你的 API Key" \
  -F "model=gpt-image-2:official" \
  -F "image=@input.png" \
  -F "mask=@mask.png" \
  -F "prompt=Keep the composition, lighting, and all objects outside the transparent mask unchanged. Inside the masked area, replace the empty tabletop with a small blue ceramic vase."

También se puede seguir el método de llamada images.edit del SDK oficial de Python de OpenAI; solo es necesario apuntar base_url a Ace Data Cloud:

from openai import OpenAI

client = OpenAI(
    api_key="你的 API Key",
    base_url="https://api.acedata.cloud/openai",
)

with open("input.png", "rb") as image, open("mask.png", "rb") as mask:
    result = client.images.edit(
        model="gpt-image-2:official",
        image=image,
        mask=mask,
        prompt=(
            "Keep the composition, lighting, and all objects outside the "
            "transparent mask unchanged. Inside the masked area, replace "
            "the empty tabletop with a small blue ceramic vase."
        ),
    )

print(result.data[0].url)

Al usar mask, la imagen original y la máscara deben subirse en la misma solicitud multipart mediante image=@input.png y mask=@mask.png, respectivamente. No mezcles una imagen original por URL con un archivo de máscara local; las solicitudes de edición únicamente por URL no admiten añadir después un archivo mask local. La máscara restringirá el área de edición, pero el modelo de generación aún puede realizar una fusión natural en los bordes; cuando se necesiten límites estrictos, se deben utilizar bordes Alpha claros y repetir en el prompt qué contenido debe permanecer sin cambios.

Los métodos de llamada anteriores son consistentes con los ejemplos de máscaras de la API OpenAI Image Edit y del Cookbook oficial de GPT Image.

​

5. Parámetros comunes

Campo	Descripción
model	gpt-image-2, gpt-image-2.5-flare (más rápido) o gpt-image-2.5-sunburst (mayor fidelidad y control); los tres pueden seleccionar la variante correspondiente :official, y gpt-image-2 también admite :reverse
image	JSON utiliza una única URL o un array de hasta 16 URL; multipart utiliza uno o varios campos de archivo image. Al utilizar mask, se debe cargar un archivo de imagen local
mask	Máscara PNG opcional, solo para carga de archivos multipart; debe incluir un canal Alpha, tener el mismo tamaño que la primera image y no superar 4MB
prompt	Instrucción de edición
size	auto o un WIDTHxHEIGHT que cumpla las restricciones
n	1–10; solo se admite 1 cuando response_format=b64_json
response_format	url o b64_json
callback_url	Dirección de callback asíncrono opcional

Las reglas de tamaño son las mismas que para la API de generación: el ancho y alto deben ser múltiplos de 16, el lado largo no debe superar 3840, el total de píxeles debe ser 655,360–8,294,400 y la relación de aspecto no debe superar 3:1. Cuando se omite size o se utiliza auto, el modelo elegirá el formato basándose en el prompt y la primera imagen de referencia.

gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst y gpt-image-2:reverse se facturan según el número de imágenes exitosas; gpt-image-2:official, gpt-image-2.5-flare:official y gpt-image-2.5-sunburst:official se liquidan según los Tokens reales de entrada de texto, entrada de imágenes de referencia y salida de imágenes; el registro de uso final prevalecerá.

​

6. Callback asíncrono y resolución de errores

Para tareas largas, se puede añadir lo siguiente a la solicitud:

{
  "callback_url": "https://example.com/webhooks/images"
}

La respuesta asíncrona 200 es {"task_id": "..."}; al completarse, se realizará un callback con el resultado final. Las solicitudes síncronas devuelven created y data.

Estado	Verificación
400	Formato/cantidad de imágenes, combinación de parámetros y formato de tamaño; al utilizar mask, compruebe el canal Alpha del PNG, el límite de 4MB y si sus dimensiones coinciden con la primera imagen original
401	API Key y Bearer Header
429	Frecuencia de solicitudes
504	Cambiar al callback asíncrono

Las respuestas de error incluirán trace_id. Proporcione este ID al informar de problemas; no proporcione la API Key.

Para los campos completos y las enumeraciones en tiempo real, consulte la página de OpenAI Images Edits API. Para generar imágenes a partir de texto plano, consulte Generación de imágenes GPT Image 2 / 2.5.