Cómo usar gpt-image-2.5-flare@pro a través de la API de hiapi: curl, Python y una solicitud ejecutable

gpt-image-2.5-flare@pro es uno de los modelos de imagen disponibles a través de la API de tareas unificada de hiapi. Esta guía primero demuestra una solicitud mínima ejecutable con curl y Python, y luego presenta los parámetros y patrones necesarios para entornos de producción: callbacks, idempotencia y manejo de errores.

Qué necesitas preparar

• Una clave de API de hiapi. Puedes obtenerla desde la consola de hiapi; cada clave comienza con sk-.
• Usa https://api.hiapi.ai como URL base. Cada solicitud requiere el encabezado Authorization: Bearer sk-<your-key>.

La generación de imágenes en hiapi (así como todos los demás modelos asíncronos: video, TTS, música) se ejecuta a través del mismo endpoint: POST /v1/tasks. Primero creas una tarea y luego puedes consultar GET /v1/tasks/:id o recibir un callback cuando la tarea finalice. Referencia completa: API asíncrona unificada.

Ejemplo mínimo ejecutable

curl

Crear una tarea:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare@pro",
    "input": {
      "prompt": "a cyan glass data center entrance, cinematic lighting",
      "aspect_ratio": "16:9",
      "quality": "high",
      "output_format": "png"
    }
  }'

Aquí se devuelve un ID de tarea, no la imagen; la generación de imágenes es asíncrona:

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR" }
}

Consultar el resultado:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR \
  -H "Authorization: Bearer $HIAPI_API_KEY"

data.status cambia en el orden queued → handling → archiving → success (o fail). Cuando el estado es success, la imagen se encuentra en data.output[0].url:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "gpt-image-2.5-flare@pro",
    "status": "success",
    "output": [
      { "url": "https://cdn.hiapi.ai/tasks/.../output.png", "type": "image", "expireAt": 1777886899 }
    ]
  }
}

expireAt es una marca de tiempo Unix; descarga el archivo o vuelve a alojarlo antes de que expire, ya que después de eso la URL dejará de funcionar.

Python

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_image_task(prompt: str, aspect_ratio: str = "16:9", quality: str = "high") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={
            "model": "gpt-image-2.5-flare@pro",
            "input": {
                "prompt": prompt,
                "aspect_ratio": aspect_ratio,
                "quality": quality,
                "output_format": "png",
            },
        },
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 120, interval_s: int = 3) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()["data"]
        if data["status"] in ("success", "fail"):
            return data
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_image_task("a cyan glass data center entrance, cinematic lighting")
    result = wait_for_task(task_id)
    if result["status"] == "success":
        image_url = result["output"][0]["url"]
        image_bytes = requests.get(image_url, timeout=30).content
        with open("output.png", "wb") as f:
            f.write(image_bytes)
        print(f"saved output.png from {image_url}")
    else:
        print("task failed:", result.get("error"))

Instala la única dependencia con pip install requests, exporta HIAPI_API_KEY y ejecuta.

Parámetros clave

gpt-image-2.5-flare ofrece dos rutas: la ruta predeterminada (usando directamente el ID de modelo gpt-image-2.5-flare) y la ruta pro (añadiendo @pro, como se muestra en todos los ejemplos anteriores). No existe un sufijo explícito @default; pasarlo devolverá MODEL_UNAVAILABLE.

input acepta los siguientes campos:

• prompt (cadena, obligatorio): el único campo obligatorio.
• aspect_ratio: 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, auto, o dimensiones explícitas en píxeles como 1536x1024, 2048x2048, 3840x2160.
• quality: low, medium, high, xhigh, max o auto.
• output_format: png, jpeg o webp.
• background: auto, transparent u opaque. Usa transparent junto con output_format: png o webp para obtener material recortado.

El esquema es estricto: los campos desconocidos (size, n o cualquier campo no listado) devuelven 400 INVALID_REQUEST con additional properties '<field>' not allowed, en lugar de ignorarse silenciosamente. Si necesitas editar una imagen existente en lugar de generarla desde un prompt en blanco, hiapi lo ofrece como un ID de modelo separado; consulta la página del modelo para la variante de imagen a imagen.

Patrones para producción

Usa callbacks en lugar de polling. Añade un objeto callback en la solicitud de creación:

{
  "model": "gpt-image-2.5-flare@pro",
  "input": { "prompt": "..." },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

when: "final" es actualmente el único valor admitido: cuando la tarea alcanza success o fail, hiapi envía una solicitud POST a tu URL. El cuerpo del callback es idéntico al campo data devuelto por GET /v1/tasks/:id.

Envía el encabezado Idempotency-Key. Si tu solicitud expira y reintentas, la clave de idempotencia evita que hiapi cree (y facture) una segunda tarea para la misma solicitud.

Maneja los errores de forma explícita. Una clave inválida o revocada devuelve HTTP 401:

{
  "error": {
    "code": "permission_denied",
    "type": "hiapi_error",
    "message": "This API key is invalid...",
    "request_id": "..."
  }
}

Un input mal formado devuelve HTTP 400, con error_code: "INVALID_REQUEST" y un message que indica el campo problemático; revísalo antes de reintentar, ya que reintentar un 400 con el mismo cuerpo solo volverá a fallar.

Los precios de gpt-image-2.5-flare@pro (se cobra por imagen generada correctamente, según la resolución y el nivel de calidad) se encuentran en la página de precios.

Documentación relacionada

• Referencia de la API asíncrona unificada: ciclo de vida completo de las tareas, todos los tipos de modelos
• Crear tarea: estructura de solicitud/respuesta de POST /v1/tasks
• Obtener detalles de la tarea: consultar GET /v1/tasks/:id
• Autenticación: formato de las claves de API y encabezados
• Página del modelo gpt-image-2.5-flare@pro

Preguntas frecuentes

¿Cuál es la diferencia entre la ruta predeterminada y @pro? Son dos rutas independientes de la misma familia de modelos, seleccionadas mediante el ID de modelo que envías (gpt-image-2.5-flare frente a gpt-image-2.5-flare@pro). Antes de elegir, consulta la página del modelo y los precios para conocer las diferencias actuales de coste y capacidades.

¿Puedo generar PNG transparentes? Sí: configura "background": "transparent" junto con "output_format": "png" (o "webp").

¿Por qué recibo additional properties 'size' not allowed? El esquema es estricto. Usa aspect_ratio (que también acepta dimensiones explícitas en píxeles como 1024x1024) en lugar del campo size.

¿Cuánto tiempo es válida la URL de salida? Hasta la marca de tiempo Unix expireAt del objeto output[0]. Descárgala o cópiala a tu propio almacenamiento antes de ese momento; hiapi no seguirá sirviendo ese archivo después.

¿Sigue siendo necesario hacer polling si configuré un callback? No, pero aún puedes hacer polling: GET /v1/tasks/:id funciona con normalidad independientemente de si configuraste un callback, lo que te permite revisar manualmente si tu endpoint de callback perdió una entrega.

¿Qué ocurre si mi solicitud incluye tanto input_urls como un prompt incorrecto? La validación se ejecuta sobre todo el cuerpo de la solicitud antes de crear la tarea: cualquier campo inválido (incluidos arrays de medios mal formados) devuelve 400 y no se crea la tarea (tampoco se cobra).