Cómo usar happyhorse-1.1 mediante la API de hiapi: texto a video, imagen a video y referencia a video

Si estás buscando cómo usar happy horse 1.1, aquí va la versión breve: happyhorse-1.1 no es un único endpoint de modelo, sino tres, y todos se sirven a través de la API unificada de tareas asíncronas de hiapi:

Endpoint (ID de modelo)	Función	Entrada obligatoria
happyhorse-1.1/text-to-video	Genera video a partir de un prompt de texto	prompt
happyhorse-1.1/image-to-video	Da movimiento a una imagen estática	image_urls
happyhorse-1.1/reference-to-video	Genera video guiado por una imagen de referencia más un prompt	prompt, reference_image

Los tres endpoints comparten el mismo ciclo de vida: POST /v1/tasks para enviar → obtener el taskId → sondear GET /v1/tasks/<id> (o recibir un callback) → descargar output[0].url. Cada tabla de parámetros y cada mensaje de error que aparece a continuación se ha verificado contra la API en producción; nada está basado en suposiciones.

Requisitos previos

Solo necesitas una cosa: una clave de API de hiapi. Obténla en tu consola de hiapi; tiene el formato sk-... y se envía en la cabecera Authorization: Bearer. La generación de video se factura por segundo de salida; consulta la página de precios para conocer la tarifa por segundo actual de cada endpoint.

export HIAPI_KEY="sk-your-key-here"

Ejemplo mínimo funcional (texto a video)

Envío del task:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/text-to-video",
    "input": {
      "prompt": "A golden retriever puppy runs through a sunlit meadow, slow motion, cinematic",
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "duration": 5
    }
  }'

La respuesta te devuelve un ID de tarea en data.taskId. Sondéala:

curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer $HIAPI_KEY"

Cuando data.status pasa a success, la URL del video está en data.output[0].url. Descárgala de inmediato: las URL de salida incluyen una marca de tiempo expireAt y residen en almacenamiento temporal, así que trátalas como una ventana de recogida, no como un alojamiento permanente.

A continuación tienes el mismo flujo como script completo de Python (solo con la biblioteca estándar):

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-your-key-here"

def api(method, url, payload=None):
    req = urllib.request.Request(url, method=method)
    req.add_header("Authorization", f"Bearer {KEY}")
    req.add_header("Content-Type", "application/json")
    data = json.dumps(payload).encode() if payload else None
    with urllib.request.urlopen(req, data=data) as resp:
        return json.loads(resp.read())

# 1. Submit
task = api("POST", API, {
    "model": "happyhorse-1.1/text-to-video",
    "input": {
        "prompt": "A golden retriever puppy runs through a sunlit meadow, cinematic",
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "duration": 5,
    },
})
task_id = task["data"]["taskId"]
print("submitted:", task_id)

# 2. Poll until terminal state
while True:
    data = api("GET", f"{API}/{task_id}")["data"]
    status = data["status"]
    if status == "success":
        video_url = data["output"][0]["url"]
        break
    if status == "fail":
        raise RuntimeError(f"task failed: {data.get('error')}")
    time.sleep(5)

# 3. Download before the URL expires
urllib.request.urlretrieve(video_url, "output.mp4")
print("saved output.mp4")

Parámetros de cada endpoint

El esquema de entrada es estricto: los campos desconocidos se rechazan con un 400 en lugar de ignorarse silenciosamente. Campos como size, seed, negative_prompt y audio devuelven additional properties ... not allowed. A continuación se indican los parámetros que acepta exactamente cada endpoint.

happyhorse-1.1/text-to-video

Campo	Obligatorio	Tipo	Valores permitidos
prompt	✅	string	La descripción de tu escena
aspect_ratio	—	string	16:9, 9:16, 3:4, 4:3, 4:5, 5:4, 1:1, 9:21, 21:9
resolution	—	string	720p, 1080p
duration	—	integer	3–15 (segundos)

Guía completa con técnicas de prompting: tutorial de texto a video con happyhorse-1.1.

happyhorse-1.1/image-to-video

Campo	Obligatorio	Tipo	Valores permitidos
image_urls	✅	array de strings	Exactamente 1 URL de imagen de acceso público (maxItems: 1)
prompt	—	string	Guía de movimiento/escena para la animación
resolution	—	string	720p, 1080p
duration	—	integer	3–15 (segundos)

Aquí hay dos trampas habituales. Primero, image_urls es un array, pero actualmente solo acepta un elemento: pasa ["https://..."], no una cadena sin corchetes ni varias URL. Segundo, este endpoint no tiene aspect_ratio (la API lo rechaza); el formato de salida sigue a tu imagen de origen.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/image-to-video",
    "input": {
      "image_urls": ["https://your-cdn.example.com/product-shot.jpg"],
      "prompt": "slow camera push-in, soft studio lighting",
      "resolution": "720p",
      "duration": 5
    }
  }'

Lectura en profundidad: tutorial de imagen a video con happyhorse.

happyhorse-1.1/reference-to-video

Campo	Obligatorio	Tipo	Valores permitidos
prompt	✅	string	Descripción de la escena
reference_image	✅	array de strings	1–9 URL de imágenes de acceso público (maxItems: 9)
aspect_ratio	—	string	Las mismas 9 proporciones que texto a video
resolution	—	string	720p, 1080p
duration	—	integer	3–15 (segundos)

Este es el endpoint de «mantén mi personaje/producto consistente»: las imágenes de referencia anclan la identidad y el estilo, mientras que el prompt impulsa la acción. A diferencia de imagen a video, aquí recuperas el control de aspect_ratio y puedes pasar hasta 9 imágenes de referencia.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/reference-to-video",
    "input": {
      "prompt": "the character waves at the camera and smiles, city street at dusk",
      "reference_image": ["https://your-cdn.example.com/character-front.jpg",
                          "https://your-cdn.example.com/character-side.jpg"],
      "aspect_ratio": "9:16",
      "resolution": "720p",
      "duration": 5
    }
  }'

Lectura en profundidad: tutorial de referencia a video con happyhorse-1.1.

¿Qué endpoint deberías elegir?

• Solo tienes una idea → text-to-video. La vía más rápida del texto al movimiento.
• Tienes la imagen exacta que quieres animar (foto de producto, ilustración, fotografía) → image-to-video. La imagen de origen es el aspecto del primer fotograma.
• Necesitas mantener el mismo sujeto a lo largo de varios clips (un personaje, una mascota de marca, varios ángulos de un producto) → reference-to-video. Las imágenes de referencia fijan la identidad; el prompt cambia por clip.

Patrones de práctica en producción

Usa callbacks en lugar de sondeo

Para cualquier uso que vaya más allá de un script, registra un webhook al crear el task: los tasks de video tardan bastante, y sondear dentro de un manejador de peticiones web acabará agotando el tiempo de espera:

{
  "model": "happyhorse-1.1/text-to-video",
  "input": { "prompt": "..." },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

Solo se admite "when": "final": recibirás un único POST cuando el task llegue a un estado terminal (cualquier otro valor devuelve invalid callback.when: only 'final' is supported). Diseña tu receptor para ser idempotente respecto a taskId: guarda el ID del task en el momento del envío y trata los callbacks duplicados o ya procesados como no-ops. Mantén un barrido de sondeo de baja frecuencia como red de seguridad para callbacks perdidos por problemas de red.

Manejo de errores: tres clases de fallo

1. Errores de validación (HTTP 400, INVALID_REQUEST). Los mensajes son muy precisos; léelos y señalarán el campo exacto:

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: duration: maximum: got 99, want 15; resolution: value must be one of '720p', '1080p'"
}

2. Errores de autenticación/permisos (HTTP 401, permission_denied). La clave es incorrecta, o la clave no tiene permiso para acceder a este modelo:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. ...",
    "request_id": "2026..."
  }
}

Revisa la clave en la consola y, si contactas con soporte, incluye el request_id.

3. Fallos de generación (task con status: "fail"). El envío se realizó correctamente, pero la generación falló; al sondear o recibir el callback, los detalles del error están en el campo error del objeto de la tarea. Estos errores merecen reintentos con retroceso exponencial; los errores de validación y de autenticación no.

Control de costes

La facturación se basa en los segundos de video generados, por lo que duration es tu principal palanca de coste: un clip de 15 segundos cuesta 3 veces más que uno de 5 segundos, mientras que resolution influye menos. Itera los prompts con duration: 3 y 720p, y después renderiza la versión final a la duración completa. Consulta la página de precios para las tarifas actuales.

Lecturas relacionadas

• happyhorse-1.1 texto a video: página del modelo y playground
• happyhorse-1.1 imagen a video: página del modelo y playground
• happyhorse-1.1 referencia a video: página del modelo y playground
• Flujos de trabajo de video corto con happyhorse-1.1
• Documentación de hiapi

Preguntas frecuentes

¿Puedo usar imágenes y prompts de texto al mismo tiempo? Sí: image-to-video acepta un prompt opcional además del image_urls obligatorio, y reference-to-video exige tanto prompt como reference_image. Solo text-to-video funciona únicamente con prompt.

¿Cuántas imágenes puedo pasar? image-to-video: exactamente una (image_urls está limitado a 1 elemento). reference-to-video: hasta nueve en reference_image. Ambos aceptan arrays de URL de acceso público, no archivos subidos ni base64.

¿happyhorse-1.1 admite los parámetros seed, negative_prompt o audio? No. El esquema de entrada es estricto y rechaza los tres con un error 400 additional properties not allowed. Si necesitas reproducibilidad, mantén el prompt y los parámetros exactamente iguales y gestiona el versionado por tu cuenta.

¿Qué resoluciones y duraciones hay disponibles? En los tres endpoints: 720p o 1080p, y de 3 a 15 segundos (enteros). Si se omiten, se aplican los valores predeterminados.

¿Por qué recibo un 401 permission_denied con una clave que parece válida? La clave existe, pero no puede usar este modelo; esto es habitual en claves con alcance limitado o de prueba. Verifica los permisos de modelo de esa clave en la consola o genera una clave nueva sin restricciones.

¿Cómo sé cuándo está listo el video sin sondear? Pasa callback: {"url": "...", "when": "final"} en el momento del envío. Cuando el task llega a success o fail, hiapi hace un POST a tu URL una sola vez. Recuerda que las URL de salida caducan: descarga el archivo en el manejador del callback, no lo enlaces en caliente.