Blog

Tutorial

Cómo llamar a happyhorse-1.1/text-to-video mediante la API de HiAPI: ejemplos de curl y Python disponibles

Estructura de la solicitud, sondeo asíncrono y manejo de audio nativo para una integración funcional

Nov 12, 2026
Imagen de portada: sobre un fondo verde pino profundo, varios prismas abstractos divididos en planos de color uniforme, que forman una composición geométrica sobria con bloques en verde grisáceo y verde neblina.
En esta página

Qué cubre esta integración

Esta guía te llevará por todo el proceso de llamar a happyhorse-1.1/text-to-video a través de la API unificada de HiAPI. Al terminar, tendrás una solicitud funcional: enviar un prompt de texto, sondear hasta que se complete y guardar el vídeo generado junto con su pista de audio nativa. Primero presentaremos la estructura de la solicitud para que entiendas el payload antes de escribir cualquier código; después daremos una llamada curl lista para copiar; a continuación explicaremos el patrón de sondeo asíncrono necesario para la generación de vídeo; y por último trasladaremos todo a Python añadiendo un manejo básico de errores. No necesitas experiencia previa con APIs de vídeo; solo una clave de API de HiAPI y un terminal o un entorno de Python. El objetivo es ofrecer un ejemplo de integración mínimo pero completo que puedas adaptar a tu propio pipeline.

Estructura de la solicitud de happyhorse-1.1/text-to-video

Antes de realizar la llamada, resulta útil entender los campos que componen una solicitud de texto a vídeo. Este endpoint acepta un payload JSON que contiene como mínimo el identificador del modelo y tu prompt de texto. Otros campos habituales controlan el tamaño y la duración de la salida, pero los nombres exactos de los parámetros y los valores aceptables deben consultarse en la documentación del modelo en HiAPI. Un payload válido suele tener este aspecto:

{
  "model": "happyhorse-1.1/text-to-video",
  "prompt": "Al amanecer, la cámara se desplaza lentamente en panorámica sobre un bosque cubierto de niebla"
}

Mantén el payload plano y usa únicamente los campos indicados en la documentación del modelo. Los campos no reconocidos o con tipos mal formados son la causa más frecuente de rechazo de la solicitud. En caso de duda, empieza con un payload mínimo que contenga solo model y prompt, y luego añade los parámetros opcionales uno a uno para poder localizar el problema.

Realizar la primera solicitud con curl

Una vez preparado el payload, puedes enviar la tarea con curl. Enviarás una solicitud POST con un cuerpo JSON y la clave de API en la cabecera Authorization. La respuesta suele incluir el identificador de la tarea, que usarás más adelante para sondear el estado. A continuación tienes un ejemplo funcional:

curl -X POST https://api.hiapi.ai/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -d '{
    "model": "happyhorse-1.1/text-to-video",
    "prompt": "Al amanecer, la cámara se desplaza lentamente en panorámica sobre un bosque cubierto de niebla"
  }'

Sustituye $HIAPI_API_KEY por tu clave real o expórtala en el shell. La respuesta será un JSON que contiene un campo id (o un identificador con un nombre similar) y un estado que indica que la tarea ha sido aceptada. Lee la respuesta con atención: si el estado no es el de aceptada, revisa primero el mensaje de error antes de continuar. No supongas en este punto que el vídeo ya está listo; la tarea acaba de entrar en la cola.

Gestionar el sondeo asíncrono

La generación de vídeo no es instantánea, por lo que HiAPI devuelve un identificador de tarea en la respuesta inicial en lugar del vídeo final. Debes sondear el endpoint de estado hasta que la tarea alcance un estado terminal. El patrón general es: enviar la tarea, obtener el ID y luego solicitar repetidamente el estado de la tarea con intervalos cortos. Detente cuando el estado indique éxito o fallo. La lógica en forma de pseudocódigo es la siguiente:

  1. Envía la tarea y lee el id de la tarea.
  2. Espera unos segundos.
  3. Solicita el estado de la tarea usando ese id.
  4. Si el estado es "completed" o "succeeded", obtén la URL de salida y sal del bucle.
  5. Si el estado es "failed", registra el error y sal.
  6. En caso contrario, espera de nuevo y repite hasta alcanzar un número máximo razonable de intentos.

Evita sondear con demasiada frecuencia. Para tareas de vídeo, un intervalo de unos segundos entre intentos suele ser suficiente. Además, no esperes que una única respuesta bloqueante incluya el vídeo final; el modelo asíncrono es intencionado y coherente en todas las tareas de generación de larga duración.

Audio nativo en la salida

El vídeo generado por happyhorse-1.1/text-to-video incluye audio nativo en la salida. Cuando la tarea se completa, la respuesta apunta al archivo de vídeo generado, que ya contiene la pista de audio. No necesitas generar ni obtener el audio por separado. Para guardar y verificar el resultado, descarga el archivo de vídeo desde la URL proporcionada y conserva su formato de contenedor. Si procesas el archivo de forma programática, verifica que el flujo de audio existe, por ejemplo, inspeccionando el archivo con una herramienta multimedia. No elimines ni recodifiques el audio salvo que tu pipeline posterior lo requiera, ya que hacerlo podría degradar la calidad o eliminar por completo la pista de audio. Trata el archivo devuelto como un activo audiovisual completo.

Realizar la misma solicitud con Python

Trasladar la llamada curl a Python es sencillo: reutiliza el mismo payload JSON y añade el bucle de sondeo. El siguiente ejemplo usa requests, espera entre intentos y lanza una excepción en caso de fallo. Sustituye la ruta del endpoint y los nombres de los campos de estado por los indicados en la documentación de happyhorse-1.1/text-to-video en HiAPI.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "happyhorse-1.1/text-to-video",
    "prompt": "Al amanecer, la cámara se desplaza lentamente en panorámica sobre un bosque cubierto de niebla",
}

resp = requests.post(f"{BASE}/video/generations", headers=HEADERS, json=payload)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]

for attempt in range(60):
    status_resp = requests.get(f"{BASE}/video/generations/{job_id}", headers=HEADERS)
    status_resp.raise_for_status()
    status = status_resp.json()
    state = status.get("status")
    if state in ("completed", "succeeded"):
        video_url = status["output"]["url"]
        print("Vídeo listo: ", video_url)
        break
    if state == "failed":
        raise RuntimeError(status.get("error", "La generación falló"))
    time.sleep(5)
else:
    raise TimeoutError("Se agotó el tiempo de sondeo")

Esto sigue la lógica de «sondear hasta completar» descrita anteriormente. Usa raise_for_status() para exponer cuanto antes los errores HTTP y mantén un intervalo de espera razonable para evitar solicitudes innecesarias.

Solucionar fallos habituales

La mayoría de los problemas de integración se agrupan en unas pocas categorías. Un payload mal formado, como la falta del campo model o el uso de un tipo JSON incorrecto, se rechaza de inmediato; revisa tu JSON con cuidado comparándolo con la documentación del modelo. Sondear con demasiada frecuencia puede provocar límites de tasa o carga innecesaria; aumenta el intervalo de espera. Otro error común es confundir la respuesta inicial con el vídeo final; asegúrate de sondear hasta alcanzar un estado terminal. Los errores de autenticación suelen significar que falta la cabecera Authorization o que está mal formada, así que verifica que tu clave de API se ha exportado correctamente. Por último, si la tarea falla tras el sondeo, revisa el mensaje de error de la respuesta de estado; normalmente apunta a un prompt no válido o a un parámetro no admitido. Tras corregir estos problemas, vuelve a intentarlo primero con un payload mínimo válido.

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