Blog

Tutorial

Cómo usar grok-imagine/text-to-image a través de la API de HiAPI: guía con curl y Python

Nov 12, 2026
Ilustración de portada en papel estratificado en tonos crema y grafito con una única lámina de color terracota escalonada en una profundidad superficial.
En esta página

Qué te ofrece grok-imagine/text-to-image

grok-imagine/text-to-image es un endpoint de texto a imagen disponible a través de HiAPI: envías una indicación y unos pocos parámetros de generación por HTTP en formato JSON, y recibes una imagen. Ese es todo el contrato. No hay SDK que instalar, ni sesión que inicializar, ni tarea en segundo plano que consultar para ver la primera imagen.

Su lugar en los flujos de trabajo de desarrolladores:

  • Validación de prototipos. Puedes pasar de una idea a una imagen renderizada con un solo comando de terminal, lo que te permite probar ideas de indicaciones rápidamente.
  • Pipelines de contenido. Como es una simple llamada HTTP, puedes invocarlo desde un servicio de backend, un worker de cola o un script de compilación igual que cualquier otra API.
  • Funcionalidades de producto. La generación de imágenes orientada al usuario suele implicar la necesidad de un manejo predecible de solicitud/respuesta, errores estructurados y reintentos. Un endpoint sin estado encaja perfectamente en estas tres cosas.

Lo que este endpoint no es: no almacena tus indicaciones, no gestiona una biblioteca de imágenes generadas ni sustituye tu propia orquestación. Tú eres responsable de la solicitud, tú eres responsable de la salida y tú decides adónde van los bytes.

Esta guía se centra en hacer que la solicitud funcione primero y en hacerla fiable después. Tanto si llamas con curl como con Python, el patrón es idéntico, porque ambos son la misma solicitud HTTP autenticada. Empieza con lo mínimo funcional, confirma que el ida y vuelta funciona y luego añade complejidad.

Requisitos previos y autenticación

Antes de la primera llamada, asegúrate de tener lo siguiente:

  1. Una cuenta de HiAPI y una clave de API. Trata la clave como un secreto: cárgala desde una variable de entorno y nunca la codifiques directamente en un script que pueda acabar siendo confirmado en el repositorio.
  2. Una herramienta para realizar solicitudes HTTP. Para la primera prueba, curl es suficiente. Para Python, usa requests o httpx; ambos se abordan más adelante.
  3. Red con acceso al host de la API de HiAPI. Si estás detrás de un proxy corporativo, asegúrate de configurar HTTPS_PROXY para tu shell, de modo que tanto curl como Python puedan leerlo.

La clave se pasa como bearer token mediante la cabecera Authorization:

export HIAPI_API_KEY="your-key-here"

Después, cada solicitud incluye:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Dos hábitos que conviene adoptar de inmediato:

  • No pongas la clave en la URL. Ninguna parte de la solicitud debe incluir credenciales en la cadena de consulta, ya que acaban en los registros y en el historial del shell.
  • Usa una clave por entorno. Las claves de desarrollo y producción deben ser valores distintos, de modo que puedas rotar una sin afectar a la otra.

Si aún no has generado una clave, créala en el panel de HiAPI y guárdala en tu gestor de secretos o en un archivo .env local excluido del control de versiones. En cuanto echo $HIAPI_API_KEY imprima un valor, estarás listo para enviar tu primera solicitud.

La solicitud mínima funcional en curl

La llamada útil mínima solo envía el identificador del modelo y la indicación. Todo lo demás tiene valores predeterminados, así que no te apresures a ajustar parámetros antes de ver una imagen devuelta.

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-image",
    "prompt": "a lighthouse on a rocky coast at dusk, calm sea, soft overcast light"
  }'

Qué hace cada parte:

  • -X POST junto con un cuerpo JSON es la forma estándar de llamar a un endpoint de generación.
  • model selecciona explícitamente grok-imagine/text-to-image. Fija el nombre del modelo en tus scripts en lugar de depender de los valores predeterminados, para que un cambio en estos no altere silenciosamente tus resultados.
  • prompt es la única entrada de contenido. Para la primera prueba, mantén una sola frase clara.

Una respuesta correcta devuelve JSON con la imagen generada, normalmente una URL o una carga en base64, según el formato de respuesta que hayas solicitado. Antes de escribir cualquier código de análisis, revisa la respuesta con una herramienta de formateo JSON. Si la ves en la terminal, pasarla por python -m json.tool hace que la estructura sea más legible.

Una vez que funcione, guarda la respuesta sin procesar en un archivo para tener una línea base de referencia válida:

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json \
  -o response.json

Al poner el cuerpo de la solicitud en request.json, puedes editar la indicación sin pelearte con las comillas del shell, algo especialmente importante cuando la indicación se alarga o contiene signos de puntuación.

La misma solicitud en Python

La versión en Python es la misma llamada HTTP, pero con una experiencia de uso mejor: diccionarios en lugar de comillas anidadas y manejo directo de los bytes de la imagen.

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "grok-imagine/text-to-image",
    "prompt": "a lighthouse on a rocky coast at dusk, calm sea, soft overcast light",
}

response = requests.post(
    f"{base_url}/v1/images/generations",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)

Dos detalles merecen mención especial. Primero, timeout=120: la generación de imágenes no es instantánea, y una solicitud sin timeout dejará a un worker colgado indefinidamente si el servicio upstream se bloquea. Segundo, llama a raise_for_status() antes de analizar la respuesta, de modo que un cuerpo de error no se confunda con una respuesta de imagen correcta.

Para guardar la imagen, maneja las dos formas de respuesta:

item = data["data"][0]

if item.get("b64_json"):
    import base64
    image_bytes = base64.b64decode(item["b64_json"])
else:
    image_bytes = requests.get(item["url"], timeout=60).content

with open("output.png", "wb") as f:
    f.write(image_bytes)

Si prefieres un único conjunto de dependencias, httpx se usa igual, con httpx.post(..., json=payload). La clave es que el cuerpo y las cabeceras de la solicitud sean idénticos al ejemplo de curl; esa consistencia es lo que hace intercambiables ambos ejemplos y predecible la depuración.

Organizar las indicaciones para la relación de aspecto

Las salidas panorámicas fallan de una forma característica: el modelo tiene mucho espacio horizontal que llenar, así que o repite elementos o deja un sujeto diminuto flotando en un lienzo vacío. Esto se resuelve con la estructura de la indicación, no acumulando más adjetivos.

Usa un esqueleto de tres partes:

  1. Sujeto: de qué trata la imagen, indicado primero y con concreción. «Un carguero entrando en el puerto» es mejor que «un barco».
  2. Estilo: el lenguaje de renderizado: fotografía, vector plano, acuarela, fotograma cinematográfico. Una o dos palabras bastan.
  3. Composición: cómo se organiza la escena; aquí es donde se gana o se pierde con las relaciones de aspecto panorámicas.

Para la composición, nombra explícitamente la estructura horizontal:

  • Especifica un orden de lectura de izquierda a derecha o panorámico: «plano general amplio, sujeto en el tercio derecho, cielo abierto a la izquierda».
  • Describe el primer plano, el plano medio y el fondo como bandas separadas, porque una imagen panorámica se lee naturalmente por capas.
  • Especifica qué llena los bordes: «grúas portuarias en el extremo izquierdo, aguas abiertas en el extremo derecho». Los bordes son lo primero que se vacía en una imagen panorámica.
  • Evita indicaciones que impliquen composición de retrato o cuadrada —primeros planos de rostros, un único objeto centrado— y espera que se estiren o se rellenen con barras negras.

Cuando configures el parámetro de relación de aspecto para un formato panorámico, modifica también la indicación. Una indicación escrita para un encuadre cuadrado producirá un concepto cuadrado en un lienzo ancho. Reescríbela como una escena que contenga distancia horizontal: un horizonte, una calle, filas de objetos, un grupo disperso por una habitación.

Itera una variable a la vez. Fija la relación de aspecto y cambia la redacción; luego fija la redacción y cambia la proporción. Registra ambos junto con la salida, para que puedas determinar qué cambio fue realmente útil.

Manejo de errores y códigos de respuesta

Lee primero el código de estado y luego el cuerpo de la respuesta. Cada fallo habitual apunta a una solución distinta, y confundirlos hace perder tiempo.

401 Unauthorized

La clave falta, está mal formada o ha sido revocada. Comprueba que la cabecera sea exactamente Authorization: Bearer <key>, que la variable de entorno realmente se haya expandido (imprime su longitud, no su valor) y que no hayas enviado por error una clave de otro entorno.

400 Bad Request

Tu JSON es HTTP válido, pero no válido para este endpoint. Sospechosos habituales:

  • model mal escrito o ausente. Debe ser grok-imagine/text-to-image.
  • prompt vacío o ausente.
  • Algún parámetro con tipo incorrecto: una cadena donde debería ir un número, o viceversa.
  • El cuerpo de la solicitud no es JSON válido en absoluto, normalmente por problemas de comillas del shell en curl. Mueve el cuerpo a un archivo y usa -d @request.json.

Lee el cuerpo del mensaje de error; normalmente señala el campo problemático.

429 Too Many Requests

Estás enviando solicitudes más rápido de lo que permite tu cuota. La solución está en el cliente: retroceder, encolar, reintentar. No aprietes el bucle de reintentos porque hayas recibido un 429; eso empeorará las cosas.

Errores 5xx del servidor

Son condiciones transitorias o del upstream. Reintenta tras un retraso y, si el fallo persiste tras varios intentos, captura la carga de la solicitud y el cuerpo de la respuesta para diagnóstico, en lugar de reintentar indefinidamente.

Timeouts y errores de conexión

No son códigos de estado HTTP en absoluto, pero son los fallos más comunes en la práctica. Si requests lanza un timeout de conexión, es posible que la solicitud ya se haya procesado. Antes de escribir un bucle de reintentos, decide para tu caso de uso si un timeout significa «reintentar» o «abandonar».

Ajuste y reintentos en producción

Una vez que la solicitud base funcione, ajusta en pasos pequeños: primero la redacción de la indicación, luego la relación de aspecto, después otros parámetros, comparando las salidas en paralelo. Guarda cada carga de solicitud junto con su salida, para que los resultados sean siempre reproducibles.

Un envoltorio de producción hace tres cosas: reintentar solo los fallos que merece la pena reintentar, registrar lo suficiente para depurar y fallar de forma ruidosa cuando se rinde.

import time
import requests

def generate(payload, max_attempts=4):
    for attempt in range(1, max_attempts + 1):
        try:
            r = requests.post(
                f"{base_url}/v1/images/generations",
                headers=headers,
                json=payload,
                timeout=120,
            )
        except requests.RequestException as exc:
            log.warning("request failed attempt=%d err=%s", attempt, exc)
            time.sleep(2 ** attempt)
            continue

        if r.status_code == 429 or r.status_code >= 500:
            log.warning("retryable status=%d attempt=%d", r.status_code, attempt)
            time.sleep(2 ** attempt)
            continue

        if r.status_code >= 400:
            raise RuntimeError(f"{r.status_code}: {r.text[:500]}")

        return r.json()

    raise RuntimeError("exhausted retries")

Notas sobre este patrón:

  • Retroceso exponencial con límite (2 ** attempt) evita que un cliente limitado por tasa golpee repetidamente el endpoint. Si ejecutas muchos workers, añade jitter.
  • Reintenta solo 429, 5xx y errores de red. Un 400 o un 401 fallarán igual en cada intento.
  • Registra el número de intento y el estado, no la clave de API y, si la indicación puede contener datos de usuario, nunca registres la indicación completa.
  • Limita el tiempo total. Un bucle de reintentos sin límite convierte una solicitud lenta en un worker bloqueado.

Mide tu propia latencia y tasa de éxito en lugar de suponerlas; esos dos números te dicen si necesitas más paralelismo o más retroceso. Empieza con la solicitud mínima de esta guía, envuélvela con la función auxiliar anterior y luego itera desde ahí.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API