Blog

Tutorial

Llamar a muse-video-1.0/text-to-video mediante la API de HiAPI: guía con curl y Python

Campos de la solicitud, sondeo asíncrono y solicitudes de ejemplo ejecutables

Nov 13, 2026
Imagen de portada brutalista abstracta con planos de hormigón bajo una luz rasante, campo gris cálido, sombras gris pizarra y una fina junta verde salvia.
En esta página

Antes de enviar: autenticación, endpoint e identificador del modelo

muse-video-1.0/text-to-video convierte un prompt de texto en un clip de vídeo generado. Envías un prompt y varios parámetros de control, el servicio renderiza el clip y luego devuelve una URL o referencia descargable.

El detalle arquitectónico clave es que esta llamada es asíncrona. La renderización de vídeo tarda bastante, y la API no mantiene tu conexión HTTP abierta hasta que el archivo esté listo. Por eso el flujo tiene dos fases:

  1. Envío: haces POST del prompt y los parámetros. La respuesta vuelve rápido e incluye el identificador de la tarea y su estado inicial.
  2. Sondeo: haces GET de la tarea por su identificador a intervalos hasta que su estado pase a un estado terminal (correcto o fallido), y luego obtienes el resultado.

Esta forma de "enviar primero y sondear después" es lo que más hay que interiorizar antes de escribir código. Cambia la estructura de la aplicación: el vídeo no aparece en la respuesta de la solicitud de envío, y cualquier error que encuentres pertenece a una fase concreta: envío, validación, renderización u obtención. Distinguir estas fases en tu propio código (con funciones separadas y registro independiente) hará que el resto de esta guía sea más fácil de aplicar.

La cadena del modelo debe ser exacta: muse-video-1.0/text-to-video. La forma vendor/model es la convención general de los endpoints de modelos de HiAPI, y el enrutamiento de la API se basa en ella para decidir qué generador invocar.

Construir la solicitud: prompt, duración y campos de audio

Antes de la primera solicitud hay que tener preparadas tres cosas.

Clave de API

Toda solicitud requiere autenticación mediante bearer token. Guárdala en una variable de entorno en lugar de en el código fuente, para que no se filtre en los commits:

export HIAPI_API_KEY="your_key_here"

Envíala en la cabecera Authorization: Bearer $HIAPI_API_KEY. Si una solicitud falla con un error de autenticación, revisa primero esta cabecera: un nombre de variable mal escrito, un espacio al final o un valor no definido en el shell actual son las causas más habituales.

URL base

Todas las llamadas comparten una única URL base de la plataforma HiAPI. Usa el valor actual del panel de cuenta o de la referencia de la API, no lo copies de fragmentos de código antiguos; guárdalo en una variable para poder cambiarlo en un solo sitio.

Identificador del modelo

La cadena del modelo es muse-video-1.0/text-to-video. Trátala como un literal sensible a mayúsculas y minúsculas. No construyas ni adivines variantes, como cambios de mayúsculas o sufijos ausentes: un identificador de modelo desconocido es un error de validación, no un fallback.

Con estos tres elementos listos, ya puedes construir el cuerpo de la solicitud.

Solicitud curl funcional

El cuerpo de la solicitud es JSON. Conceptualmente contiene tres grupos de campos.

Prompt

El prompt es la instrucción creativa y determina la mayor parte de la calidad de la salida. Un prompt eficaz describe de forma concreta el sujeto, la acción, el comportamiento de cámara, la iluminación y el estilo, en lugar de limitarse a acumular adjetivos. Es un campo de texto normal.

Duración

Un modelo de texto a vídeo necesita saber cuánto debe durar el clip. La duración es un campo de la solicitud y también afecta al coste: la generación se factura por segundos de salida. Como el rango aceptable y el valor por defecto los define el modelo en cada momento, lee el nombre exacto del campo y los valores permitidos en la referencia de la API en vivo de muse-video-1.0/text-to-video, sin adivinar. Enviar una duración fuera de rango provoca un fallo de validación.

Audio

muse-video-1.0/text-to-video admite controles relacionados con el audio además de la generación visual. También son campos de la solicitud —normalmente interruptores o entradas de estilo de prompt de audio— cuyos nombres exactos y valores aceptables están documentados en la misma referencia de la API. En la primera integración, lo prudente es omitir por completo los campos de audio opcionales, confirmar que se devuelve el vídeo correctamente y luego ir añadiendo las opciones de audio una a una.

Por tanto, el cuerpo mínimo de la solicitud sería aproximadamente así (los nombres de campo son solo ejemplos; confírmalos con la referencia):

{
  "model": "muse-video-1.0/text-to-video",
  "prompt": "Al amanecer, una lenta toma aérea avanza sobre un bosque de pinos cubierto de niebla, luz volumétrica suave, aspecto cinematográfico",
  "duration": 5
}

Como el conjunto de parámetros puede evolucionar, una costumbre fiable es: obtener la documentación de referencia de ese modelo, copiar los nombres de campo literalmente y validarlos localmente antes de enviar.

La misma solicitud en Python

La llamada de envío es un HTTP POST normal. La ruta exacta del recurso la define la referencia de la API de HiAPI; el ejemplo siguiente usa el endpoint habitual de tareas, con el modelo en el cuerpo de la solicitud.

curl -sS -X POST "$HIAPI_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-video-1.0/text-to-video",
    "prompt": "Un robot de cartón camina por un callejón lluvioso con neones, reflejos en el asfalto mojado, textura de película de 35 mm",
    "duration": 5
  }'

La respuesta es pequeña y vuelve rápido. Lo importante en ella es el identificador de la tarea y el estado. La estructura típica es:

{
  "id": "job_abc123",
  "status": "queued"
}

Registra el id: es el identificador que usarás en todas las llamadas posteriores. Que status sea queued o processing es normal; indica que la solicitud se ha aceptado, no que algo haya ido mal.

Para sondear manualmente desde el shell:

curl -sS "$HIAPI_BASE_URL/v1/video/generations/job_abc123" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Ejecútalo varias veces con intervalos para observar cómo status avanza hacia un estado terminal. En la práctica, conviene poner este bucle en el código, no en el historial de la terminal.

Gestionar resultados asíncronos y sondear sin saturar la API

La versión en Python hace las mismas dos cosas —enviar y luego sondear— pero añade gestión de timeouts, reintentos acotados y guardado del resultado, para poder ejecutarse de forma desatendida con seguridad.

import os
import time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}"}

MODEL = "muse-video-1.0/text-to-video"

def submit(prompt: str, duration: int) -> str:
    resp = requests.post(
        f"{BASE}/v1/video/generations",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"model": MODEL, "prompt": prompt, "duration": duration},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["id"]

def wait_for(job_id: str, max_wait: int = 900) -> dict:
    deadline = time.time() + max_wait
    interval = 5
    while time.time() < deadline:
        r = requests.get(
            f"{BASE}/v1/video/generations/{job_id}",
            headers=HEADERS,
            timeout=30,
        )
        if r.status_code >= 500 or r.status_code == 429:
            time.sleep(interval)
            interval = min(interval * 2, 30)
            continue
        r.raise_for_status()
        job = r.json()
        if job["status"] == "succeeded":
            return job
        if job["status"] == "failed":
            raise RuntimeError(job.get("error") or "generation failed")
        time.sleep(interval)
        interval = min(interval * 1.5, 30)
    raise TimeoutError(f"job {job_id} did not finish in time")

def save(job: dict, path: str) -> None:
    url = job["result"]["video_url"]
    with requests.get(url, stream=True, timeout=120) as r:
        r.raise_for_status()
        with open(path, "wb") as f:
            for chunk in r.iter_content(8192):
                f.write(chunk)

if __name__ == "__main__":
    job_id = submit(
        "Un pequeño terrario de cristal sobre una mesa de madera, luz de la mañana, partículas de polvo flotando, macro",
        5,
    )
    job = wait_for(job_id)
    save(job, "output.mp4")
    print("saved output.mp4")

Aquí hay tres decisiones meditadas. Los reintentos están acotados por una fecha límite, no por un número de iteraciones, así que no se cuelgan indefinidamente. El backoff crece ante fallos transitorios y crece lentamente en el sondeo del camino correcto. La descarga es una solicitud de streaming aparte, lo que evita que los archivos grandes pasen por la ruta JSON.

Errores comunes y cómo diagnosticarlos

La frecuencia de sondeo es una decisión de diseño real. Sondear cada 200 ms solo genera carga innecesaria; sondear cada cinco minutos desperdicia tiempo real después de que la renderización haya terminado.

Estrategia práctica:

  • Empieza con un intervalo moderado (unos segundos) y auméntalo gradualmente: multiplicar por 1,5 en cada sondeo, con un tope de medio minuto, funciona bien.
  • Aumenta el backoff ante respuestas 429 y 5xx: duplica el intervalo y reintenta, tratándolas como señal de capacidad y no como estado de la tarea.
  • Fija un tiempo máximo total de espera y lanza un error al superarlo, en lugar de sondear para siempre. Las renderizaciones más largas tardan de verdad más, así que el límite debe ajustarse a tu propia carga de trabajo.
  • Registra una transición solo cuando cambie el estado, no en cada sondeo: los registros ruidosos hacen que los fallos reales pasen desapercibidos.

La respuesta de una tarea completada suele incluir el status terminal, el id de la tarea y una carga de resultados con la URL del vídeo descargable, a veces con metadatos y una fecha de caducidad de la URL. Obtén el archivo pronto tras el éxito. Si la tarea informa de failed, lee el mensaje de error de la respuesta antes de reintentar: un fallo de validación nunca tendrá éxito al reintentar, mientras que un error interno de renderización sí puede tenerlo.

Siguientes pasos

Empieza con el cuerpo mínimo de la solicitud, confirma una ejecución correcta de extremo a extremo y luego añade los controles de duración y audio según la documentación de referencia actual de muse-video-1.0/text-to-video. El mismo patrón de "enviar primero y sondear después" es trasladable a otros endpoints de modelos de HiAPI, así que el código de cliente que escribas aquí es reutilizable.

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