API de texto a imagen de GPT Image 2.5 Sunburst: guía práctica con curl y Python

Si quieres generar imágenes con gpt-image-2.5-sunburst/text-to-image a través de la API de hiapi, esta guía te llevará por una solicitud completa y funcional, usando curl y Python respectivamente: desde la creación de la tarea hasta la descarga de la URL final de la imagen. Cada solicitud y respuesta mostrada aquí se ejecutó realmente contra la API en producción antes de publicarse.

Requisitos previos

• Tener una cuenta de hiapi y una API key (sk-...). Puedes obtenerlas en la consola de hiapi.
• curl o, si vas a seguir los ejemplos en Python, Python 3.8+.
• Presupuesto para al menos una imagen de salida. gpt-image-2.5-sunburst/text-to-image se factura según la resolución de salida; consulta los precios actuales antes de ejecutarlo en producción, ya que las tarifas pueden cambiar.

Todas las solicitudes usan encabezados estándar:

Authorization: Bearer sk-your-api-key-here
Content-Type: application/json

Ejemplo mínimo funcional

Todos los modelos de imagen de hiapi se ejecutan sobre la misma API de tareas asíncrona: creas una tarea con POST y luego consultas su estado (o recibes una notificación por webhook) hasta que alcanza un estado terminal; después lees la URL de la imagen desde output[0].url.

1. Crear la tarea (curl)

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "input": {
      "prompt": "A minimalist product shot of a ceramic coffee dripper on a marble counter, soft morning light, 35mm lens look",
      "resolution": "2K",
      "aspect_ratio": "4:3",
      "background": "auto"
    }
  }'

Una llamada exitosa solo devuelve un ID de tarea: la generación es asíncrona:

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

2. Consultar el resultado

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

Consulta repetidamente cada pocos segundos hasta que data.status alcance un valor terminal. En caso de éxito, la respuesta se ve así (taskId/URL acortados para facilitar la lectura):

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01ABCDEF...",
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "status": "success",
    "storage": "temp",
    "created": 1789144334,
    "completed": 1789144407,
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/.../output-0.png",
        "artifactId": "146251",
        "expireAt": 1789749206
      }
    ]
  },
  "message": "success"
}

Obtén la imagen desde data.output[0].url. Esa URL caduca (consulta expireAt, una marca de tiempo Unix); en cuanto la tarea tenga éxito, descarga los bytes de inmediato y guárdalos por tu cuenta; no la trates como un enlace permanente.

3. Ejemplo completo en Python

import time
import requests

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


def create_task(prompt: str, resolution: str = "1K", aspect_ratio: str = "1:1") -> str:
    payload = {
        "model": "gpt-image-2.5-sunburst/text-to-image",
        "input": {
            "prompt": prompt,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 300, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task("A minimalist product shot of a ceramic coffee dripper on a marble counter")
    task = wait_for_task(task_id)
    image_url = task["output"][0]["url"]
    print(f"Done: {image_url}")

    img_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(img_bytes)

Qué campos acepta realmente input

El esquema de gpt-image-2.5-sunburst/text-to-image es pequeño y estricto. Solo acepta los siguientes campos; cualquier otro (quality, size, n, output_format, style, seed) se rechaza con un 400:

Campo	Obligatorio	Valores
prompt	Sí	Cualquier cadena
resolution	No (por defecto 1K)	1K, 2K, 4K
aspect_ratio	No	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
background	No	transparent, opaque, auto

Ten en cuenta que este esquema es distinto del del modelo gpt-image-2.5-sunburst básico: este último acepta niveles de quality (low/medium/high/xhigh/max/auto) y admite edición imagen a imagen mediante image_urls. El precio de ambos también difiere; antes de basarte en cifras concretas, verifícalo en /en/pricing, ya que las tarifas pueden cambiar.

Patrones para producción

Usar webhooks en lugar de sondeo

Para cualquier caso que vaya más allá de un script rápido, omite el sondeo y deja que hiapi te llame cuando la tarea termine. Añade un objeto callback de nivel superior en la misma solicitud POST /v1/tasks:

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

when: "final" es actualmente el único valor admitido; cuando la tarea alcanza un estado terminal (success o fail), tu endpoint se invoca una vez y la estructura del payload es la misma que obtendrías mediante sondeo.

Sondeo vs. callback: el sondeo es más fácil de implementar correctamente en scripts o notebooks y no requiere un endpoint público, pero desperdicia solicitudes y añade latencia (en promedio, tu intervalo de sondeo) hasta saber que la tarea terminó. Para integraciones del lado del servidor o cualquier escenario de alta concurrencia, el callback es más adecuado: evitas por completo el bucle de sondeo y recibes la notificación en cuanto la tarea finaliza.

Idempotencia en los reintentos

La API de tareas acepta una cadena idempotency_key de nivel superior, junto a model/input/callback. Si tu cliente puede reintentar el POST tras un timeout (enviaste la solicitud pero nunca recibiste respuesta), añade una key estable para tener una señal clara con la que verificar, en lugar de adivinar si la solicitud original llegó realmente a procesarse.

Gestionar errores

Una API key no válida o caducada devuelve HTTP 401 y un cuerpo de error estructurado:

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

Valores de input incorrectos (miembro de enumeración erróneo, falta de prompt, campos no admitidos) devuelven HTTP 400 antes de crear la tarea, por lo que no se te cobrará:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}

Revisa explícitamente ambos casos: reintenta ante errores transitorios de red o 5xx, pero trata un 400 como señal de que hay que corregir el cuerpo de la solicitud, no como algo que reintentar a ciegas.

Recursos relacionados

• Página del modelo gpt-image-2.5-sunburst: referencia completa de parámetros y precios en tiempo real tanto del modelo básico como de la ruta /text-to-image.
• Precios de hiapi: tarifas actuales por resolución de este modelo y de todos los demás.
• Recetas de prompts para GPT Image 2.5 Sunburst: si quieres inspiración antes de empezar a escribir el script, aquí tienes ejemplos de prompts de referencia.

Preguntas frecuentes

¿Tengo que especificar resolution? No; si se omite, el valor por defecto es 1K. Si necesitas salida en 2K o 4K, indícalo explícitamente, ya que el precio aumenta con la resolución.

¿Puedo pasar quality como en la documentación de otros modelos GPT Image? En esta ruta, no. gpt-image-2.5-sunburst/text-to-image rechaza por completo quality; ese parámetro solo existe en el ID de modelo básico gpt-image-2.5-sunburst, que tiene otro esquema y otro precio.

¿Por qué mi solicitud devuelve un ID de tarea en lugar de la imagen directamente? Todos los modelos de imagen de hiapi se ejecutan a través de la misma API de tareas asíncrona (POST /v1/tasks → sondeo o callback → output[0].url), sin importar lo rápido que sea en realidad el modelo subyacente. Construye una integración en torno a ese patrón y cada modelo que sustituyas después funcionará de la misma manera.

¿Qué pasa si no descargo la URL de salida a tiempo? Caduca; el campo expireAt de la respuesta de la tarea es la marca de tiempo Unix en la que la URL temporal deja de funcionar. En cuanto status sea success, descarga y guarda los bytes por tu cuenta de inmediato.

¿Puedo hacer edición imagen a imagen con este modelo? En la ruta /text-to-image, no. Para editar imágenes, usa el ID de modelo básico gpt-image-2.5-sunburst y pasa el campo de entrada image_urls; consulta su página del modelo para conocer el esquema exacto.

¿Listo para probarlo tú mismo? Obtén una API key en la consola de hiapi y sustituye el prompt en el ejemplo de Python anterior.