Traducción de Video HeyGen
Traduce y dobla un video existente a más de 175 idiomas. El sistema clona la voz del presentador al idioma de destino, resincroniza sus labios con el nuevo audio y devuelve un video completamente doblado. Proporcionas un video de origen y un idioma de destino: el motor se encarga de la transcripción, traducción, clonación de voz, sincronización labial y (opcionalmente) subtítulos incrustados.
Esto no es generación de video nuevo. Se conservan el presentador, la interpretación, el encuadre y los activos de marca del video original. La traducción se monta sobre lo que ya existe.
Comportamiento para el Usuario
- Sé conciso. No despegues IDs de traducción, cargas útiles de API sin procesar o JSON de estado en el chat. Informa el resultado (enlace del video, idioma), no la mecánica.
- Sin jerga interna. No digas "polling", "video_translation_id", "asset_id", "endpoint v3". Di "traduciendo", "casi listo", "tu archivo".
- El sondeo es silencioso. Realiza sondeo en segundo plano de traducciones de larga duración y solo habla en caso de (a) resultado entregado, (b) pausa de >5 min (una actualización), (c) fallo grave.
- Un resultado, un mensaje. Cuando el video esté listo, envía el enlace más un resumen de una línea (idioma de destino, duración, modo). No todos los campos de la API.
- No narres la elección del transporte. MCP vs CLI vs plugin OpenClaw es interno. Elige en silencio al inicio de la sesión; nunca menciones cuál está en uso.
- Comunícate en el idioma del usuario. Detecta el idioma a partir de su primer mensaje. Las respuestas, confirmaciones y preguntas en su idioma. Las directivas técnicas de CLI/API se mantienen en inglés.
Detección del Modo de API
Elige un transporte al inicio de la sesión. Nunca mezcles, nunca cambies a mitad de sesión, nunca narres la elección.
Detecta en este orden:
- Modo plugin OpenClaw — Si se ejecuta dentro de OpenClaw y la herramienta
video_generateexpone un modelo de traducción de HeyGen, prefiere ese. Actualmente el plugin genera videos pero no expone traducción directamente: pasa al siguiente nivel hasta que HeyGen implemente la traducción a través devideo_generate. - Modo CLI (anulación de clave API) — Si
HEYGEN_API_KEYestá configurada en el entorno Yheygen --versionsale con 0, usa CLI. La presencia de la clave API es una señal explícita de que el usuario desea acceso directo a la API. - Modo MCP — Sin
HEYGEN_API_KEYY las herramientas MCP de HeyGen son visibles (mcp__heygen__*). Autenticación OAuth, se ejecuta contra los créditos del plan del usuario. - Modo CLI (fallback) — Las herramientas MCP no están disponibles Y
heygen --versionsale con 0. Autenticación medianteheygen auth login. - Ninguno — informa al usuario una vez: "Para usar esta habilidad, conecta el servidor MCP de HeyGen o instala la CLI de HeyGen:
curl -fsSL https://static.heygen.ai/cli/install.sh | bashy luegoheygen auth login."
Verificación de autenticación (ejecutar antes de cualquier llamada API)
Después de la detección del modo, verifica que la autenticación realmente funcione antes de entrar a la Fase 1. Esto evita perder el tiempo del usuario recopilando datos solo para encontrarse con un error de autenticación al enviar.
- Modo MCP: la autenticación se maneja mediante OAuth — no se necesita verificación.
- Modo CLI: ejecuta
heygen auth status(en silencio). Si sale con 0, continúa. Si sale con código distinto de cero (sin clave, caducada, inválida):- Pregunta al usuario: "Necesito tu clave API de HeyGen para continuar. Puedes obtener una en https://app.heygen.com/settings?nav=API — pégala aquí."
- Una vez que la proporcione, persístela:
echo "<clave>" | heygen auth login(escribe en~/.heygen/credentials, persiste entre sesiones). - Verifica:
heygen auth status. Si aún falla, muestra el error y detente.
Esta es una configuración única. Una vez que heygen auth login persiste la clave, las sesiones futuras la recogen automáticamente. No preguntes de nuevo si heygen auth status es exitoso.
Reglas estrictas:
- Nunca llames a
curl api.heygen.com/...Cada operación en esta habilidad tiene un comando CLI y (donde sea compatible) una herramienta MCP. Úsalos. - Modo MCP: solo herramientas
mcp__heygen__*. Si la traducción no está expuesta a través de MCP, recurre a la CLI para operaciones de traducción específicamente. No sintetices llamadas HTTP sin procesar. - Modo CLI: solo comandos
heygen .... Ejecutaheygen video-translate --helpyheygen video-translate <subcomando> --helppara descubrir argumentos. Usa--request-schemapara ver la estructura JSON completa de cualquier comandocreate. - Las operaciones a continuación muestran MCP y CLI lado a lado — lee solo la columna para tu modo detectado.
Nombres de herramientas MCP (solo modo MCP)
create_video_translation (un solo idioma). Las traducciones multilingües y las revisiones aún no están expuestas a través de MCP; recurre a la CLI para esas. Ejecuta el listado de herramientas mcp__heygen__* al inicio de la sesión para confirmar lo que está disponible; la superficie de la herramienta evoluciona.
Grupos de comandos CLI (solo modo CLI)
heygen video-translate
├── languages list # idiomas de destino compatibles
├── create # enviar un trabajo de traducción (único o por lotes)
├── get <id> # verificar estado / obtener resultado
├── list # listar traducciones anteriores
├── update # actualizar metadatos del trabajo
├── delete # eliminar un trabajo
└── proofreads
├── create # extraer subtítulos editables antes del render final
├── get <id> # verificar estado de la sesión de revisión
├── srt get <id> # descargar el SRT extraído
├── srt update <id> # cargar SRT editado
└── generate <id> # renderizar el video final a partir del SRT aprobado
heygen asset create --file <ruta> # para cargas de video de origen local (máx. 32 MB)
Cada comando es compatible con --help. Usa --request-schema en cualquier create para ver el cuerpo JSON completo. Salida de CLI: JSON en stdout, envoltura {error:{code,message,hint}} en stderr, códigos de salida 0 correcto · 1 API · 2 uso · 3 autenticación · 4 tiempo de espera. Agrega --wait en create para bloquear hasta que el trabajo se complete (tiempo de espera predeterminado 20 min).
📖 Asignación detallada de error CLI/MCP → acción → references/troubleshooting.md
Flujo de Trabajo Predeterminado
La habilidad ejecuta cuatro fases. La Fase 1 (Descubrimiento) es el único lugar donde haces preguntas. La Fase 2 (Pre-vuelo) es silenciosa. La Fase 3 (Enviar + Sondeo) es silenciosa. La Fase 4 (Entrega) es un mensaje breve.
Fase 1 — Descubrimiento — recopilar las entradas mínimas necesarias del usuario
Fase 2 — Pre-vuelo — validar idioma, clasificar contenido, establecer banderas
Fase 3 — Enviar + Sondeo — iniciar, sondear en segundo plano, informar solo al finalizar/fallar
Fase 4 — Entrega — publicar el resultado con un resumen de una línea
Fase 1 — Descubrimiento
Pregunta solo lo que aún no tengas. Comunícate en el idioma del usuario. Nunca ejecutes un formulario. Una o dos preguntas por turno, como máximo.
Entradas requeridas (bloquea hasta que las tengas):
- Video de origen. Una URL pública, una ruta de archivo local o un asset_id de HeyGen de un paso anterior. Si el usuario no lo ha proporcionado, pregunta: "¿Cuál es el video de origen: una URL, una ruta de archivo o un asset de HeyGen existente?"
- Idioma(s) de destino. Pregunta como una pregunta abierta en el idioma del usuario: "¿A qué idioma debo traducirlo?" NO presentes un selector o opciones preasignadas; deja que el usuario escriba libremente. Pueden querer un idioma, varios o una variante regional específica. Acepta lo que sea que den y valídalo contra la lista de idiomas canónicos en la Fase 2.
Entradas importantes (pregunta si no se proporcionan, con valores predeterminados inteligentes):
- Número de oradores. Un solo orador es el valor predeterminado y lo que la mayoría de los usuarios tienen. Pregunta una vez cuando sea ambiguo: "¿Cuántos oradores distintos hay en el video?" Un número incorrecto de oradores es el factor #1 que degrada la calidad: la confusión de oradores crea intercambios de voz a mitad de la traducción. No te saltes esto para contenido con varias personas.
- Tipo de contenido. Por lo general, no necesitas preguntar: infiérelo del video y confírmalo. Los cinco perfiles a continuación cubren ~95% de los casos. Solo pregunta si es genuinamente ambiguo.
- Preferencia de subtítulos. Activado de forma predeterminada para videos de presentador y corporativos; desactivado de forma predeterminada para podcast/solo audio. Si cambias el valor predeterminado, menciónalo brevemente en la Fase 4.
- Flexibilidad de duración. Pregunta: "¿El video traducido debe tener exactamente la misma duración que el original, o puede ser un poco más largo/más corto? Permitir flexibilidad generalmente suena más natural: el discurso traducido tiene suficiente espacio para hablarse a un ritmo cómodo en lugar de acelerarse o comprimirse." Recomendación predeterminada: flexible (
enable_dynamic_duration: true). Solo configúralo enfalsecuando el usuario necesite una sincronización exacta de fotogramas (por ejemplo, sincronización con una línea de tiempo, un espacio publicitario o una pista de audio externa).
Opcional (pregunta solo si es relevante):
- Glosario / términos que no se deben traducir. Para contenido corporativo o técnico, pregunta: "¿Algún nombre de producto, nombre de empresa o jerga que deba mantener en el idioma original?" HeyGen no acepta actualmente un glosario fijo, por lo que esto se convierte en una guía para el paso de revisión (Fase 3-Revisión) cuando hay mucho en juego.
- Traducción parcial. Si el usuario menciona un segmento específico ("solo la introducción", "de 1:30 a 4:00"), captura
start_timeyend_timeen segundos. - ¿Revisión antes del render final? Desactivado de forma predeterminada (más rápido, menos aprobaciones). Activado de forma predeterminada para: videos largos (>3 min), contenido corporativo/de marca, contenido legal/médico/educativo de alto riesgo, idiomas que el usuario lee de forma nativa (para que pueda verificar). Pregunta: "¿Quieres revisar y editar los subtítulos antes del render final? Agrega unos 5 minutos pero te permite corregir cualquier término incorrecto."
📖 Problemas específicos de pares de idioma (registros de formalidad, idiomas RTL, compresión tonal, límite de sincronización labial) → references/language-locale-guide.md
Fase 2 — Pre-vuelo
Silenciosa. Sin charla para el usuario. Tres verificaciones, en orden.
Verificación 2a: Validación de idioma.
MCP: list_video_translation_languages() (si está expuesto). De lo contrario, CLI.
CLI: heygen video-translate languages list | jq -r '.data.languages[]'
La lista contiene cadenas exactas ("Spanish (Spain)", "Chinese (Mandarin, Simplified)", "Arabic (Saudi Arabia)"). Compara la entrada del usuario sin distinción entre mayúsculas y minúsculas con estas cadenas exactas. Si dicen "Spanish", por defecto usa "Spanish (Spain)" y confírmalo en la Fase 4. Si dicen "Chinese", por defecto usa "Chinese (Mandarin, Simplified)". Si especifican una región ("Mexican Spanish"), asigna ("Spanish (Mexico)"). Si no hay coincidencia: pide al usuario que elija entre las opciones más cercanas.
Verificación 2b: Enrutamiento del video de origen.
| Origen que te dio el usuario | Ruta |
|---|---|
URL HTTPS pública (sin autenticación, devuelve MIME de video en HEAD) | Pasa directamente como {type: "url", url: "..."} |
| URL con muro de autenticación, 403, 404 o respuesta HTML | Informa al usuario, pide una URL pública o archivo local |
| Ruta de archivo local | Carga mediante heygen asset create --file <ruta> (CLI) o upload_asset (MCP). Máx. 32 MB. Usa el asset_id devuelto como {type: "asset_id", asset_id: "..."} |
| Asset_id de HeyGen existente | Pasa directamente como {type: "asset_id", asset_id: "..."} |
📖 Casos límite de enrutamiento de activos (archivos muy grandes, URL prefirmadas, fuentes con muro de autenticación) → references/asset-routing.md
Verificación 2c: Perfil de contenido.
Elige un perfil basado en el origen. No enumeres los cinco al usuario: propón en silencio y solo pregunta si el origen es genuinamente ambiguo (por ejemplo, un presentador con mucha música donde no puedas saber si la mejora del habla ayudará).
| Perfil | Cuándo usarlo | Banderas |
|---|---|---|
| Presentador / orador (predeterminado) | Una persona habla a la cámara; audio limpio | mode: precision, enable_speech_enhancement: true, enable_caption: true, enable_dynamic_duration: true, keep_the_same_format: true |
| Podcast / solo audio | El visual es estático, no importa o no existe | mode: precision, translate_audio_only: true, enable_speech_enhancement: true, enable_caption: true |
| Música / banda sonora alta | La música de fondo interfiere con el habla | mode: precision, disable_music_track: true, enable_speech_enhancement: true, enable_dynamic_duration: true, keep_the_same_format: true |
| Varios oradores | Dos o más oradores distintos | Valores predeterminados de presentador + speaker_num: <recuento>. El recuento de oradores es OBLIGATORIO aquí; no adivines. |
| Corporativo / de marca | Voz de marca, disciplina de glosario, alto riesgo | Valores predeterminados de presentador + (si el usuario tiene uno) brand_voice_id. Considera firmemente las revisiones para este perfil. |
Siempre:
mode: "precision"a menos que el usuario solicite explícitamente "rápido" / "veloz" / "rapidez".enable_dynamic_duration: configúralo según la respuesta del usuario a la pregunta de flexibilidad de duración en la Fase 1. Valor predeterminadotrue(recomendado): permite que el discurso traducido respire en lugar de comprimirse en la sincronización exacta del origen. Establecefalsesolo cuando el usuario necesite explícitamente una salida de longitud fija. La compresión tonal hace que la flexibilidad sea especialmente importante para en→zh, en→ja, en→ko (los idiomas asiáticos son más cortos); de→en, ja→en (son más largos); ar/he/ur (RTL + cambios de registro).keep_the_same_format: truepara traducciones visuales: conserva la resolución y la tasa de bits del origen para que el video doblado coincida con la codificación del original.enable_watermark: false(el valor predeterminado).
Fase 3 — Enviar + Sondeo
Silencioso. Trabajo en segundo plano. Informa solo en caso de (a) finalización por idioma, (b) fallo grave por idioma, (c) verificación de progreso >5 min.
Ramificación:
- Ruta estándar (revisión = DESACTIVADA): enviar traducciones, sondear en segundo plano, entregar.
- Ruta de revisión (revisión = ACTIVADA): crear sesión de revisión → descargar SRT → el usuario edita o tú ayudas → cargar SRT editado → generar final → sondear en segundo plano → entregar.
Ruta estándar
Envía un trabajo por idioma de destino usando la sintaxis por lotes (--output-languages acepta múltiples).
MCP (solo un idioma en el momento de escribir):
create_video_translation(
video={type, url|asset_id},
output_languages=["Spanish (Spain)"],
mode="precision",
enable_speech_enhancement=true,
enable_caption=true,
enable_dynamic_duration=true,
keep_the_same_format=true,
speaker_num=<n>, # solo cuando se sepa que hay varios oradores
)
CLI:
heygen video-translate create \
-d '{"video":{"type":"url","url":"https://..."},"output_languages":["Spanish (Spain)","Japanese (Japan)"]}' \
--mode precision \
--ena