Cómo usar la API de texto a imagen grok-imagine-quality: curl, Python y una solicitud ejecutable

Resumen

• Qué es: una solución ejecutable para usar la API grok-imagine-quality/text-to-image en hiapi: cree una tarea con POST /v1/tasks, consulte GET /v1/tasks/<taskId> (o use un callback) y descargue la imagen desde output[0].url.
• Esquema estricto y reducido: prompt (obligatorio), aspect_ratio (13 proporciones, predeterminada 1:1), resolution (1k | 2k, en minúsculas, predeterminada 1k), output_format (jpeg | png | webp, predeterminado jpeg). Cualquier otro campo se rechaza con 400.
• "Quality" es un nivel, no un ajuste. No existen los parámetros quality ni rich_detail: el mayor detalle, las texturas y la iluminación son lo que esta variante del modelo ofrece por defecto. Si necesita borradores masivos y económicos, en el mismo endpoint está su modelo hermano de nivel estándar grok-imagine/text-to-image.
• Las URL de salida incluyen una fecha límite expireAt: descárguelas a tiempo o guárdelas de forma persistente.

Qué vas a construir y qué necesitas preparar

Objetivo: enviar un prompt de texto a grok-imagine-quality/text-to-image y obtener un archivo de imagen final listo para usar como imagen principal, primero con curl y luego como un pequeño script de Python que puedas poner en una cola de tareas.

Solo necesitas una cosa: una clave de API de hiapi. Obténla desde tu consola de hiapi y expórtala:

export HIAPI_API_KEY="sk-..."

Cada solicitud se autentica con el encabezado bearer estándar: Authorization: Bearer sk-<key>.

Solicitud mínima ejecutable (curl)

La generación de imágenes en hiapi es solo asíncrona. No necesitas esperar una llamada HTTP prolongada; en su lugar, creas una tarea y obtienes el resultado cuando termina.

Paso 1: crear la tarea:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-quality/text-to-image",
    "input": {
      "prompt": "imagen principal de producto de una cafetera espresso negra mate sobre una encimera de pizarra, iluminación direccional dramática, profundidad de campo reducida, acabado comercial de alta gama",
      "aspect_ratio": "16:9",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

Mientras el modelo trabaja en segundo plano, recibirás inmediatamente un taskId:

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

Paso 2: consultar hasta llegar a un estado terminal:

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

La tarea pasa por queued → handling → archiving y finalmente llega a success o fail. Solo success incluye salida:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "grok-imagine-quality/text-to-image",
    "status": "success",
    "created": 1783130400,
    "completed": 1783130460,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../image.png",
        "type": "image",
        "expireAt": 1783735260
      }
    ]
  }
}

Paso 3: descargar antes de expireAt:

curl -o hero.png "https://cdn.hiapi.ai/tasks/.../image.png"

El mismo flujo en Python

Un script completo: crear, consultar y guardar. Cópialo, configura HIAPI_API_KEY y ejecútalo.

import os
import time

import requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

payload = {
    "model": "grok-imagine-quality/text-to-image",
    "input": {
        "prompt": (
            "imagen principal de producto de una cafetera espresso negra mate "
            "sobre una encimera de pizarra, iluminación direccional dramática, "
            "profundidad de campo reducida, acabado comercial de alta gama"
        ),
        "aspect_ratio": "16:9",
        "resolution": "2k",       # ¡minúsculas! "2K" se rechaza con 400
        "output_format": "png",
    },
}

resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()  # un 4xx aquí = la propia solicitud fue rechazada
task_id = resp.json()["data"]["taskId"]
print("Tarea creada:", task_id)

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    status = task["status"]
    if status == "success":
        image = task["output"][0]
        with open("hero.png", "wb") as f:
            f.write(requests.get(image["url"], timeout=120).content)
        print("hero.png guardado")
        break
    if status == "fail":
        err = task["error"]
        raise RuntimeError(f"Tarea fallida: {err['code']} {err['message']}")
    time.sleep(5)  # queued / handling / archiving: sigue consultando

La generación en el nivel 2k suele completarse en uno o dos minutos; un intervalo de consulta de 5 segundos es suficiente.

Parámetros que existen realmente

El esquema de entrada es estricto: los campos desconocidos fallan con 400 INVALID_REQUEST: additional properties not allowed en lugar de ignorarse en silencio. Eso es buena noticia: las erratas no llegan a producción. Alcance completo de la interfaz:

Campo	Obligatorio	Valores	Valor predeterminado
input.prompt	Sí	Texto libre	—
input.aspect_ratio	No	2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2	1:1
input.resolution	No	1k, 2k (solo minúsculas)	1k
input.output_format	No	jpeg, png, webp	jpeg

Antes de construir sobre esto, hay tres cosas que conviene saber:

• La "quality" del nombre es un nivel, no un parámetro. Es posible que veas este modelo descrito como con mayor detalle, texturas e iluminación; eso es la variante del modelo en sí. No hay campos rich_detail, quality ni style que puedas activar.
• 1k y 2k se facturan como niveles distintos. Patrón habitual: iterar el prompt repetidamente en 1k y luego ejecutar de nuevo el prompt ganador en 2k para generar el material final. Consulta el precio actual por imagen en la página de precios de hiapi.
• No hay n, ni seed, ni negative_prompt. Una tarea genera una imagen. Si necesitas variantes, envía varias tareas en paralelo: son independientes y se ponen en cola de forma concurrente.

Consideraciones de producción: callbacks, idempotencia y errores

En producción, prioriza los callbacks frente a las consultas periódicas. Pasa callback en el nivel superior del cuerpo de la solicitud (no dentro de input) y hiapi llamará a tu servicio cuando la tarea llegue a un estado terminal:

{
  "model": "grok-imagine-quality/text-to-image",
  "input": { "prompt": "..." },
  "callback": {
    "url": "https://your-service.example.com/hiapi/callback",
    "when": "final"
  }
}

Con when: "final", se notifican tanto success como fail, así que deduplica por taskId en tu lado. Mantén una consulta periódica de baja frecuencia como respaldo por si se pierde un callback: el endpoint de detalle de tarea es siempre la fuente de la verdad.

Haz que los reintentos sean seguros con Idempotency-Key. La creación de tareas acepta el encabezado Idempotency-Key (máximo 255 bytes). Reintentar con la misma key nunca crea tareas duplicadas: la repetición devuelve el taskId original:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Idempotency-Key: order-42-hero-image" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-quality/text-to-image", "input": {"prompt": "..."}}'

Distingue y trata tres formas de fallo:

1. Fallo de autenticación: HTTP 401 y {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}. Comprueba la clave y si tiene permiso para usar este modelo; no reintentes a ciegas.
2. Entrada no válida: HTTP 400 y "error_code": "INVALID_REQUEST", y el mensaje indica el campo concreto (por ejemplo, resolution: value must be one of '1k', '2k'). Corrige el payload; reintentar con el mismo cuerpo fallará de la misma manera.
3. Fallo a nivel de tarea: la llamada de creación tiene éxito, pero la tarea termina con status: "fail" y un objeto data.error. Revisa error.code antes de volver a enviar.

Vigila expireAt. Las URL de salida son temporales. Descarga el archivo inmediatamente después de que la tarea tenga éxito, o pasa storage: "persistent" al crear la tarea para conservar la salida a largo plazo.

Páginas relacionadas

• Página del modelo grok-imagine-quality/text-to-image: playground y precios por nivel
• Referencia completa de parámetros en la documentación
• Referencia de la API de creación de tareas: encabezados, idempotencia, callbacks
• Cómo usar grok-imagine-quality de imagen a imagen: el mismo nivel, editando imágenes existentes
• Todos los modelos de imagen, vídeo y música

Preguntas frecuentes

¿Cuál es la diferencia entre grok-imagine-quality y grok-imagine/text-to-image? El mismo endpoint, la misma estructura de solicitud y distintos niveles. El nivel quality está orientado a imágenes principales y material comercial, con mayor detalle e iluminación, y se factura por niveles de resolución 1k/2k; la versión estándar grok-imagine/text-to-image es una opción más rápida y económica para lotes e ideación.

¿Por qué "resolution": "2K" devuelve 400? La enumeración distingue mayúsculas y minúsculas y es en minúsculas: 1k o 2k. Los valores en mayúsculas se rechazan con INVALID_REQUEST.

¿Puedo establecer un tamaño exacto en píxeles como 1920x1080? No. Controlas la forma con aspect_ratio (13 opciones, desde 2:1 ultraancho hasta 9:20 ultralto) y la nitidez con los niveles 1k/2k. Este modelo no tiene un campo size de forma libre.

¿Puedo generar varias imágenes en una sola solicitud? No: no hay parámetro n. Envía varias tareas en paralelo; cada tarea devuelve su propio taskId y se procesan de forma concurrente.

¿grok-imagine-quality admite imagen a imagen? Sí, con un id de modelo distinto: grok-imagine-quality/image-to-image. Su esquema se describe en la guía de imagen a imagen: es diferente del de texto a imagen.

¿Cuánto tiempo es válida la URL del resultado? Cada entrada de output[] tiene una marca de tiempo Unix expireAt. Descarga antes de esa fecha límite, o usa storage: "persistent" al crear la tarea (o promociona la salida más tarde) para conservarla.

¿Cómo se ve una tarea en cola pero sin completar? GET /v1/tasks/<taskId> devuelve un status de queued, handling o archiving, y todavía no hay output. Solo success incluye salida descargable; fail incluye data.error.