GPT Image 2 / 2.5: generación y edición de imágenes

Elija el endpoint antes de escribir la solicitud: texto a imagen usa /images/generations; imagen a imagen usa /images/edits con archivos de imagen cargados. Mencionar "imagen de referencia 1" en un prompt no adjunta ninguna imagen.

Modelos y endpoints

ID de modelo	Texto a imagen	Imagen a imagen
gpt-image-2	/images/generations	/images/edits + archivos de imagen
gpt-image-2.5-sunburst	/images/generations	/images/edits + archivos de imagen
gpt-image-2.5-flare	/images/generations	/images/edits + archivos de imagen

Estos son IDs de modelo distintos. Cambie model explícitamente al cambiar de modelo; GPT Image 2.5 no es un alias de GPT Image 2. Consulte la disponibilidad actual y los precios de la cuenta en el marketplace.

Operación	Método y endpoint	Formato de solicitud
Texto a imagen	POST https://apimaster.ai/v1/images/generations	JSON
Imagen a imagen / edición	POST https://apimaster.ai/v1/images/edits	multipart/form-data con archivos de imagen reales
Edición de imagen asíncrona	POST https://apimaster.ai/v1/images/edits/async	Mismos archivos multipart que las ediciones; devuelve un ID de tarea
Texto a imagen asíncrono	POST https://apimaster.ai/v1/images/generations/async	JSON; devuelve un ID de tarea
Consultar una tarea	GET https://apimaster.ai/v1/tasks/{task_id}?model=MODEL_ID	Autenticación Bearer

Para una respuesta de tarea de edición de imágenes, use /images/edits/async. Cargue los mismos archivos y campos que las ediciones síncronas y luego consulte /tasks/{task_id}. No mueva una solicitud de edición a generations/async. Estos endpoints de tarea reutilizan el contrato asíncrono existente: un upstream asíncrono puede devolver su tarea con rapidez, mientras que un upstream síncrono puede terminar la edición antes de que el gateway devuelva un ID de tarea. No son una promesa de ejecución inmediata en segundo plano. No use Chat Completions para estos modelos.

Autenticación y tiempos de espera

Cree una clave de API y envíe Authorization: Bearer YOUR_API_KEY. Las solicitudes de generación JSON usan Content-Type: application/json. Para las cargas de archivos, deje que cURL o su librería HTTP generen el boundary multipart; no establezca manualmente la cabecera Content-Type.

Permita al menos 180 segundos para solicitudes básicas, 300 segundos para mayor resolución y 600 segundos para ediciones exigentes o alta calidad. Un timeout del cliente no prueba que la solicitud al upstream se haya detenido. Evite envíos duplicados inmediatos.

Texto a imagen: generación JSON

curl --fail-with-body --max-time 300 "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor orange cat sitting on a windowsill at sunset",
    "n": 1,
    "size": "1024x1024"
  }'

Para Sunburst o Flare, reemplace el ID del modelo con gpt-image-2.5-sunburst o gpt-image-2.5-flare. No añada imágenes de referencia a este ejemplo; use los ejemplos de edición de abajo.

Imagen a imagen: cargar una referencia

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change only the background to pale mint green. Preserve the subject, lettering and layout of the reference image." \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "image=@reference.png;type=image/png"

Reemplace reference.png con una imagen local existente. El @ indica a cURL que cargue los bytes del archivo; image=reference.png envía solo una cadena con el nombre del archivo. Este patrón de endpoint también aplica a gpt-image-2 e gpt-image-2.5-sunburst.

Imagen a imagen: cargar múltiples referencias

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Create one comic page. Reference 1 defines character A, reference 2 defines character B, and reference 3 defines the setting. Preserve each character's appearance." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

Repita el mismo campo image[] para cada archivo, en el orden descrito por el prompt. n es el número de imágenes de salida, no el número de referencias. Los límites de referencias dependen del modelo seleccionado y de la ruta disponible; no asuma un límite universal de 16 imágenes. Comience con una referencia e n=1, y luego añada entradas según sea necesario.

Ejemplo de edición en Python

Instale requests. Este ejemplo carga un archivo real y maneja tanto respuestas de imagen URL como base64.

import base64
import os
from pathlib import Path
import requests

api = "https://apimaster.ai/v1"
headers = {"Authorization": "Bearer " + os.environ["APIMASTER_API_KEY"]}
with open("reference.png", "rb") as image:
    response = requests.post(
        f"{api}/images/edits",
        headers=headers,
        data={
            "model": "gpt-image-2.5-flare",
            "prompt": "Change only the background to pale mint green. Preserve the subject and lettering.",
            "n": 1,
            "size": "1024x1024",
        },
        files={"image": ("reference.png", image, "image/png")},
        timeout=(20, 600),
    )
response.raise_for_status()
item = response.json()["data"][0]
if item.get("b64_json"):
    Path("result.png").write_bytes(base64.b64decode(item["b64_json"]))
elif item.get("url"):
    print(item["url"])
else:
    raise RuntimeError("No image returned: " + str(response.json()))

Para varios archivos, pase una lista de entradas ("image[]", (filename, file_object, mime_type)) repetidas a files. Mantenga cada archivo abierto hasta que la solicitud se complete.

Edición de imagen asíncrona

Use este endpoint con GPT Image 2, Sunburst o Flare cuando su aplicación consuma IDs de tarea. Las reglas de carga de archivos, el orden de las referencias, los límites de capacidades y la autenticación son los mismos que en las ediciones síncronas.

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Combine the three reference images into one poster, preserving their subjects and order." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

El envío devuelve data[0].task_id. Consulte con el mismo ID de modelo:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2.5-flare" \
  -H "Authorization: Bearer YOUR_API_KEY"

Una tarea rastreada completada tiene esta forma; se incluye cada imagen generada:

{
  "data": {
    "status": "succeeded",
    "result": {
      "images": [{"url": "https://your-image-host.example/result.png"}]
    }
  }
}

La tarea pertenece a la cuenta que la envió. Consúltela con una clave de API válida para esa cuenta. Un envío fallido devuelve un error en lugar de una tarea utilizable; una vez que se ha devuelto un ID de tarea, siga consultando esa tarea en lugar de volver a enviar la edición. Vea la tabla de estados de consulta abajo.

Integraciones existentes con URL o base64

Si su entrada es una URL, descargue la imagen en su aplicación y cargue sus bytes a /images/edits. Si es un data URI base64, decodifique el payload en un archivo o buffer de bytes y cárguelo. No envíe la URL o el texto base64 como si fuera una carga de archivo.

Algunas rutas de GPT Image 2 admiten la extensión image_urls en generations. Ese no es un contrato portable de edición de imágenes y no debe asumirse que funciona con GPT Image 2.5. Las nuevas integraciones deben usar los ejemplos de ediciones multipart de arriba. Una solicitud JSON que contenga image_urls, image o images no es equivalente a cargar archivos a edits.

Parámetros y límites de capacidades

Campo	Uso
model	Obligatorio; use un ID de modelo exacto de la tabla de arriba
prompt	Obligatorio; describa el resultado y el orden de las referencias
image / image[]	Archivos reales cargados para las ediciones; use PNG o JPEG para los ejemplos básicos
n	Cantidad de imágenes de salida; comience con 1; el máximo depende de la ruta
size	Opcional; 1024x1024 es el ejemplo básico; otras dimensiones de píxeles o relaciones de aspecto dependen de la ruta
resolution	Extensión opcional específica de la ruta, como 1k, 2k, 4k; no todos los modelos/rutas admiten todos los niveles
quality	Opcional; los valores aceptados y el costo dependen de la ruta
background, output_format, output_compression	Opcional; la transparencia y la codificación de salida requieren soporte de la ruta
mask	Solo GPT Image 2, cuando una ruta de edits disponible admita máscaras cargadas; no es compatible con el manejador multipart actual de GPT Image 2.5

Para GPT Image 2, el soporte de máscaras debe verificarse por separado de la edición de referencias ordinaria. Una máscara PNG compatible debe coincidir con las dimensiones de entrada e incluir un canal alfa. El endpoint multipart actual de GPT Image 2.5 rechaza los archivos de máscara cargados; no añada una máscara a los ejemplos de Sunburst o Flare de arriba. No asuma que una solución JSON con mask_url es compatible sin verificar la ruta elegida.

Envíe solo los campos opcionales que necesite. Pueden cambiar las rutas elegibles y el precio; establecer un valor predeterminado explícitamente no siempre es equivalente a omitirlo. Ninguna tabla fija de tamaños de píxeles ni lista de parámetros avanzados aplica de manera uniforme a los tres IDs de modelo. Los precios reales y las capacidades admitidas siguen al marketplace y a la respuesta de la solicitud.

Respuestas síncronas

Una generación o edición exitosa devuelve entradas de imagen en data:

{
  "created": 1789890000,
  "data": [{"url": "https://your-image-host.example/result.png"}]
}

Dependiendo de la ruta y el formato de salida, una entrada puede contener en su lugar b64_json. Decodifíquelo a bytes de imagen. Descargue rápidamente las URL de resultados temporales. Una respuesta HTTP 200 o un recuento de imágenes por sí solos no prueban que se preservaron los detalles de las referencias; inspeccione el resultado contra la entrada.

Tareas asíncronas: envío y consulta

Para texto a imagen, envíe JSON sin imágenes de referencia a generations/async. Para edición de imágenes, use el ejemplo multipart de edits/async de arriba. Ambos usan el mismo endpoint de consulta de tarea:

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A watercolor cat on the moon","n":1}'

{
  "code": 200,
  "data": [{"status": "submitted", "task_id": "task_EXAMPLE"}]
}

El sobre de envío normalmente informa submitted; un upstream ya puede informar un estado de finalización. La primera consulta puede estar ya completa. Un ID de tarea no garantiza una respuesta inmediata: si el upstream seleccionado es síncrono, la plataforma espera a que la generación termine antes de devolver la tarea. Mantenga un timeout de envío suficiente.

Consulte con el mismo ID de modelo usado para el envío:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Estado de la tarea	Acción
pending, submitted, processing, in_progress	Espere; consulte de nuevo después de 3–5 segundos
succeeded, success, completed	Lea cada entrada en data.result.images; las tareas rastreadas usan un url de cadena, mientras que las respuestas legacy de upstream pueden usar un array de URL
failed, error, cancelled	Deje de consultar e inspeccione el error

Use un plazo total de consulta finito, como 10 minutos. Si expira, conserve el ID de tarea para verificaciones posteriores en lugar de crear automáticamente otra tarea de pago. Las respuestas de consulta de tarea y las respuestas síncronas de imagen tienen estructuras diferentes.

Solución de problemas con imágenes de referencia

1. Verifique que la ruta real de la solicitud sea /v1/images/edits o /v1/images/edits/async, no generations o generations/async.
2. Verifique que el multipart contenga bytes de archivo bajo image o image[] repetido, con un boundary generado. El texto del prompt, los nombres de archivo y los recuentos de referencias no reemplazan a los archivos.
3. Compruebe el ID de modelo exacto. Una extensión de GPT Image 2 no es automáticamente compatible con Sunburst o Flare.
4. Si los detalles de tarea/log no muestran una vista previa, no concluya que no se envió ninguna imagen: los logs pueden omitir los datos base64 y el contenido de los archivos cargados. A la inversa, un recuento de referencias registrado no establece que un upstream usó las imágenes.
5. Pruebe con una referencia simple que contenga letras o formas distintivas, y pida un cambio de fondo sin describir esos detalles. Compare la salida visualmente.
6. Para soporte, conserve el ID de solicitud (X-Oneapi-Request-Id), el ID de tarea si está presente, el modelo, el endpoint, la marca de tiempo, los campos de solicitud depurados y las imágenes de referencia. Nunca comparta su clave de API.

Para una respuesta 400, inspeccione la compatibilidad del endpoint y los parámetros; 401 indica un fallo de autenticación; 429 indica un límite de tasa/cuota. Para timeouts o fallos del upstream, conserve el ID de solicitud/tarea y compruebe la tarea o el registro de uso existente antes de reenviar.