Cómo usar gpt-image-2.5-sunburst con la API de hiapi: curl, Python y ejemplos de solicitud funcionales

Para generar o editar imágenes con gpt-image-2.5-sunburst, envía una tarea con tu prompt a POST /v1/tasks y luego consulta GET /v1/tasks/<id> (o recibe un callback) hasta que la tarea termine, y lee la URL de la imagen desde data.output[0].url. Esta guía cubre la solicitud mínima, el conjunto completo de parámetros y los patrones de producción necesarios antes del lanzamiento (callbacks, idempotencia, manejo de errores).

Requisitos previos

Necesitas una clave de API de hiapi. Crea una desde la consola: cada solicitud se autentica con Authorization: Bearer sk-<your-key>. No hay un nivel gratuito para llamarla desde el navegador ni una forma de hacerlo sin clave; todos los ejemplos siguientes asumen que ya tienes una clave.

Ejemplo mínimo funcional

gpt-image-2.5-sunburst/text-to-image solo requiere prompt dentro de input. La relación de aspecto predeterminada es auto y la resolución predeterminada es 1K.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "input": {
      "prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter, soft morning light"
    }
  }'

Devuelve inmediatamente un id de tarea:

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

Consulta el resultado:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ \
  -H "Authorization: Bearer sk-<your-key>"

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ",
    "status": "success",
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "output": [
      {"type": "image", "url": "https://temp.hiapi.ai/.../output-0.webp", "expireAt": 1789571298}
    ]
  }
}

Versión en Python del mismo flujo de ida y vuelta:

import time
import requests

API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers=HEADERS,
    json={
        "model": "gpt-image-2.5-sunburst/text-to-image",
        "input": {"prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter"},
    },
    timeout=30,
)
task_id = resp.json()["data"]["taskId"]

while True:
    poll = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()
    status = poll["data"]["status"]
    if status in ("success", "fail"):
        break
    time.sleep(2)

if status == "success":
    image_url = poll["data"]["output"][0]["url"]
    print(image_url)
else:
    print("task failed:", poll["data"])

data.output[0].url apunta a almacenamiento temporal: la respuesta incluye expireAt (en segundos Unix). Descarga los bytes y persístelos antes de esa fecha límite (tu propio almacenamiento, S3, R2, etc.); no lo trates como un enlace permanente.

Referencia completa de parámetros

gpt-image-2.5-sunburst tiene dos ids de modelo: gpt-image-2.5-sunburst/text-to-image para generar a partir de un prompt, y gpt-image-2.5-sunburst/image-to-image para editar o componer a partir de imágenes de referencia. Ambos aceptan los mismos campos; la diferencia es que image_urls es obligatorio en image-to-image y no se usa en text-to-image:

Campo	Tipo	Valor predeterminado	Descripción
prompt	string, 1–8000 caracteres	—	Obligatorio. Para ediciones, describe qué debe cambiar y qué debe permanecer exactamente igual.
image_urls	array de URL	—	Solo para image-to-image, obligatorio, de 1 a 16 imágenes JPEG, PNG o WebP, cada una con un máximo de 20 megapíxeles y no más de 30 MB. Debe ser una URL descargable públicamente o un data URI.
aspect_ratio	enumeración	"auto"	auto, 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9, 27:16, 16:27, 9:8, 8:9.
resolution	enumeración	"1K"	1K, 2K, 4K. Esto determina el precio.
background	enumeración	ninguno	transparent, opaque, auto. transparent solo surte efecto con 1K, y en ese caso devuelve un PNG con canal alfa.

Ejemplo de edición: pasa una o varias imágenes de referencia y describe únicamente el cambio que deseas:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "input": {
      "prompt": "Change only the ceramic cup color to matte black. Keep the marble counter, lighting, and camera angle exactly as-is.",
      "image_urls": ["https://your-storage.example.com/cup-original.webp"],
      "resolution": "2K"
    }
  }'

El schema es estricto (additionalProperties: false): los campos desconocidos se rechazan, así que no reutilices parámetros de otros modelos de imagen (por ejemplo, size, strength, n).

Patrones de producción

Usa callbacks en lugar de sondeo en un backend real. Añade un bloque callback para omitir el bucle de sondeo:

{
  "model": "gpt-image-2.5-sunburst/text-to-image",
  "input": {"prompt": "..."},
  "callback": {"url": "https://your-server.example.com/hooks/hiapi", "when": "final"}
}

when: "final" se activa exactamente una vez cuando la tarea alcanza un estado terminal (success o fail). Tu endpoint debe devolver rápidamente 2xx y realizar el trabajo real de forma asíncrona (descargar la salida, actualizar tu propia base de datos); hiapi reintentará los callbacks que no reciban una confirmación rápida.

Haz que los reintentos sean idempotentes. Si la solicitud del cliente expira, no puedes saber si la tarea se creó. Envía el encabezado Idempotency-Key en la solicitud de creación (máximo 255 bytes) y reutiliza la misma clave en los reintentos: con la misma cuenta y clave solo se crea una tarea, y el reintento devuelve el taskId original. Sin esto, procesar el mismo prompt de forma duplicada se cobra dos veces.

Maneja los estados terminales que realmente encontrarás:

• success: lee data.output[0].url y descárgalo a tiempo (respeta expireAt).
• fail: revisa data.error antes de reintentar para entender el motivo del fallo; no reintentes a ciegas ante cada fallo, algunos son problemas a nivel de prompt (por ejemplo, violaciones de políticas) y reintentar tal cual volverá a fallar.
• Consultar un id de tarea inexistente (error tipográfico, expirado) devuelve un HTTP 404 con el contenido {"code":404,"message":"task not found"}.

Los fallos de autenticación son HTTP 401, no errores a nivel de tarea:

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

Comprueba esto en tu manejo de errores antes de asumir que la tarea falló: una clave inválida o revocada nunca llega a la fase de creación de la tarea.

Lecturas relacionadas

• Página del modelo GPT Image 2.5 Sunburst: ejemplos en vivo y precios actuales.
• GPT Image 2.5: generación, edición y migración: si vas a migrar desde rutas anteriores de Image 2 hacia la serie 2.5 (Flare o Sunburst), este artículo cubre las diferencias de parámetros.
• Cómo cambiar el estilo de imágenes con IA: si el modo de edición de Sunburst es solo una parte de tu pipeline, aquí tienes un recorrido más amplio sobre image-to-image.
• Documentación de autenticación y Inicio rápido para conocer el ciclo de vida completo de una solicitud más allá de este modelo concreto.

Preguntas frecuentes

¿gpt-image-2.5-sunburst admite edición de imágenes o solo generación de texto a imagen? Admite ambas cosas, mediante dos ids de modelo. Usa gpt-image-2.5-sunburst/image-to-image con image_urls (de 1 a 16 imágenes de referencia) para editar o componer, y gpt-image-2.5-sunburst/text-to-image para generar solo a partir de texto.

¿Qué pasa si envío un array image_urls vacío en lugar de omitirlo? No lo hagas. En image-to-image, image_urls es obligatorio y requiere al menos una URL. Para generación puramente a partir de texto, usa el id de modelo text-to-image.

¿Cuánto cuesta una imagen? Depende de resolution: $0.05 para 1K, $0.08 para 2K y $0.12 para 4K, igual para text-to-image e image-to-image. Durante la promoción del Día del Programador (hasta el 9 de noviembre de 2026, 00:00 UTC+8), todos los niveles tienen un 50 % de descuento: $0.025, $0.04 y $0.06. Antes de escalar, consulta la página del modelo para ver los precios en vivo.

¿Puedo obtener un tamaño fijo en píxeles en lugar de una relación de aspecto? Sí: además de cadenas de proporción como 16:9, aspect_ratio también acepta dimensiones literales como 1024x1024, 1536x1024 o 3840x2160.

¿Por qué obtengo un 404 al consultar la tarea? O el taskId tiene un error tipográfico, o el endpoint/la región que consultas no tiene esa tarea. Revisa con cuidado el id que guardaste de la respuesta de creación: hiapi no hace expirar silenciosamente los registros de tareas dentro de ninguna ventana de sondeo normal.

¿Puedo llamarla sin una clave de API para probar? No. Cada solicitud a /v1/tasks requiere Authorization: Bearer sk-<key>; no hay modo anónimo ni solo de navegador.