Integración de la API de GPT Image 2.5: generación, edición y migración desde Image 2

Para integrar GPT Image 2.5 en HiAPI, primero elige gpt-image-2.5-flare o gpt-image-2.5-sunburst y luego envía la tarea mediante POST /v1/tasks. Ambos modelos admiten generación y edición; la presencia o ausencia de image_urls determina si la solicitud incluye imágenes de referencia.

Al migrar desde Image 2, es necesario modificar tanto el nombre del modelo como los parámetros de entrada. La versión anterior de resolution, size, los campos de imágenes de referencia y la configuración de rutas tienen convenciones distintas; si solo se reemplaza la cadena del modelo, es fácil que queden parámetros no aplicables.

El siguiente código se basa en la documentación en línea de HiAPI del 9 de septiembre de 2026 y sirve para ilustrar el flujo de solicitudes y el procesamiento asíncrono; la salida real y los costos se rigen por el registro de la tarea. Las actualizaciones de parámetros se rigen por la documentación de Flare y la documentación de Sunburst.

Un solo ID de modelo que cubre generación y edición

Flare y Sunburst tienen los mismos campos de solicitud en HiAPI. Tras elegir un modelo, la generación a partir de solo texto omite image_urls; para editar, se añaden de 1 a 16 imágenes de referencia e indican en el prompt qué se debe modificar y qué se debe conservar. No envíes un arreglo vacío para la generación a partir de solo texto, ni agregues manualmente los sufijos /edit o /text-to-image. Cada tarea produce una imagen.

Si ya tienes un flujo de trabajo de imágenes estable, puedes migrar primero un tipo de tarea y conservar las entradas y los criterios de aceptación originales. Para conocer el posicionamiento de ambos modelos, puedes consultar primero las diferencias entre Image 2 y 2.5; este artículo se centra en cómo implementar las solicitudes.

Envío de una solicitud de generación

El siguiente ejemplo genera una imagen de producto de una taza cuadrada. Guarda el JSON como request.json. quality se establece explícitamente en medium para facilitar la reproducción posterior de los parámetros; aspect_ratio se establece en el tamaño en píxeles 1024x1024 que figura en la documentación.

{
  "model": "gpt-image-2.5-flare/text-to-image",
  "input": {
    "prompt": "A studio product photograph of a matte cobalt blue ceramic mug on a warm gray seamless background. Front three-quarter view, soft light from the left, subtle contact shadow, no text, no logo.",
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

La clave de API se coloca en la variable de entorno del servidor HIAPI_API_KEY. El siguiente comando lee el archivo, envía la solicitud y guarda la respuesta de la creación de la tarea. HIAPI_REQUEST_ID lo genera tu aplicación para esta solicitud lógica; se reutiliza cuando se reintenta la misma solicitud por problemas de red y se usa un valor nuevo cuando se modifican las entradas o se crea otra imagen.

: "${HIAPI_API_KEY:?Set HIAPI_API_KEY on your server}"
: "${HIAPI_REQUEST_ID:?Set a unique ID for this logical request}"
curl --fail-with-body --silent --show-error \
  https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer ${HIAPI_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${HIAPI_REQUEST_ID}" \
  --data-binary @request.json \
  --output created.json

Tras una creación exitosa, lee el ID de la tarea desde data.taskId en created.json. En este momento la imagen aún se está generando de forma asíncrona. Idempotency-Key se utiliza para evitar que la misma solicitud lógica cree varias tareas por envíos duplicados; consulta la convención completa en la documentación de creación de tareas. No confundas el envío exitoso con la finalización de la imagen.

Edición de imágenes con la misma interfaz

A continuación se muestra una solicitud de edición independiente con Sunburst. Reemplaza la dirección de marcador de posición en image_urls por la URL real de una imagen de referencia accesible para el servicio, guárdala como request.json y envíala con un nuevo ID de solicitud. La dirección example.com solo ilustra la estructura de los campos y no puede usarse directamente para generar.

{
  "model": "gpt-image-2.5-sunburst/image-to-image",
  "input": {
    "prompt": "Change only the background behind the mug to pale peach. Preserve the mug shape, cobalt blue color, handle, camera angle, lighting direction, and contact shadow. Do not add text or objects.",
    "image_urls": ["https://example.com/your-mug-reference.webp"],
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

Cuando haya varias imágenes de referencia, indica su uso en el orden del arreglo; por ejemplo, la primera proporciona el producto y la segunda proporciona el fondo. En modificaciones consecutivas, usa la salida guardada del paso anterior como imagen de referencia de la siguiente solicitud; cada vez sigue siendo una tarea nueva y se deben especificar los nuevos requisitos de modificación. No asumas que la interfaz conservará automáticamente la conversación o la imagen de la ronda anterior.

Para un fondo transparente, establece background en transparent y elige PNG o WebP. JPEG no admite canal alfa. Tras la salida del modelo, sigue siendo necesario revisar los bordes y el sujeto; la configuración de los campos no sustituye la validación de la imagen.

Consulta del estado y guardado del archivo

GET /v1/tasks/:id devuelve los detalles de la tarea. queued, handling y archiving son estados no terminales; solo success indica que la salida está disponible, mientras que fail proporciona información del fallo mediante data.error. El code: 200 externo solo indica que la consulta fue exitosa; debes seguir evaluando data.status. Documentación de detalles de la tarea

El siguiente ejemplo de Python usa requests, lee el created.json anterior, espera primero 3 segundos y luego consulta cada 4 segundos. Guarda el JSON de detalles y la primera imagen. Los 10 minutos son el límite de espera local del ejemplo; no representan un SLA del servicio ni cancelan la tarea en el servidor. Tras el tiempo de espera, conserva el taskId y consulta más tarde la misma tarea.

import json
import os
import time
from pathlib import Path

import requests

created = json.loads(Path("created.json").read_text())
if created.get("code") != 200:
    raise RuntimeError(created)
task_id = created["data"]["taskId"]
headers = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
deadline = time.monotonic() + 600
delay = 3

while time.monotonic() < deadline:
    time.sleep(delay)
    response = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers=headers, timeout=30,
    )
    if response.status_code == 503:
        delay = min(delay * 2, 30)
        continue
    response.raise_for_status()
    envelope = response.json()
    if envelope.get("code") != 200:
        raise RuntimeError(envelope)
    task = envelope["data"]
    Path("task-detail.json").write_text(json.dumps(envelope, indent=2))
    status = task["status"]
    if status == "fail":
        raise RuntimeError(task.get("error"))
    if status == "success":
        image = next(x for x in task["output"] if x["type"] == "image")
        # This example requested WebP. Do not forward the API key to the CDN.
        with requests.get(image["url"], stream=True, timeout=60) as result:
            result.raise_for_status()
            with Path("result.webp").open("wb") as output:
                for chunk in result.iter_content(1024 * 1024):
                    output.write(chunk)
        print("Saved result.webp", task_id)
        break
    if status not in {"queued", "handling", "archiving"}:
        raise RuntimeError(f"Unexpected status: {status}")
    delay = 4
else:
    raise TimeoutError(f"Resume polling this task later: {task_id}")

Las salidas temporales deben descargarse o transferirse antes de output[].expireAt. Los servicios en producción pueden configurar callback en el nivel superior de la solicitud para recibir notificaciones de estado terminal, manteniendo el sondeo como respaldo; el campo de callback no debe colocarse dentro de input. La verificación de firma de los callbacks y el manejo de notificaciones duplicadas se implementan según la API asíncrona unificada. El ejemplo no incluye colas de negocio, servicios de callback ni una estrategia completa de reintentos de red.

Migración desde Image 2: verificación de las entradas punto por punto

La versión anterior de Image 2 tiene rutas distintas; al migrar, primero confirma cuál se está usando actualmente. A continuación se enumeran las diferencias de parámetros entre las documentaciones de HiAPI, que no aplican a la transferencia directa de solicitudes de SDK de otros proveedores.

Flujo de trabajo antiguo	Ajuste en Image 2.5
La generación y la edición usan IDs de modelo de Image 2 distintos	Usa el ID completo de Flare o Sunburst; distingue por la presencia o ausencia de image_urls
La edición Standard usa input_urls	Cámbialo a image_urls; la edición ext antigua ya usaba este campo
Standard / ext usan resolution	Vuelve a elegir la proporción o el enumerado de píxeles en aspect_ratio según el tamaño objetivo; no conserves resolution
La generación Beta usa size	Cámbialo a los enumerados de píxeles de aspect_ratio admitidos en la documentación; no copies tamaños arbitrarios directamente
route: "beta" / "ext" explícito, o nombre de modelo con sufijo de ruta	Reconstruye la solicitud según la documentación del modelo 2.5; no uses las rutas antiguas
Proporciones como 4:5 admitidas en la versión anterior	Verifica punto por punto; el enumerado actual de 2.5 no incluye 4:5; no lo cambies silenciosamente por otra proporción
Depender de la calidad, el tamaño o el formato de salida predeterminados	Especifícalos explícitamente y vuelve a revisar la salida, los costos y el procesamiento de archivos posteriores

Las opciones de proporción actuales de 2.5 son 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16 y auto. Además, aspect_ratio acepta los 10 tamaños en píxeles que figuran en la documentación. Si necesitas un tamaño fijo, elige un valor del enumerado; no puedes inferir que cualquier widthxheight sea válido solo por el formato de la cadena. En particular, auto se describe en la nueva documentación como una opción en la que el modelo elige la composición adecuada; no debes heredar directamente la suposición de la ruta de edición antigua de “seguir la imagen de entrada”.

Las opciones de calidad son low, medium, high, xhigh, max y auto, con medium como valor predeterminado. Un nivel de calidad con el mismo nombre no garantiza el mismo costo ni el mismo resultado visual que el modelo antiguo. El protocolo antiguo completo puede consultarse en la documentación de generación con Image 2 y edición con Image 2.

Errores y presupuesto dentro del mismo flujo de validación

Un 400 al enviar indica que se deben revisar el nombre del modelo, los campos y los enumerados; un 402, el saldo; un 415, el Content-Type. Si aparece fail después de crear la tarea, guarda data.error para investigar y no reenvíes la misma entrada inválida. Un 503 puede reintentarse más tarde con retroceso exponencial; si no se puede determinar si el POST creó la tarea debido a una interrupción de red, usa la misma clave de idempotencia para evitar tareas duplicadas. Descripción de errores en la creación de tareas

La verificación de costos comienza en la página de precios actual de HiAPI y en la página del modelo específico. La validación de la migración debe registrar el modelo completo, el tamaño, la calidad, la cantidad de imágenes de referencia, la solicitud, la salida y la factura real; no reutilices el precio unitario de Image 2 antiguo ni tomes el precio inicial de otras plataformas como cotización de HiAPI. Las imágenes de muestra del sitio web pueden ayudar a evaluar los resultados; los tiempos de la API y la facturación requieren sus propios registros reales.

Después de integrar, guardar y validar una tarea de generación y una de edición, amplía al flujo por lotes. Puedes consultar los puntos de entrada actuales en la página del modelo Flare o en la página del modelo Sunburst y luego mantener los parámetros según la documentación correspondiente.