MiniMax Video (H3)

MiniMax Video Oficial

Usa scripts/minimax_video.py de esta habilidad para conectarse directamente a la API V2 oficial de MiniMax. Por defecto usa el sitio nacional https://api.minimax.cn y el modelo MiniMax-H3; el sitio internacional es https://api.minimax.io. Generalmente, las nuevas tareas de MiniMax deben usar esta habilidad; las tareas de Nǎdūtōng deben ser consultadas por el cliente original, los ID de tarea no migran entre servicios.

Configuración

• Localiza el script desde el directorio de instalación real de la habilidad. Prioriza ~/.config/minimax/venv/bin/python; la entrada de solo texto, HTTPS o mm_file:// solo necesita Python 3.9+. La validación de materiales locales y el R2 opcional requieren las dependencias en scripts/requirements.txt.
• Las credenciales se leen de MINIMAX_API_KEY, priorizando la variable de entorno; de lo contrario, se parsea ~/.config/minimax/env. No se leen credenciales de chat de otras aplicaciones, ni se escriben claves en la habilidad, línea de comandos o registros de tareas. Consulta configuración y recuperación para el sitio nacional/internacional y el entorno de herramientas.
• Si falta la clave, usa scripts/configure.py --region cn --gui para entrada oculta en macOS; en otros sistemas, entrada oculta en la terminal del usuario. No pidas al usuario que pegue la clave en el chat. Si el usuario tiene una variable de entorno existente, usa --from-env; para rotación, --replace-key.
• doctor --check-api solo lee la lista de tareas recientes para verificar autenticación y la API de consulta V2; no verifica saldo, permisos de generación de un modelo específico ni la calidad del video final. La instalación, configuración e investigación de la API no autorizan generación paga.

Parámetros y Entrada

Al seleccionar un modelo, parámetros no predeterminados o materiales multimodales, primero lee API oficial y capacidades y no uses los modelos, resoluciones 720p/960p o límites de 4–12 segundos de Nǎdūtōng.

• Por defecto: H3, 4 segundos, 768P; texto plano por defecto 16:9; primer/último fotograma determinan la proporción según la imagen de entrada. Los cuatro modelos H3 tienen límites diferentes de resolución, duración y proporciones; el cliente valida según el modelo.
• --first-frame y --last-frame cada uno como máximo una imagen; las referencias multimodales usan los parámetros repetibles --ref-image, --ref-video, --ref-audio. No se pueden mezclar primer/último fotograma con referencias multimodales. Mantén el orden de los materiales y especifica roles como "referencia imagen 1", "referencia video 1" en el prompt.
• Los materiales soportan archivos locales, URLs HTTPS y handles mm_file:// de la cuenta oficial actual. La entrada local guarda primero una copia inmutable y valida formato, tamaño, duración, etc.; las especificaciones de contenido remoto son validadas por el oficial, sin afirmar que se hayan revisado localmente.
• Los materiales locales pequeños usan --delivery inline por defecto, enviados con la solicitud de generación en formato data URI oficial, sin necesidad de hosting de terceros. El tamaño total de la solicitud expandida en Base64 no debe exceder 64 MB; para archivos MOV locales o grandes, usa explícitamente --delivery r2 y luego ejecuta host. No subas, transcodifiques ni modifiques archivos originales para eludir límites.
• El modo R2 solo usa buckets privados configurados, reutiliza objetos por hash y verifica descargas anónimas. Antes de subir, cumple con las convenciones de materiales y privacidad del proyecto de destino; solo aloja dentro del ámbito de materiales autorizados para la tarea actual. Si falla la configuración o el hosting, reporta pero no cambies automáticamente de host de imágenes.

Producción y Consulta

Cuando el usuario solicite generar un video, completa un candidato; los intentos por lotes y adicionales siguen esta convención. Cada candidato usa un nuevo directorio de tarea, priorizando tmp/artwork/generations/<run-id>/<asset-id>/<attempt-id>/ ignorado por el proyecto; si no hay proyecto, usa un directorio temporal del espacio de trabajo o una ubicación especificada por el usuario, sin sobrescribir tareas antiguas.

1. Usa doctor --check-api para verificar la configuración. Escribe las acciones, planos, restricciones de personajes/objetos y requisitos de sonido en un archivo de prompt UTF-8, usa prepare para congelar el prompt, parámetros oficiales, región de servicio y copias de entrada. Este paso es offline, no genera video.
2. Solo ejecuta host si --delivery r2 y hay materiales locales. Esta operación sube los materiales al R2 privado y permite que MiniMax use enlaces firmados; los materiales inline se envían directamente a MiniMax.
3. Ejecuta submit una vez. El cliente guarda exclusivamente el registro de envío y el hash de la solicitud antes de la POST paga; el oficial no promete idempotencia de clave en su documentación, por lo que no uses UUID de solicitud local como garantía de deduplicación del servidor.
4. Usa status independiente para consultar estados: queued / running / succeeded / failed / cancelled. Usa espera interrumpible por el host y mantén comunicación de progreso, sin hacer polling en comandos largos de shell durante minutos.
5. Tras éxito, usa download para descargar, verificar el MP4 y guardar el hash. Si falla la descarga, solo reintenta status / download; las URLs de medios caducados se pueden actualizar con una nueva consulta. El oficial solo proporciona consulta de tareas en los últimos 7 días, así que guarda inmediatamente en disco.
6. Para recuperación entre diálogos, primero inspect --job, luego status / download. Cualquier submission.json previene reenvío. Timeout, desconexión, error 5xx o falta de ID son resultados inciertos; conserva evidencia. Puedes usar tasks de solo lectura como ayuda, pero la similitud de modelo y tiempo no prueba que sea la misma tarea. No crees automáticamente candidatos pagos adicionales si falla o el resultado es incierto.

Ejemplo de comandos (las variables representan rutas absolutas reales; JOB no debe existir aún):

"$PY" "$CLIENT" doctor --check-api
"$PY" "$CLIENT" prepare --job "$JOB" --prompt-file "$PROMPT_FILE" --first-frame "$FIRST_FRAME" --duration 4 --resolution 768P
"$PY" "$CLIENT" submit --job "$JOB"
"$PY" "$CLIENT" status --job "$JOB"
"$PY" "$CLIENT" download --job "$JOB"

Para texto plano, omite --first-frame y da --ratio según sea necesario; para primer/último fotograma, añade --last-frame. Para referencias multimodales, usa los parámetros --ref-* correspondientes. En modo R2, añade --delivery r2 al preparar y ejecuta host --job "$JOB" antes de submit. Opciones completas en --help del script.

Entrega

Entrega el archivo video.mp4 local reproducible y el directorio de la tarea, mostrando el video con la ruta absoluta. Explica el modelo real, duración, resolución, proporción y rendimiento de sonido, y si se revisó el video a velocidad original, primer/último fotograma y consistencia de personajes; el éxito HTTP no equivale a aprobación visual.

El registro de la tarea contiene el prompt, materiales Base64, URLs firmadas y ID real de la tarea, solo legible por el usuario actual; no lo pegues completo en el chat ni lo subas a Git. La consola muestra la huella de la tarea; el Bearer de la API oficial solo se envía a los hosts permitidos de la API oficial; el video final y todas sus redirecciones se descargan de forma anónima por HTTPS.