Cómo llamar a muse-image-1.0/text-to-image mediante la API de HiAPI: curl y Python

Qué implica realmente esta integración

En HiAPI, una llamada de texto a imagen es una única solicitud HTTP síncrona: se envía un cuerpo JSON que describe la imagen deseada y la respuesta llega con los datos de la imagen generada. Este endpoint no tiene bucles de sondeo ni colas de trabajos que gestionar: una solicitud, una respuesta.

Los componentes implicados son pocos:

• Tu clave de API: autentica la solicitud mediante la cabecera Authorization.
• El endpoint: la ruta URL fija de muse-image-1.0/text-to-image sobre la URL base de HiAPI.
• El cuerpo JSON: transporta tu prompt y cualquier parámetro opcional que acepte el modelo.
• El payload de respuesta: devuelve los datos de la imagen generada, que tú decodificas o reenvías.

Eso es toda la superficie de la interfaz. Las secciones siguientes construyen la solicitud paso a paso con curl y luego repiten el mismo proceso con Python, de modo que puedas verificar cada parte antes de añadir complejidad.

Requisitos previos y autenticación

Antes de enviar tu primera solicitud, asegúrate de tener:

1. Una clave de API obtenida desde el panel de tu cuenta de HiAPI. Trátala como una contraseña; nunca la incluyas en el control de versiones.
2. Un cliente HTTP: basta con curl para las pruebas; la versión del script está pensada para Python 3.8+.
3. La URL base de la API de HiAPI, que encontrarás junto a la clave en la documentación del panel.

La autenticación usa un token Bearer en la cabecera Authorization. Cada solicitud a muse-image-1.0/text-to-image lo necesita:

Authorization: Bearer $HIAPI_API_KEY

Guarda la clave en una variable de entorno, no la codifiques directamente en el script:

export HIAPI_API_KEY="your-key-here"

La ruta del endpoint de este modelo es /muse-image-1.0/text-to-image, añadida tras la URL base. La URL base exacta está documentada en tu panel de HiAPI; guárdala también en una variable de entorno para poder cambiar de entorno sin modificar el código:

export HIAPI_BASE_URL="https://api.hiapi.ai"   # confirma el valor actual en tu panel

Con estas dos variables configuradas, ya puedes enviar solicitudes.

Una solicitud curl que funciona

A continuación se muestra una llamada mínima a muse-image-1.0/text-to-image. Envía un prompt y escribe la respuesta JSON sin procesar en un archivo, para que puedas inspeccionarla antes de escribir código de análisis.

curl -sS -X POST "$HIAPI_BASE_URL/muse-image-1.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a quiet harbor at dawn, soft fog, wide angle",
    "n": 1
  }' \
  -o response.json

Algunas observaciones sobre el cuerpo de la solicitud:

• prompt es obligatorio: es la descripción textual que renderiza el modelo.
• n es opcional y controla el número de imágenes que solicitas. Si lo omites, se acepta el valor predeterminado.
• Incluye solo los parámetros que hayas confirmado para este modelo en la documentación de referencia de la API de HiAPI. No adivines campos no documentados; los parámetros desconocidos pueden ser rechazados por la validación del servidor o ignorados silenciosamente.

Si la solicitud tiene éxito, response.json contiene los datos de la imagen. Si falla, recibirás un cuerpo de respuesta de error y un código de estado no 2xx; consulta la sección de manejo de errores a continuación.

Puedes comprobar el código de estado HTTP sin volcar todo el cuerpo de la respuesta:

curl -sS -o /dev/null -w "%{http_code}\n" -X POST "$HIAPI_BASE_URL/muse-image-1.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"test"}'

Implementar la misma solicitud en Python

La versión en Python usa requests y es idéntica a la llamada curl: el mismo endpoint, las mismas cabeceras, el mismo cuerpo. Extráela como una función reutilizable.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

def generate_image(prompt: str, n: int = 1) -> dict:
    url = f"{BASE_URL}/muse-image-1.0/text-to-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {"prompt": prompt, "n": n}

    response = requests.post(url, headers=headers, json=payload, timeout=60)
    response.raise_for_status()  # lanza excepción en 4xx/5xx
    return response.json()

if __name__ == "__main__":
    result = generate_image("a quiet harbor at dawn, soft fog, wide angle")
    print(result.keys())

Hay dos detalles que merece la pena conservar:

• timeout=60: establece un tiempo de espera explícito. La generación de imágenes es más lenta que una llamada típica a una API JSON; sin tiempo de espera, tu proceso podría quedarse colgado indefinidamente si la conexión se estanca.
• raise_for_status(): expone los errores HTTP como excepciones, en lugar de dejarte analizar silenciosamente un cuerpo de respuesta de error como si fuera una imagen.

Si ya usas httpx o aiohttp, la conversión es directa: las mismas cabeceras, el mismo cuerpo JSON. Esta solicitud no depende de ninguna biblioteca HTTP concreta.

Leer la respuesta síncrona

Como muse-image-1.0/text-to-image es síncrono, los datos de la imagen llegan en la misma respuesta: no hace falta una segunda llamada para obtener el resultado. La respuesta es JSON; inspecciona su estructura una vez antes de escribir el analizador:

import json

result = generate_image("a quiet harbor at dawn")
print(json.dumps(result, indent=2)[:500])

Cómo manejar la imagen depende de lo que contenga la respuesta:

Si la respuesta contiene datos de imagen en base64

Decodifica la cadena y escribe los bytes en un archivo:

import base64

b64 = result["data"][0]["b64_json"]   # nombre del campo: confírmalo en la referencia de la API
with open("output.png", "wb") as f:
    f.write(base64.b64decode(b64))

Si la respuesta contiene una URL

Descárgala con un GET normal: la URL ya está autorizada para la recuperación, así que no añadas la clave de API a un host de terceros:

import requests

image_url = result["data"][0]["url"]   # nombre del campo: confírmalo en la referencia de la API
img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
    f.write(img.content)

Los nombres exactos de los campos —b64_json frente a url, así como la estructura externa que los envuelve— están definidos en la documentación de referencia de la API de HiAPI para este modelo. Imprime la respuesta una vez, confirma la estructura y luego escribe el código en consecuencia. No des por sentada la estructura de otros modelos.

En un servicio, no escribas ciegamente en el disco local: transmite los bytes a un almacenamiento de objetos o pásalos directamente a donde se consuma la imagen (un paso de carga, una cola, la respuesta a tu propio cliente). Antes de reenviar, verifica que los bytes decodificados parezcan una imagen (comprueba los bytes mágicos).

Manejar códigos de error y reintentos

HiAPI devuelve códigos de estado HTTP estándar. Una regla de triaje útil es: si vuelvo a enviar la misma solicitud sin cambiarla, ¿tendrá éxito?

Corregir la solicitud: no reintentar

• 400 Bad Request: JSON mal formado o un parámetro que el modelo no acepta. Comprueba que prompt exista y que no hayas inventado campos. Corrige el cuerpo; reintentar tal cual volverá a fallar igual.
• 401 Unauthorized: clave de API ausente o no válida. Verifica que HIAPI_API_KEY esté configurada y no haya sido rotada.
• 403 Forbidden: la clave es válida pero no tiene permiso para acceder a este endpoint. Revisa los permisos de acceso de tu cuenta en el panel.
• 404 Not Found: ruta incorrecta. Confirma que la cadena del endpoint sea exactamente /muse-image-1.0/text-to-image y que la URL base sea correcta.
• 422 Unprocessable Entity: el JSON está bien formado pero es semánticamente no válido, por ejemplo un valor fuera de rango. Lee el mensaje de error; normalmente indica el nombre del campo.

Reintentar con retroceso exponencial

• 429 Too Many Requests: estás siendo limitado por tasa. Aplica retroceso exponencial y reintenta; si existe la cabecera Retry-After, respétala.
• Errores 5xx: fallo del lado del servidor. Reintenta con retroceso exponencial y un límite (por ejemplo, tres intentos) y luego abandona y expón el error.

Un bucle de reintentos compacto:

import time

def post_with_retry(url, headers, payload, attempts=3):
    for i in range(attempts):
        resp = requests.post(url, headers=headers, json=payload, timeout=60)
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(2 ** i)
            continue
        resp.raise_for_status()
        return resp.json()
    raise RuntimeError(f"failed after {attempts} attempts: {resp.status_code} {resp.text}")

Registra siempre el código de estado y el cuerpo de la respuesta de error cuando haya un fallo. El mensaje del cuerpo de la respuesta te dirá a cuál de las dos categorías pertenece un error dado.

Lista de comprobación de producción antes de publicar

Algunos hábitos hacen que las llamadas a muse-image-1.0/text-to-image sigan siendo predecibles cuando salen de tu portátil:

• Fija la estructura de la solicitud. Valida el cuerpo JSON contra los campos documentados en la referencia de la API. Si añades un parámetro, confirma primero que esté soportado.
• Establece tiempos de espera en todas partes. Tanto las llamadas de generación como cualquier descarga de los datos de imagen devueltos necesitan un tiempo de espera explícito.
• Distingue las categorías de error. Separa los fallos reintentables (429, 5xx) de los definitivos (400, 401, 403, 404, 422), para que tus alertas no sean ruidosas y los reintentos no se desperdicien.
• Registra la información clave. Si la respuesta proporciona un ID de solicitud, regístralo junto con el código de estado, la latencia y la longitud del prompt; no registres el propio prompt si puede contener texto sensible.
• Vigila los factores que impulsan el coste. La generación se factura por la salida: el número de imágenes, el tamaño y la frecuencia con la que reintentas afectan al coste. Evita reintentar errores definitivos y evita regenerar cuando almacenar en caché los resultados sea viable.
• Mantén las claves en el lado del servidor. Nunca incrustes la clave de API en un navegador o cliente móvil para llamar directamente al endpoint.

Con esto, la integración es una función pequeña y aburrida que puedes llamar desde cualquier lugar, que es justo lo que quieres. Para conocer la superficie completa de parámetros y los campos de respuesta actuales, consulta la documentación de referencia de la API de HiAPI para este modelo.