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
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:
- 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.
- 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
429y5xx: 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 →-
Tutorial
Guía práctica de gpt-6.2-sol: 5 usos de alto valor de los modelos de texto en el negocio
-
Tutorial
Guía práctica de gpt-6.2-astra: puntos clave de integración e implementación en 5 escenarios de texto de alto valor
Lista de verificación desde la perspectiva del desarrollador: de la selección de escenarios a la implementación en ingeniería
-
Tutorial
Casos prácticos de Tripo H3.1: 5 usos de alto valor y puntos clave de implementación
De texto a 3D a la reconstrucción multivista: elige el modo y los parámetros correctos según el escenario de negocio