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

gpt-image-2.5-sunburst@pro es la ruta Pro del modelo gpt-image-2.5-sunburst en hiapi. Esta guía te lleva desde cero hasta una solicitud ejecutable: cuál es exactamente el id del modelo, qué campos input acepta, un ejemplo de curl/Python listo para ejecutar y los patrones de producción (idempotencia, callbacks, manejo de errores) que necesitas antes de ejecutarlo de forma desatendida.

Qué necesitas preparar primero

• Una cuenta de hiapi y una API key de la consola. Cada solicitud a continuación se autentica con Authorization: Bearer sk-<your key>.
• Eso es todo: no necesitas instalar ningún SDK por separado. Todos los modelos de hiapi se invocan a través del mismo endpoint de tareas asíncronas, así que si ya has llamado a cualquier otro modelo de hiapi, la estructura de esta solicitud te resultará familiar.

Lo único específico de este modelo: @pro es un sufijo de ruta, no un apodo. hiapi expone más de un modo de invocación para ciertos modelos, y gpt-image-2.5-sunburst es uno de ellos: el id del modelo normal y el id con el sufijo @pro aceptan campos input diferentes y se facturan a tarifas distintas. Esta guía está dirigida específicamente a gpt-image-2.5-sunburst@pro; si usas el id sin sufijo gpt-image-2.5-sunburst obtendrás un modo y un esquema diferentes (consulta las FAQ).

Ejemplo mínimo ejecutable

Todos los modelos de generación de hiapi (imagen, vídeo o audio) se invocan a través del mismo endpoint unificado: POST /v1/tasks. Envías el model y el input, recibes inmediatamente un taskId y la generación se ejecuta de forma asíncrona.

Para gpt-image-2.5-sunburst@pro, input acepta:

Campo	Tipo	Obligatorio	Descripción
prompt	string	Sí	De 1 a 32.000 caracteres
image_urls	string[]	No	De 1 a 16 URLs públicas de JPEG/PNG/WebP; incluirlo permite imagen a imagen en lugar de texto a imagen (no se admite SVG)
aspect_ratio	enum	No	Por ejemplo 1:1, 16:9, 9:16, o dimensiones explícitas como 1536x1024; por defecto 1:1
quality	enum	No	low / medium / high / xhigh / max / auto; por defecto medium; antes de aumentarlo, revisa las notas de producción que aparecen más abajo
background	enum	No	transparent, opaque o auto; por defecto auto
output_format	enum	No	png, jpeg o webp; por defecto webp

curl

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sunburst-pro-demo-001" \
  -d '{
    "model": "gpt-image-2.5-sunburst@pro",
    "input": {
      "prompt": "A minimalist product photo of a ceramic pour-over coffee dripper on a light wood table, soft studio lighting",
      "aspect_ratio": "1:1",
      "quality": "medium",
      "output_format": "webp"
    }
  }'

Esto devuelve inmediatamente un taskId:

{ "code": 0, "message": "ok", "data": { "taskId": "task_xxxxxxxx" } }

Luego consulta el resultado mediante polling:

curl -s "https://api.hiapi.ai/v1/tasks/task_xxxxxxxx" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

Cuando data.status sea success, la imagen estará en data.output[0].url. Descárgala de inmediato: esa URL lleva un expireAt y no sirve para referencias permanentes como enlace externo.

Python

import time
import requests

API_KEY = "sk-YOUR_API_KEY"
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def submit_task():
    payload = {
        "model": "gpt-image-2.5-sunburst@pro",
        "input": {
            "prompt": "A minimalist product photo of a ceramic pour-over coffee dripper "
                      "on a light wood table, soft studio lighting",
            "aspect_ratio": "1:1",
            "quality": "medium",
            "output_format": "webp",
        },
    }
    r = requests.post(
        f"{BASE}/tasks",
        headers={**HEADERS, "Idempotency-Key": "sunburst-pro-demo-001"},
        json=payload,
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def poll_task(task_id, timeout_s=180, interval_s=3):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data.get('error')}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = submit_task()
    image_url = poll_task(task_id)
    print("image ready:", image_url)

Patrones de producción

Polling y callbacks. El bucle anterior está bien para scripts y uso de bajo tráfico. Para cualquier escenario del lado del servidor, es preferible un callback al polling: añade un objeto callback en la misma solicitud:

{
  "model": "gpt-image-2.5-sunburst@pro",
  "input": { "...": "..." },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

callback.url debe ser HTTPS, y when: "final" (el único valor admitido actualmente) te notifica una vez tanto si la tarea tiene éxito como si falla: sin bucles de polling ni solicitudes desperdiciadas. hiapi puede entregar el callback varias veces, así que deduplica por taskId en tu lado.

Idempotencia. Añade la cabecera Idempotency-Key en POST /v1/tasks (cualquier cadena de hasta 255 bytes, por ejemplo un id de pedido). Si un timeout de red hace que tu cliente reintente el mismo envío, la plataforma devuelve el taskId original (con la cabecera de respuesta Idempotent-Replay: true) en lugar de crear (y facturar) una segunda tarea. La clave tiene alcance de tu cuenta y caduca a las 24 horas; reutilizarla con un cuerpo de solicitud diferente devuelve 422 IDEMPOTENCY_KEY_MISMATCH en lugar de crear silenciosamente una nueva tarea, así que un desajuste es una señal de que debes revisar tu lógica de reintentos, no reintentar a ciegas.

Errores de autenticación. Una API key mal formada o incorrecta falla rápidamente con 401 y el código de error permission_denied, antes de crear cualquier tarea:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again.",
    "type": "hiapi_error"
  }
}

Si ves esto, la solución casi siempre está en la propia key (variable de entorno mal escrita, key caducada, falta el prefijo sk-), no en el cuerpo de la solicitud. Trátalo como no reintentable hasta que corrijas la key.

Sobre quality. quality es medium por defecto, un valor razonable para publicar: aumentarlo incrementa tanto el coste como el tiempo de generación, así que solo súbelo a high/xhigh/max cuando hayas confirmado en tus propias pruebas que un prompt dado sigue funcionando de forma fiable en ese nivel.

Páginas relacionadas

• Página del modelo gpt-image-2.5-sunburst: capacidades de esta familia de modelos, salidas de ejemplo y todos los modos disponibles.
• Documentación de la API asíncrona unificada: el contrato completo de /v1/tasks que comparten todos los modelos de generación de hiapi (idempotencia, callbacks, códigos de estado).
• Documentación de autenticación: cómo crear y gestionar API keys.
• Guía de la API de gpt-image-2.5-sunburst: si quieres el modo básico (sin @pro), aquí se detalla su esquema independiente basado en resolution.
• Precios: coste actual por imagen según el nivel de quality.

FAQ

¿gpt-image-2.5-sunburst@pro y gpt-image-2.5-sunburst son modelos diferentes? Es la misma familia de modelos, con rutas distintas. El id sin sufijo gpt-image-2.5-sunburst (y su modo /text-to-image) acepta un campo resolution (1K/2K/4K) y no tiene campos quality ni image_urls. @pro lo sustituye por niveles de quality y añade image_urls opcional, así que usa esta ruta cuando quieras controlar el nivel de calidad o hacer imagen a imagen en la misma llamada.

¿Necesito una imagen de referencia? No. Para texto a imagen, omite por completo image_urls. Si incluyes de 1 a 16 URLs de imágenes públicas, pasas a condicionar la salida con imágenes de referencia.

¿Puedo usar este modelo sin una API key? No: cada solicitud requiere una cabecera Authorization: Bearer válida con una API key real de hiapi de tu cuenta. No hay ningún nivel sin autenticación ni libre de key.

¿Cuánto cuesta? El precio varía según el nivel de quality y se mantiene actualizado en la página de precios, en lugar de repetirse aquí; consúltala antes de estimar costes a escala.

¿Qué hago si mi callback nunca llega? La entrega de callbacks no está garantizada de forma inmediata y hiapi puede reintentar la entrega (así que deduplica por taskId). Si necesitas un límite estricto, mantén un polling de respaldo a GET /v1/tasks/:id tras un timeout, en lugar de esperar el callback indefinidamente.

¿Por qué obtengo un estado fail en lugar de un error en el envío? El envío (que devuelve 200/taskId) solo significa que la solicitud se ha aceptado; la generación en sí puede fallar de forma asíncrona. Tras el polling o mediante el callback, comprueba data.status y revisa data.error para conocer el motivo antes de reenviar.