Cómo usar happyhorse-1.1/reference-to-video con la API de HiAPI: recetas de prompts y flujo de trabajo para videos cortos

Qué cambia reference-to-video en tu flujo de trabajo

La generación de video a partir de solo texto exige que el modelo cree el sujeto desde cero según la descripción, lo que significa que cada ejecución puede producir caras, ropa o formas de producto diferentes. reference-to-video es lo contrario: proporcionas una o varias imágenes y el modelo las trata como referencia visual de lo que aparece en la escena. El prompt deja de ser una indicación de casting y pasa a ser una hoja de instrucciones de dirección.

En un flujo de trabajo de videos cortos, esto cambia el centro de atención. Con la generación de solo texto, iteras principalmente sobre la redacción. Con happyhorse-1.1/reference-to-video, lo primero que iteras es el conjunto de imágenes de referencia, y solo después el prompt. Si el sujeto no se ve bien, la solución suele ser cambiar una imagen por otra mejor o ajustar el orden de las imágenes, no acumular listas más largas de adjetivos.

Dónde encaja

Un ciclo típico es más o menos así:

1. Reúne y selecciona un pequeño conjunto de imágenes de referencia para el sujeto y la escena.
2. Ordénalas por importancia (la siguiente sección lo explica en detalle).
3. Escribe un prompt ordenado por planos, con atributos estables y ritmo explícito.
4. Genera, revisa comparando con las imágenes de referencia y decide si cambiar las imágenes o el texto.

El beneficio real está en la coherencia de una serie de contenidos. Si vas a producir varios videos con el mismo personaje, producto o mascota, un conjunto de imágenes de referencia estable es la clave para que el tercer episodio siga pareciendo el primero. Gestiona las imágenes como activos versionados en el repositorio, no como archivos subidos de usar y tirar.

Organiza tu conjunto de imágenes de referencia

El modelo lee tus imágenes como una señal con prioridad. El orden y la selección forman parte del prompt en sí, así que decídelos a propósito.

Elige una imagen principal del sujeto

La primera imagen debe ser la vista más clara y representativa del sujeto: de frente, bien iluminada, sin obstrucciones y con un fondo sin distracciones. Esta imagen fija la identidad. Las demás imágenes son información secundaria.

Añade un segundo ángulo solo cuando aporte valor real

Una segunda imagen es útil cuando resuelve una ambigüedad que la primera no elimina, por ejemplo una vista de perfil, un estado de vestuario diferente o la parte trasera de un producto. Es perjudicial cuando introduce detalles contradictorios, como dos peinados o dos logotipos. Si no quieres que el modelo haga un promedio de ambos, no pongas los dos a la vez.

Separa el sujeto del entorno

Si la escena es importante, añade una imagen de referencia del entorno que muestre el escenario sin competir por la atención con el sujeto. Hazla visualmente distinta de la imagen del sujeto para que el modelo no las mezcle.

Una regla de orden sencilla

• Posición 1: sujeto principal, limpio y canónico.
• Posición 2: vista secundaria del sujeto, solo si es necesaria.
• Posición 3 y siguientes: referencias de entorno o estilismo.

Prácticas que te ahorran varias iteraciones

• Mantén el conjunto de referencias pequeño y coherente internamente.
• Evita imágenes con el sujeto demasiado pequeño, recortes extraños o filtros demasiado agresivos.
• Unifica en lo posible la relación de aspecto; composiciones muy dispares dificultan que el modelo concilie las distintas vistas.
• Nombra los archivos según su rol (subject-primary.png, scene-street.png) para que el equipo los trate como un conjunto de materiales.

Si dudas, elimina una imagen en lugar de añadir otra.

Escribe prompts que mantengan la coherencia del sujeto

La deriva de identidad suele venir de una redacción vaga. Descripciones genéricas como "una persona" o "ropa con estilo" le dan al modelo margen para improvisar. La solución es escribir explícitamente atributos estables y observables, y mantenerlos iguales entre frases.

Indica lo que no debe cambiar

Enumera los atributos que definen al sujeto: color y corte de la ropa, peinado, accesorios característicos, forma del producto, ubicación del logotipo. Repite los elementos clave en cada descripción de plano en lugar de dar por supuesta la continuidad.

Distingue lo "fijado" de lo "variable"

Divide mentalmente el prompt en dos bloques: los atributos fijados del sujeto y, después, la acción y el plano de cada toma. Así detectas fácilmente cuándo introduces una contradicción sin querer, por ejemplo una chaqueta roja en el primer plano y una chaqueta gris en el tercero.

Patrones de redacción eficaces

• Ancla primero: empieza por el sujeto y sus atributos fijados, y describe el movimiento después.
• Mantén los sustantivos coherentes: si la imagen de referencia muestra un gabardina, llámalo gabardina siempre, no primero "chaqueta" y luego "abrigo".
• Lo concreto supera a lo valorativo: "pelo corto oscuro con raya lateral" es mejor que "pelo bonito".
• Especifica lo que se mantiene durante el movimiento: "el abrigo conserva su forma original mientras el sujeto se gira" es más útil que esperar que el modelo lo deduzca.
• Evita acumular sinónimos: amontonar adjetivos diluye la señal.

Una comparación rápida

Débil: "una mujer con estilo caminando por la calle, cinematográfico".

Más fuerte: "la mujer de la imagen de referencia —pelo corto oscuro con raya lateral, gabardina camel, botas negras— camina hacia la cámara con paso constante; el abrigo y las botas se mantienen iguales en todo momento".

La segunda versión le da al modelo una lista de comprobación, no una atmósfera.

Dirige el plano y el ritmo en un solo prompt

El éxito de un video corto depende del ritmo. Una única descripción estática genera un video sin estructura que vaga a la deriva. Escribe el prompt como una secuencia ordenada de planos con indicaciones de ritmo explícitas.

Organiza por tiempos

Describe de dos a cuatro tiempos, cada uno con el estado del sujeto, la acción y una nota de plano. Mantén cada tiempo breve. El modelo procesa mejor una secuencia clara de tres tiempos que un párrafo largo y denso.

Escribe el ritmo de forma explícita

Las palabras de ritmo tienen peso: "corte rápido", "acercamiento lento", "pausa de un tiempo", "zoom brusco", "cierre estable". Combínalas con el lenguaje de cámara (dolly, paneo, cámara en mano) para que el movimiento y la sensación de tiempo se refuercen mutuamente.

Plantilla de tiempos

Plano 1 (0-2 s): [sujeto + atributos fijados] [acción], [movimiento de cámara], [indicación de ritmo].
Plano 2 (2-4 s): [cambio de estado del sujeto] [acción], [movimiento de cámara], [indicación de ritmo].
Plano 3 (4-6 s): [tiempo de cierre], [cámara estable], [indicación de ritmo].

No necesitas marcas de tiempo exactas, pero pensar en segundos te obliga a justificar cada tiempo. Si un tiempo no tiene un cambio visual claro, elimínalo.

Errores de ritmo habituales

• Meter demasiados tiempos en un video corto, lo que obliga al modelo a precipitarlo todo.
• No dar indicaciones de cámara, lo que produce una composición plana y estática.
• Incluir indicaciones de ritmo contradictorias en la misma línea ("lento y enérgico").

Cuando termines la secuencia, léela en voz alta y elimina todo lo que no cambie el contenido de la imagen.

Compensaciones entre resolución, duración y presupuesto

Antes de generar en lote, decide qué recurso vas a gastar: píxeles, segundos o iteraciones. Compiten entre sí.

La compensación central

Una resolución de salida más alta (por ejemplo, 1080P) y una duración mayor aumentan el coste de cada generación. Como la facturación sigue la salida que solicitas —incluidas la resolución y la longitud del clip—, un video largo en 1080P es lo más caro que puedes pedir. Para videos cortos, rara vez necesitas llevar ambos al máximo.

Un orden de decisión eficaz

1. Fija primero la duración. Un video corto suele implicar una ventana de tiempo compacta. Bloquea la longitud que necesita la plataforma y trata todo lo demás como ajustable.
2. Elige la resolución según el destino de entrega. Si el clip se va a comprimir de todos modos en el feed, una resolución más baja puede ser el valor predeterminado más sensato y además te permite gastar el presupuesto en más intentos.
3. Gasta el presupuesto en iteraciones, no solo en resultados. Un video de resolución algo menor que puedes generar tres veces y del que eliges el mejor resultado suele superar a un intento caro que no puedes rehacer.

Consejos prácticos

• Haz prototipos con una resolución más baja para validar el prompt y el conjunto de referencias.
• Sube a 1080P solo cuando la secuencia de planos y la coherencia de identidad estén aprobadas.
• Sé honesto con la duración: un corto compacto con tiempos claros se ve mejor que un video largo lleno de relleno.

Consulta el panel de precios actual para conocer las tarifas exactas; los números cambian y no deben codificarse de forma fija en los scripts. Al construir la solicitud, haz que la resolución y la duración sean parámetros conmutables, no constantes enterradas en el código.

Solicitud ejecutable y biblioteca de recetas de prompts

A continuación se muestra la estructura de solicitud para llamar a happyhorse-1.1/reference-to-video mediante la API de HiAPI, seguida de recetas de prompts listas para copiar que acompañan al flujo de trabajo anterior. Los nombres de los parámetros pueden variar ligeramente según la versión del SDK; consulta la página del modelo para obtener el esquema canónico.

Estructura de la solicitud

import os, requests

resp = requests.post(
    "https://api.hiapi.ai/v1/video/generations",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "happyhorse-1.1/reference-to-video",
        "reference_images": [
            "https://your-cdn.example/subject-primary.png",
            "https://your-cdn.example/subject-angle.png",
            "https://your-cdn.example/scene-street.png",
        ],
        "prompt": "...recipe text...",
        "resolution": "1080P",
        "duration": 6,
    },
)
print(resp.json())

Mantén las imágenes de referencia en URL estables y ordenadas como se indicó: sujeto principal, vista secundaria, entorno.

Receta 1: visual principal de producto, un solo tiempo

El producto de la imagen de referencia —frasco negro mate, tapón color cobre, etiqueta frontal— centrado sobre una superficie de piedra. Acercamiento lento hasta la etiqueta, iluminación de estudio suave, sin cortes. El frasco y el tapón conservan su forma y color exactos en todo momento.

Receta 2: persona caminando, tres tiempos

Plano 1 (0-2 s): la mujer de la imagen de referencia —pelo corto oscuro con raya lateral, gabardina camel, botas negras— camina hacia la cámara, plano medio, cámara en mano estable, paso ligero.
Plano 2 (2-4 s): corte rápido a un perfil; la gabardina se mueve cuando ella gira, la cámara la sigue lateralmente, mismo ritmo ligero.
Plano 3 (4-6 s): ella se detiene y mira al frente, la cámara se estabiliza en un acercamiento lento, cierre sereno. El pelo, la gabardina y las botas se mantienen iguales en todos los planos.

Receta 3: apertura guiada por el entorno

Plano 1 (0-2 s): plano general de la calle de la imagen de referencia del entorno, luz de mañana, paneo lento hacia la izquierda.
Plano 2 (2-4 s): el sujeto de la imagen de referencia entra por la derecha del encuadre —la misma chaqueta y el mismo bolso—, la cámara permanece fija, ritmo natural.
Plano 3 (4-6 s): se cierra a un plano medio, ella mira a cámara; la chaqueta y el bolso coinciden exactamente con la imagen de referencia.

Puedes ajustar la duración y la resolución por clip sin modificar el texto del prompt. La documentación ofrece una guía específica con ejemplos completos.

Revisa el resultado e itera

La revisión es donde se produce la mayor parte de la mejora de calidad, y la disciplina clave es determinar ante qué tipo de problema estás.

Evalúa comparando con la referencia, no de memoria

Abre el conjunto de imágenes de referencia junto al resultado. Comprueba uno a uno los atributos de identidad: cara y pelo, color y corte de la ropa, forma del producto, ubicación del logotipo. La deriva que puedes nombrar es la deriva que puedes corregir.

Clasifica los fallos en dos tipos

• Problemas de identidad o apariencia: normalmente significan que el conjunto de referencias es débil, incoherente o está mal ordenado. Arregla primero las imágenes; forzar más el prompt rara vez salva un conjunto de referencias contradictorio.
• Problemas de composición, movimiento o ritmo: normalmente significan que el prompt debe mejorar: tiempos más claros, notas de cámara más contundentes, una duración más compacta.

Un ciclo de revisión breve

1. Puntúa por separado identidad, composición y ritmo.
2. Si la identidad no aprueba, ajusta primero las imágenes de referencia y luego toca el prompt.
3. Si el ritmo no aprueba, reescribe la secuencia de tiempos y elimina uno de ellos.
4. Cambia solo una variable por iteración, así sabrás qué funcionó.
5. Cuando esté estable en resolución baja, sube a 1080P para la versión final.

Mantén un registro breve de la versión del prompt y de la versión del conjunto de referencias para cada clip aprobado. En una serie, ese registro se convierte en tu verdadera biblioteca de recetas: prompts fiables, imágenes fiables, resultados predecibles. Itera sobre el conjunto de referencias y el texto, y deja el resto al modelo.