MiniMax H3: cómo usar un vídeo de referencia sin que lo copie

Para que MiniMax H3 tome de un vídeo de referencia solo el movimiento de cámara, solo la acción de un personaje o solo el ritmo de montaje, el prompt tiene que darle a ese vídeo un único papel, nombrar lo que no debe pasar al resultado (la persona, la ropa, los animales y el escenario que aparecen en el clip) y describir la escena nueva entera. Un prompt que solo dice «usa el vídeo 1» deja al modelo decidir qué parte es la referencia, y el resultado puede acabar reproduciendo lo que ve. El modo se llama Reference Generation en la API oficial de MiniMax, Ref2VA en los pesos abiertos y Reference-to-Video en plataformas como fal, Domo o RunDiffusion. En la API oficial y en la de LaoZhang, el clip entra como elemento video_url con el papel reference_video, junto a un texto obligatorio; ComfyUI y SGLang usan sus propias entradas.

Así funcionó en una prueba del 2 de noviembre de 2026: una petición a MiniMax-H3 a 768P y 4 s, con un clip de demostración de MiniMax de 6,06 s (un hombre con traje rosa sostiene un cordero negro en un prado mientras la cámara en mano se acerca despacio) y la orden de usar ese vídeo «solo para su movimiento de cámara», devolvió un pescador remendando una red en un muelle al amanecer, con el mismo acercamiento lento. En los fotogramas no aparece ni el traje, ni el cordero, ni el prado. La tarea costó 0,55 $, porque se cobran los 4 s de salida más 7 s de referencia: los 6,06 s se redondean hacia arriba. Es una sola muestra, no una garantía.

Antes de enviar nada, deja el clip dentro de los límites oficiales: como máximo 3 vídeos, de 2 a 15 s cada uno y 15 s en total, y sin first_frame ni last_frame en la misma petición. Algunas peticiones fuera de esos límites se aceptan y fallan segundos después con «temporary service error… Please retry», un mensaje que suena a avería pasajera cuando lo que hay que cambiar es el clip.

Qué es Reference-to-Video en MiniMax H3 y qué papel darle al vídeo

Reference-to-Video es el modo de H3 que genera un vídeo nuevo a partir de un texto y de imágenes, vídeos o audios de referencia. La guía de generación de vídeo de MiniMax resume su uso como «referenciar personaje, movimiento, cámara, estilo, voz o ritmo de edición», y la guía oficial de prompts para el modo referencia, publicada con los pesos en Hugging Face, separa cada uso en un tipo de tarea distinto. Elige el papel antes de escribir el prompt, porque de él dependen las palabras que usas y lo que tienes que excluir.

La guía oficial lo dice de forma explícita: si un vídeo de referencia solo aporta movimiento de cámara, cortes o ritmo, la tarea es normalmente reference generation. También explica por qué se cuelan las personas: la etiqueta de vídeo se reserva para relaciones con el vídeo entero (cámara, cortes, ritmo, edición, continuación), mientras que una persona u objeto que vuelve a aparecer como contenido visible se trata como un sujeto aunque salga de un vídeo. Si quieres a la persona del clip en el resultado, esa es otra tarea y conviene describirla como sujeto; si no la quieres, nombrarla en la lista de exclusiones es lo que separa ambos casos. La guía de Reference-to-Video de DomoAI y la guía de prompts de MiniMax H3 de RunDiffusion dan el mismo consejo práctico: un trabajo por referencia, frases como «Video 1 controls motion and camera only; ignore its performer and setting» y añadir las referencias de una en una.

La luz y el color son lo otro que se cuela. Según una prueba de Reference-to-Video publicada por Atlas Cloud en agosto de 2026, un vídeo de referencia tiende a fijar el movimiento, la cámara, el etalonaje y el grano del clip, no la identidad. En esa prueba el prompt pedía a la vez «bright empty covered market, cold clean daylight» y «carry the grade and grain of the reference clip»; ganó la referencia, y el plano salió mucho más sombrío de lo pedido. La conclusión de Atlas es que una misma llamada no puede pedir el aspecto de la referencia y la luz contraria: si necesitas cambiar la luz, quita primero la instrucción de conservar el etalonaje, o prescinde del vídeo de referencia y mantén la identidad solo con una imagen.

Cómo nombrar el vídeo dentro del prompt depende de dónde generes. Los ejemplos de la API oficial usan lenguaje natural y numeran por tipo («reference video 1», «reference images 1 and 2»); la documentación de LaoZhang y el nodo nativo de ComfyUI usan etiquetas como <Video 1>; fal, RunDiffusion y el nodo de API de ComfyUI escriben Video 1, y la app de Hailuo @Video1. En la API la numeración va por tipo de archivo, así que el primer vídeo es el vídeo 1 aunque antes envíes tres imágenes.

Requisitos del clip: 3 vídeos, de 2 a 15 s cada uno y 15 s en total

Además del número y la duración, el clip tiene que cumplir límites de formato, tamaño, resolución y fotogramas por segundo, y cualquiera de ellos puede tumbar la petición. Estos son los límites completos de la referencia de la API de vídeo de MiniMax a 2 de noviembre de 2026:

La petición también tiene reglas propias. Debe llevar un elemento de texto no vacío, y las referencias no se pueden combinar con first_frame ni last_frame, porque la documentación trata imagen a vídeo y referencia a vídeo como modos excluyentes. El parámetro ratio es opcional y por defecto vale adaptive, salvo en MiniMax-H3-Lite, que todavía no lo admite. Los cuatro modelos del endpoint (MiniMax-H3, -Highspeed, -Lite y -Max) aceptan vídeo de referencia en la API, aunque la app de Hailuo indica que allí solo H3 lo admite.

El transporte cambia según dónde envíes. La API oficial acepta una URL pública, un archivo subido (mm_file://{file_id}) o el vídeo en Base64 como data:video/mp4;base64,…, y recomienda URL para archivos grandes porque el Base64 ocupa alrededor de un 33 % más. La documentación de LaoZhang exige enlaces HTTPS públicos y directos para vídeo y audio, y no admite el audio como única referencia.

Script de comprobación previa con ffprobe

Los límites se pueden comprobar en local antes de gastar una petición. El script siguiente lee cada clip con ffprobe, revisa número, duración, total, contenedor, códec, tamaño, píxeles, proporción y fotogramas por segundo, e imprime los segundos que se cobrarían si la plataforma redondea hacia arriba. Necesita Python 3 y FFmpeg instalados; se ejecuta con python3 h3_ref_check.py clip1.mp4 clip2.mp4.

#!/usr/bin/env python3
"""Comprueba vídeos de referencia contra los límites de MiniMax H3 antes de enviarlos."""
import json, math, subprocess, sys

def probe(path):
    out = subprocess.run(["ffprobe", "-v", "error", "-show_entries",
        "format=duration,size,format_name:stream=codec_type,codec_name,width,height,avg_frame_rate",
        "-of", "json", path], capture_output=True, text=True, check=True).stdout
    return json.loads(out)

def check(paths):
    problems, total = [], 0.0
    if len(paths) > 3:
        problems.append(f"{len(paths)} clips: H3 accepts at most 3 reference videos")
    for p in paths:
        info = probe(p)
        fmt = info["format"]
        v = next(s for s in info["streams"] if s["codec_type"] == "video")
        dur, size_mb = float(fmt["duration"]), int(fmt["size"]) / 1e6
        num, den = map(int, v["avg_frame_rate"].split("/"))
        fps = num / den if den else 0
        w, h = v["width"], v["height"]
        total += dur
        print(f"{p}: {dur:.2f}s (billed {math.ceil(dur)}s), {w}x{h}, {fps:.3f} fps, "
              f"{v['codec_name']}, {size_mb:.1f} MB")
        if not 2 <= dur <= 15: problems.append(f"{p}: {dur:.2f}s is outside 2-15 s")
        if v["codec_name"] not in ("h264", "hevc"): problems.append(f"{p}: codec {v['codec_name']} is not H.264/H.265")
        if not ("mp4" in fmt["format_name"] or "mov" in fmt["format_name"]): problems.append(f"{p}: container is not MP4/MOV")
        if size_mb > 50: problems.append(f"{p}: {size_mb:.1f} MB is over 50 MB")
        if not (256 <= w <= 5760 and 256 <= h <= 5760): problems.append(f"{p}: {w}x{h} outside 256-5760 px")
        if not 0.4 <= w / h <= 2.5: problems.append(f"{p}: aspect ratio {w/h:.2f} outside 0.4-2.5")
        if not 23.976 <= round(fps, 3) <= 60: problems.append(f"{p}: {fps:.2f} fps outside 23.976-60")
    if total > 15: problems.append(f"total {total:.2f}s is over 15 s")
    print(f"total reference length {total:.2f}s")
    print("OK" if not problems else "FIX BEFORE SUBMITTING:\n- " + "\n- ".join(problems))
    return not problems

if __name__ == "__main__":
    sys.exit(0 if check(sys.argv[1:]) else 1)

El 2 de noviembre de 2026, en macOS 26.1 con ffprobe 9.0.2, el script aprobó el clip de demostración de 6,06 s (1920×1080, 24 fps, H.264, 4,4 MB, «billed 7s») y marcó los dos casos que después fallarían en la API: un clip de 1,5 s («1.50s is outside 2-15 s») y dos copias de un clip de baile de 9,47 s («total 18.95s is over 15 s»). Para arreglar el segundo caso basta recortar; este comando vuelve a codificar el clip desde el segundo 1 y lo deja en 6,00 s exactos:

ffmpeg -ss 1 -i dance.mp4 -t 6 -c:v libx264 -crf 20 -preset veryfast -c:a aac dance-6s.mp4

Con el clip recortado más el de 6,06 s, el total fue de 12,06 s y el script respondió «OK». Recortar a segundos enteros también ahorra dinero donde la referencia se cobra por segundo redondeado: 6,00 s se cobran como 6, mientras que 6,06 s se cobran como 7. El script solo comprueba los límites documentados; no puede prever la calidad del resultado ni la moderación automática, que según MiniMax se aplica a los textos, imágenes y vídeos enviados.

Petición y prompt para tomar solo la cámara, paso a paso

La petición que funcionó lleva el modelo, un texto que asigna el papel y una sola entrada video_url con el papel reference_video. La prueba se hizo el 2 de noviembre de 2026 a través de la API de LaoZhang, que sirve MiniMax-H3 desde un despliegue propio de los pesos abiertos (no pasa por la API oficial de MiniMax) y cobra 0,05 $/s a 768P según su documentación de MiniMax H3. El cuerpo de la petición es el mismo que documenta la API oficial; solo cambian la dirección y la clave.

Aviso: laozhang.ai es un servicio propio. Sus precios son nuestra tarifa, no una comparación independiente.

1. Pasa el clip por el script anterior y súbelo a una URL HTTPS pública que el servidor pueda descargar directamente.
2. Escribe el prompt en tres frases: qué aporta el vídeo 1 (describiendo el movimiento con tus palabras), qué no debe copiarse (lo que se ve en el clip, nombrado uno por uno) y la escena nueva completa, con sujeto, lugar, hora y luz.
3. Envía la petición:

# API oficial de MiniMax
H3_CREATE="https://api.minimax.io/v2/video_generation"
H3_QUERY="https://api.minimax.io/v2/query/video_generation"
# Servicio usado en la prueba (LaoZhang):
# H3_CREATE="https://api.laozhang.ai/hailuo/v2/video_generation"
# H3_QUERY="https://api.laozhang.ai/hailuo/v2/query/video_generation"

curl -s -X POST "$H3_CREATE" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "model": "MiniMax-H3",
    "content": [
      { "type": "text", "text": "Use reference video 1 only for its camera movement: a slow handheld push-in that drifts slightly around the subject. Do not copy the person, clothing, animals or field from reference video 1. New scene: an elderly fisherman in a yellow raincoat mends a net on a wooden pier at dawn, light rain, sea in the background." },
      { "type": "video_url", "role": "reference_video", "video_url": { "url": "https://tu-dominio.com/clip-referencia.mp4" } }
    ],
    "resolution": "768P",
    "duration": 4,
    "ratio": "16:9"
  }'

4. Guarda el task_id de la respuesta y consulta el estado cada 10 s hasta que task.status sea succeeded o failed; el vídeo está en task.content.url:

curl -s "$H3_QUERY/$TASK_ID" -H "Authorization: Bearer $API_KEY"

5. Descarga el resultado con curl o con el navegador y revisa dos cosas: los fotogramas, buscando cualquier elemento del clip original, y el bloque usage, donde input_seconds son los segundos de referencia cobrados.

El prompt de la prueba está en inglés, igual que los ejemplos oficiales. En español dice: «Usa el vídeo de referencia 1 solo para su movimiento de cámara: un acercamiento lento cámara en mano que se desplaza un poco alrededor del sujeto. No copies la persona, la ropa, los animales ni el campo del vídeo de referencia 1. Escena nueva: un pescador mayor con impermeable amarillo remienda una red en un muelle de madera al amanecer, lluvia ligera, el mar al fondo». La lista de exclusiones no es genérica: nombra exactamente lo que aparece en el clip.

La tarea apareció como succeeded en la consulta de los 45 s (el servidor registró 26 s entre la creación y la última actualización). La respuesta indicó total_seconds 11, input_seconds 7 y output_seconds 4, y el descuento en el saldo coincidió con esos 11 s a 0,05 $/s. El archivo salió a 1344×768, 24 fps, 4,46 s de duración, H.264 con audio AAC estéreo a 32 kHz y 3,5 MB. En una hoja de fotogramas a 1 por segundo se ve al pescador, el impermeable, el muelle y el mar al amanecer; el sujeto pasa del tercio izquierdo hacia el centro y crece un poco, que es el acercamiento con deriva lateral del clip de referencia. La lluvia ligera no se distingue con claridad. Al descargar, el CDN rechazó con un 403 el User-Agent por defecto de urllib en Python, y curl con un User-Agent de navegador funcionó.

Por qué falla o dice «temporary service error»: qué se rechaza y qué no

Una petición fuera de límites puede fallar de dos maneras: rechazada al enviarla, con un HTTP 400 que explica el problema, o aceptada con su task_id y fallida segundos después con un mensaje que invita a reintentar. El 2 de noviembre de 2026, con MiniMax-H3 a 768P, 4 s y 16:9 a través del mismo servicio de la prueba, ninguno de estos casos se cobró al final:

En los dos casos aceptados, el saldo subió 0,40 $ al crear las tareas (un precobro de 4 s × 0,05 $ por cada una) y volvió al valor inicial cuando fallaron. Ese «temporary service error» no era temporal: una petición válida enviada minutos después se completó sin problemas. Reintentar la misma petición fuera de límites no se probó, pero lo esperable es que vuelva a fallar igual. En el caso de 1,5 s no se puede separar la causa, porque se juntaron un clip demasiado corto y el envío en Base64, que la documentación de LaoZhang no admite para vídeo.

Cada plataforma valida a su manera. En pruebas publicadas por Atlas Cloud sobre las reglas de Reference-to-Video en su API en agosto de 2026, todas las peticiones incorrectas devolvían 200 y los errores aparecían de 2 a 3 minutos después; al mezclar un primer fotograma con referencias, una de las entradas se descartó en silencio y la tarea se cobró (0,40 $), y dos audios de referencia de unos 8 s (16,1 s en total) se completaron y cobraron aunque superaban el límite de 15 s para audio. Atlas no probó un total de vídeo por encima de 15 s. La regla práctica es quedarse dentro de los límites documentados en cualquier plataforma, porque una plataforma puede rechazarte, otra fallar con un mensaje engañoso y otra cobrarte un resultado que ignora parte de lo que enviaste.

Cuánto cuesta el vídeo de referencia: salida más segundos de entrada

En la API oficial de MiniMax, el vídeo de referencia se cobra por segundo de entrada al mismo precio por segundo que la resolución de salida elegida, así que la fórmula es: coste = (segundos de salida + segundos de referencia) × precio por segundo. La tabla de precios de pago por uso de MiniMax fija para MiniMax-H3 0,08 $/s a 768P y 0,13 $/s a 2K, con el audio de referencia gratis y las primeras 5 imágenes de cada tarea sin coste (después, 0,04 $ por imagen). La excepción es MiniMax-H3-Max: a 768P la salida cuesta 0,08 $/s pero el vídeo de entrada 0,143 $/s. La página oficial no aclara cómo se redondean los segundos de referencia.

El ejemplo real es la tarea de la prueba: 4 s de salida más 6,06 s de referencia, que se cobraron como 7 s, dan (4 + 7) × 0,05 $ = 0,55 $. Con el clip recortado a 6,00 s habrían sido (4 + 6) × 0,05 $ = 0,50 $. La misma petición con los precios oficiales de MiniMax-H3 costaría (4 + 6) × 0,08 $ = 0,80 $ a 768P y (4 + 6) × 0,13 $ = 1,30 $ a 2K, suponiendo que la API oficial también cuente segundos enteros. El modo de cobrar la referencia cambia mucho de una plataforma a otra:

La app de Hailuo muestra un precio en créditos («12 Credits/s» para vídeo) sin aclarar si se aplica también a la entrada. Para comparar H3 con otros modelos por precio por segundo y por clip, consulta ¿Cuánto cuesta un generador de vídeo con IA? De 0,03 a 0,60 $/s.

MiniMax H3 en local con ComfyUI: trampas del flujo R2V

En local, el vídeo de referencia funciona con el checkpoint Ref2VA de los pesos abiertos que MiniMax publicó el 3 de agosto de 2026, y la mayoría de los fallos vienen de la configuración, no del prompt. El flujo local no formó parte de la prueba del 2 de noviembre; lo que sigue procede del tutorial de MiniMax H3 en ComfyUI, de la documentación del nodo MiniMaxH3ReferenceToVideo y de la ficha del modelo en Hugging Face:

• Carga el modelo de difusión ref2va (minimax_h3_ref2va_pruned_int8_convrot), no el fl2va, que es el de primer y último fotograma.
• Conecta la entrada vae: sin ella, las imágenes y vídeos de referencia solo condicionan el codificador de texto y no generan latentes de referencia.
• Convierte el clip a 24 fps antes de cargarlo, porque el nodo lo lee a 24 fps sin mirar los metadatos; cada clip necesita al menos 5 fotogramas.
• Ajusta length a la duración que quieres: viene en 124 fotogramas (unos 5 s), se redondea a 17k+5 y los fotogramas de referencia que lo superan se recortan.
• Evita el LoRA Turbo de 4 pasos cuando la referencia tiene que notarse: es más rápido, pero debilita referencias y audio; la documentación recomienda 20–25 pasos, y los LoRA de estilo compiten con las referencias (alrededor de 0,5 de intensidad).
• Si quieres el sonido del clip, conecta ref_video_audio_N al mismo número que ref_video_N; si no, el audio del vídeo no se usa.

Los pesos abiertos generan a 768p y 24 fps, de 4 a 15 s; el módulo de 2K no se ha publicado y requiere las API alojadas de MiniMax. El nodo nativo usa etiquetas <Video 1> numeradas por tipo, mientras que el nodo de API de ComfyUI escribe Video 1. En hardware, la guía de SGLang cita 4×H200, 4×H100 o 2×RTX 5090 con 384 GiB de RAM, y una RTX 4090 con un pico de unos 18 GB probada en modo de fotogramas, no en modo referencia; en su ejemplo, una tarea con referencia tardó 260 s frente a 37 s de texto a vídeo.

Otras preguntas sobre el vídeo de referencia en MiniMax H3

¿Puedo pasar un resultado de 768P a 2K sin generarlo de nuevo?

Sí, en la API oficial de MiniMax existe Video Regeneration: repites todo el content de la petición original y añades el vídeo de 768P como video_url con el papel base_video, y la tarea devuelve la versión en 2K. Así se completa también el flujo de 2K con pesos abiertos, que combina la generación local con las API alojadas de MiniMax. Es comportamiento documentado a 2 de noviembre de 2026; la prueba con la referencia de cámara no lo incluyó.

¿Para qué sirve H3-Context-IR con un vídeo de referencia?

H3-Context-IR es una tarea de la API oficial que interpreta el texto y las referencias y devuelve solo un prompt mejorado, sin vídeo. Ese prompt sigue el formato estructurado de la guía oficial (tipos de tarea y marcadores como fully_preserved o weak_reference), así que sirve para ver qué papel cree el modelo que tiene cada referencia antes de pagar la generación. No es obligatorio: un prompt en lenguaje natural como el de la prueba también funciona.

¿MiniMax H3 Max admite vídeo de referencia?

En la API oficial sí, a 2 de noviembre de 2026: MiniMax-H3-Max acepta imágenes, vídeos y audios de referencia, a 480P o 768P y de 5 a 15 s, pero cobra el vídeo de entrada más caro que la salida. En la app de Hailuo, en cambio, el texto de la interfaz dice que solo H3 admite vídeos de referencia y que H3 Max trabaja con texto o con fotogramas inicial y final.

¿Pruebo H3 u otro modelo para vídeo con referencias?

Si todavía no has elegido modelo, la comparativa Wan 3.0 vs MiniMax H3 vs Seedance 2.5: cuál probar primero ordena los tres por duración, 2K, audio nativo, referencias, edición y despliegue local.