Crear videos cortos con happyhorse-1.1/reference-to-video mediante la API de hiapi

La mayoría de las demostraciones de "video con IA" terminan con un solo clip y una sola toma. En cuanto necesitas que el mismo personaje aparezca en una segunda o tercera toma —por ejemplo, una mascota que entra en escena, luego corre y luego celebra— tanto el texto a video como el imagen a video empiezan a desviarse: cada regeneración produce una cara distinta, una ropa distinta y una iluminación distinta. happyhorse-1.1/reference-to-video en la API de hiapi existe precisamente para resolver este problema concreto. Le das hasta 9 imágenes de referencia del mismo sujeto, más un prompt que describe la acción a lo largo de las tomas, y devuelve un único video continuo que mantiene el sujeto consistente de principio a fin —no una diapositiva hecha de animaciones independientes unidas en el editor de video.

Hicimos y entregamos un clip real de 8 segundos en 720p de principio a fin para ver qué tal funciona en la práctica: el prompt, la llamada a la API, el costo y la salida. Este es el proceso completo.

Por qué reference-to-video es otra herramienta

El texto a video no le da al modelo nada a lo que anclar una identidad, así que al regenerar con el mismo prompt la cara y la ropa del personaje pueden cambiar. El imagen a video ancla una pose, lo que funciona para un único momento, pero deja de servir en cuanto tu historia necesita un segundo ángulo o una acción que la imagen de origen nunca mostró. reference-to-video está a medio camino: varias imágenes de referencia le muestran al modelo el mismo sujeto desde múltiples ángulos reales —de frente, en pose de acción, lo que sea que proporciones— y usa esas imágenes juntas como ancla de identidad, de modo que el video puede recorrer varios momentos sin perder el hilo.

Esto lo hace adecuado para una necesidad concreta y habitual de los videos cortos: clips explicativos con mascota, contenido social con un personaje habitual, narrativa con un personaje de producto —cualquier escenario en el que el mismo "quién" deba sostenerse a lo largo de varios "qué" en una misma toma continua.

Caso de prueba: un zorro repartidor, tres momentos

Diseñamos un pequeño personaje original —Bramble, un zorro repartidor— y generamos primero dos imágenes de referencia para establecer su identidad antes de empezar a hacer el video.

Prompt usado: "Un pequeño personaje zorro de dibujos animados con ojos grandes llamado Bramble: pelaje naranja rojizo, hocico y pecho color crema, orejas altas y puntiagudas con el interior color crema, pañuelo verde azulado, un gastado bolso de correo de cuero marrón con una pequeña insignia circular azul en la correa. Estilo de largometraje animado en 3D, iluminación cálida y suave, pose de cuerpo entero orientada al frente, fondo neutro liso, diseño de personaje consistente."

Prompt usado: "El mismo personaje zorro Bramble —pelaje naranja rojizo, hocico color crema, pañuelo verde azulado, bolso de correo de cuero marrón con insignia azul— congelado en plena carrera en una dinámica pose de acción de tres cuartos, un brazo balanceado hacia delante, cola ondeando hacia atrás, ojos grandes y expresivos, mismo estilo de largometraje animado en 3D y mismas proporciones que la hoja de referencia, fondo neutro liso."

Cada imagen costó $0.03 generarla. Juntas constituyen todo el paso de "selección de reparto": antes de fijar el personaje no se realiza ninguna llamada de video.

Llamar a la API

reference-to-video, como todos los demás modelos de la plataforma, es un endpoint basado en tareas: se envía y luego se consulta hasta que termina.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/reference-to-video",
    "input": {
      "prompt": "Bramble the fox courier picks up a glowing gift box at a warm, lantern-lit delivery station and looks at it with delight; cut to Bramble sprinting through a bustling night market strung with red lanterns, package tucked under one arm, tail flying; cut to Bramble standing proudly on a rooftop at golden-hour sunset, package delivered, looking out over the rooftops with a satisfied smile. Consistent character design throughout, cinematic 3D animated feature style, warm lighting, smooth camera motion.",
      "reference_image": [
        "https://static.hiapi.ai/blog/happyhorse-1-1-reference-to-video-short-form-video/01-bramble-front.png",
        "https://static.hiapi.ai/blog/happyhorse-1-1-reference-to-video-short-form-video/02-bramble-action.png"
      ],
      "duration": 8,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

Esto devuelve un taskId. Consúltalo hasta que status alcance un estado terminal:

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

status pasa por queued → handling → (a veces) archiving → success o fail. En caso de éxito, el clip terminado es una URL temporal en output[0].url —descárgalo de inmediato, el enlace caduca.

Campos que confirmamos que funcionan

Campo	Tipo	Valor que usamos	Descripción
prompt	cadena, requerido	descripción de tomas de 3 momentos	Escríbelo como una mini lista de planos, no como una frase genérica
reference_image	array de URLs de imágenes	2 imágenes	La plataforma indica que admite hasta 9 por clip
duration	entero, segundos	8	La serie happyhorse-1.1 va de 3 a 15 segundos
resolution	cadena	"720p"	"1080p" también disponible, a mayor precio
aspect_ratio	cadena	"16:9"	Enumeración estándar de relaciones de aspecto

Resultado

Observa cómo se comporta el personaje entre los puntos de corte: el mismo pelaje, el mismo pañuelo verde azulado, el mismo bolso con insignia azul, desde la recogida en interior hasta la carrera por el mercado nocturno y el atardecer en la azotea. Ese es todo el sentido de darle dos imágenes de referencia en lugar de una: ante un cambio de escena, el modelo tiene más a lo que anclarse que una sola imagen fija. El clip además incorpora audio nativo automáticamente; no hay un campo de audio separado que configurar.

Ejemplo de Python reutilizable

import json
import subprocess
import time

def generate_reference_video(prompt, reference_images, token,
                              duration=8, resolution="720p", aspect_ratio="16:9"):
    payload = {
        "model": "happyhorse-1.1/reference-to-video",
        "input": {
            "prompt": prompt,
            "reference_image": reference_images,
            "duration": duration,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        },
    }
    submit = subprocess.run(
        ["curl", "-s", "-X", "POST", "https://api.hiapi.ai/v1/tasks",
         "-H", f"Authorization: Bearer {token}",
         "-H", "Content-Type: application/json",
         "-d", json.dumps(payload)],
        capture_output=True, text=True, check=True,
    )
    task_id = json.loads(submit.stdout)["data"]["taskId"]

    while True:
        poll = subprocess.run(
            ["curl", "-s", f"https://api.hiapi.ai/v1/tasks/{task_id}",
             "-H", f"Authorization: Bearer {token}"],
            capture_output=True, text=True, check=True,
        )
        task = json.loads(poll.stdout)["data"]
        if task["status"] in ("success", "fail"):
            break
        time.sleep(5)

    if task["status"] != "success":
        raise RuntimeError(task.get("error"))
    return task["output"][0]["url"]

Cuánto cuesta

Concepto	Costo
Imagen de referencia (frontal)	$0.03
Imagen de referencia (pose de acción)	$0.03
Clip de 8 s @ 720p ($0.16/s)	$1.28
Total de esta demostración	$1.34

720p cuesta $0.16/s; 1080p cuesta $0.21/s, así que el mismo clip de 8 segundos en 1080p costaría $1.68. Las tarifas completas vigentes están siempre en la página de precios —consúltala antes de ampliar la duración o la resolución del clip.

Trucos de prompting para la consistencia multicámara

• Escribe el prompt como una lista de tomas, no como una frase. "Momento 1 → Momento 2 → Momento 3", con una acción clara en cada momento, es lo que realmente impulsa tomas distintas dentro de un mismo clip; una única descripción genérica tiende a difuminarse en un movimiento continuo.
• Garantiza tú mismo la consistencia visual entre las imágenes de referencia. El modelo conserva lo que ya es consistente entre tus referencias; no reconcilia inconsistencias. Si tu imagen frontal y tu imagen de acción tienen tonos de pelaje distintos o les falta la insignia, esa ambigüedad se traslada al video.
• Dale una pose que ninguna imagen fija haya mostrado antes. El valor de múltiples referencias frente a una sola es que el modelo puede sintetizar acciones y ángulos más allá de lo que muestra cualquier imagen individual —una imagen de frente y una pose de acción bastan para sostener momentos tranquilos y momentos llenos de energía.
• Indica claramente los cambios de escena. "Corte a", "luego" y nombres de lugares concretos en el prompt se corresponden directamente con los cortes de toma que ves en el resultado.

Preguntas frecuentes

¿Cuántas imágenes de referencia puedo usar? Hasta 9 por clip. En esta demostración usamos 2, y fueron suficientes para mantener la identidad a lo largo de tres momentos distintos.

¿Se admite 1080p? Sí —1080p cuesta $0.21/s frente a los $0.16/s de 720p.

¿Y si solo tengo una imagen de referencia? Usa happyhorse-1.1/image-to-video —misma serie, una imagen inicial, sin anclaje de identidad con múltiples referencias.

¿Hay una opción de solo texto a video en la misma serie? Sí, happyhorse-1.1/text-to-video, con la misma tarifa por segundo, para cuando no tienes ninguna imagen fija de referencia.

¿La salida incluye sonido? Sí, el audio nativo se genera automáticamente junto con la imagen —no hay ningún parámetro de audio separado que configurar.

¿Cuánto puede durar el clip? La serie happyhorse-1.1 va de 3 a 15 segundos; usamos 8 segundos para presentar una narrativa de tres momentos.

Puntos clave

• happyhorse-1.1/reference-to-video convierte de 2 a 9 imágenes fijas en un video continuo y mantiene el mismo personaje, vestuario y estilo artístico en cada toma.
• Una demostración completa y funcional —2 imágenes de referencia más un clip de 8 segundos en 720p— cuesta $1.34 de principio a fin en la API de hiapi.
• Además del prompt, el modelo solo necesita tres campos: reference_image (array de URLs), duration (3-15 segundos) y resolution (720p o 1080p).
• Escribe el prompt como una lista de tomas (momento 1 → momento 2 → momento 3), no como una descripción genérica —eso es lo que realmente impulsa la estructura multicámara.
• El audio nativo se genera automáticamente con el video, sin un paso separado de generación de audio.

¿Listo para probarlo con tus propios personajes? Empieza en la página del modelo happyhorse-1.1/reference-to-video, o echa un vistazo a un flujo de trabajo similar de video corto en nuestro tutorial práctico de Seedance 2.0 Mini.