Generación de Video con Avatares Digitales

¿Qué hace Generación de Video con Avatares Digitales?

¿Qué hace este skill?

Introduce tres cosas —un guion, una foto de perfil y una muestra de voz— y genera un video vertical de tipo "busto parlante" donde la persona sale en pantalla:

Se clona la voz de la persona para leer el guion, se usa Seedance 2.0-mini para sincronizar los labios de la foto con el audio, se añade un BGM generado por Suno, se incrustan subtítulos enriquecidos con resaltado de palabras clave y avance tipo karaoke, y finalmente se compone todo con ffmpeg. Todo el proceso utiliza únicamente APIs públicas documentadas. Cualquier agente que pueda ejecutar Python y ffmpeg puede seguir este skill, sin depender de un cliente específico.

Cada parámetro y cada problema de la tubería han sido validados en proyectos reales (ver references/); no es una solución teórica.

Entradas necesarias (pedir al usuario antes de empezar)

1. Guion: Guardar como script.md en la raíz del proyecto, una frase por línea, formato "1. Texto" "2. Texto". Las frases son la unidad de generación; si una frase es demasiado larga (más de 15 segundos), dividirla en dos.
2. Foto de perfil: Imagen en assets/, preferiblemente vertical 9:16 (p. ej. 1152×2048). La calidad de la foto determina directamente la calidad del resultado final: rostro de frente, iluminación uniforme, sin gafas de sol ni mascarilla. Si el usuario no tiene una foto adecuada, generarla con GPT Image 2 (ver references/api-reference.md) y pedir al usuario que confirme el aspecto antes de continuar.
3. Muestra de voz: Archivo de audio en assets/ de 15–30 segundos, voz limpia (sin música de fondo, sin reverberación), para la clonación de Fish Audio.
4. Dos claves API: Una de Fish Audio y otra de APIMART. Se pasan mediante variables de entorno. Prohibido escribirlas en cualquier archivo o mostrarlas en la salida de comandos. Los scripts las leen de variables de entorno; si falta alguna, se muestra un aviso y se sale, sin persistirla en disco.

Costes y cuentas

Componente	Modo	Coste (CNY)	Origen del modelo	Notas	Enlace de invitación
Persona	GPT Image 2	0.1	API APIMART	Solo si no hay foto	https://apimart.ai/register?aff=QVui
Video	Seedance 2.0-mini	10	API APIMART	720×1280, facturación por segundo	https://apimart.ai/register?aff=QVui
BGM	Suno	0.35	API APIMART	Modo solo música, dos pistas de una vez
Clonación de voz	s2.1-pro-free	0	API Fish Audio	Nivel gratuito, voice_id permanente	https://fish.audio/?aff=X7QT3YAX3N4Q4
Subtítulos	whisperx small	0	Local	Instalar el entorno una vez

Costes reales: Seedance 2.0-mini 720p ~0.039 USD/segundo; un video de 30 segundos ~12 CNY; la clonación de Fish Audio requiere saldo en la cuenta (saldo 0/0 devuelve error 403), el TTS es gratuito; Suno cuesta ~0.05 USD por pista. El coste real de un video completo es de aproximadamente 10–13 CNY.

Proceso en cinco fases

Cada fase tiene un control de acceso: si no se cumple, no se pasa a la siguiente. El estado se guarda en output/state.json, permitiendo reanudar desde un punto de interrupción.

Fase A: Voz (Fish Audio)

1. python scripts/avatar_voice.py clone: Subir la muestra de voz para crear un modelo de clonación privado y obtener el voice_id.
2. python scripts/avatar_voice.py tts: Sintetizar cada frase del script.md en WAV.
3. python scripts/avatar_voice.py fixwav: Reparar la cabecera del archivo WAV (la cabecera devuelta por Fish declara una longitud mayor que la real; sin repararla, algunos decodificadores cortan el audio).
4. python scripts/avatar_voice.py qc: Verificar la duración, el volumen medio y el clipping de cada frase.

Control: Todas las frases deben tener un volumen no inferior a -30 dBFS y sin clipping. La duración estimada es solo una referencia, no un objetivo fijo —está estrictamente prohibido hacer estiramientos de audio para alcanzar una duración (ver reglas de hierro). El usuario debe escuchar y confirmar que el timbre se parece a su voz para superar la fase.

Fase B: Video (Seedance 2.0-mini)

1. python scripts/avatar_video.py upload-image: Subir la imagen de perfil a APIMART para obtener una URL pública.
2. python scripts/avatar_video.py host-audio: Alojar cada archivo WAV mediante tmpfiles.org y extraer el enlace directo /dl/ (APIMART no tiene endpoint para subir audio; el enlace directo caduca en 60 minutos, así que se envía inmediatamente después de la subida).
3. python scripts/avatar_video.py submit: Enviar cada frase. Parámetro clave: generate_audio=False (el video se genera en silencio; la sincronización labial se basa en el audio externo —este es el interruptor para la ruta de avatar digital). La duración se redondea al alza según la duración del audio. Si el coste estimado de un solo segmento supera 1 USD, se detiene automáticamente.
4. python scripts/avatar_video.py poll + download: Sondeo y descarga.

Control: Revisar fotogramas para asegurar que la persona no se distorsiona ni cambia de rostro; la boca debe abrirse y cerrarse. Si se cambia el audio, es necesario repetir esta fase —la sincronización labial del video antiguo se generó para el audio anterior; simplemente reemplazar la pista de audio no garantiza la sincronización.

Fase C: BGM (Suno)

1. Leer el guion y redactar un brief musical (estilo/estado de ánimo/BPM/curva de energía/elementos a evitar). Ver el paradigma en references/prompts.md.
2. python scripts/avatar_bgm.py generate: Modo instrumental, generar dos candidatos.
3. python scripts/avatar_bgm.py mix: Recortar, fundidos de entrada/salida, comprimir a ~-16dB por debajo de la voz, aplicar compresión sidechain para ducking, y mezclar en el video final.
4. El usuario escucha y elige una. La apreciación musical es subjetiva; la automatización llega hasta "generar candidatos aceptables"; la selección queda para la persona.

Fase D: Subtítulos (ASS enriquecidos, sin coste local)

Sin depender de ningún servicio en línea, se utiliza ASS/libass para lograr un efecto de subtítulos cercano al de un software de edición profesional. avatar_caption.py tiene seis capacidades (cada una verificada fotograma a fotograma; no son descripciones teóricas):

Capacidad	Cómo configurarlo	Descripción
Agrupación de Cues	Escribir || en las líneas del script.md	Dividir una frase larga en dos líneas de subtítulos con temporización independiente
Resaltado de palabras clave	spec.keywords	Por ejemplo, AI → cian, 5000人 → dorado; coincide con palabras completas tanto en chino como en otros idiomas
Avance karaoke carácter a carácter	spec.karaoke.enabled	Se ilumina el carácter que se está leyendo; los leídos no retroceden
Texto dual	spec.dual_text	Decir "diez" y mostrar "10" en pantalla; separar habla oral de texto escrito
Cambio de estilo por ventana de tiempo	spec.emphasis	Especificar un intervalo (p. ej., 3–6 segundos) con tamaño de fuente mayor u otro color para frases destacadas
Doble pista (chino/inglés) + animaciones	spec.points	Pista principal en chino + pista secundaria con puntos clave en inglés, con \fad para fundidos y \t para zoom de aparición

python scripts/avatar_caption.py spec    # Escribe plantilla output/caption-spec.json
python scripts/avatar_caption.py all     # Genera ASS + lo incrusta en digital-human-captioned.mp4

Prioridad de la fuente del texto de subtítulos: --srt especificado > output/digital-human.srt de whisperx > duración de voice/qc.json + texto original de script.md. Cuando hay texto original del guion, se prefiere usar el original (añadiendo --prefer-script), ya que es más preciso que la transcripción ASR y no requiere whisperx.

Dos convenciones imprescindibles de libass (ambas han causado problemas, ver references/pitfalls.md): el color no leído en karaoke es SecondaryColour, el leído cambia a PrimaryColour y se mantiene; la unidad de \k es centisegundos y la suma total debe ser igual a la duración del Cue correspondiente, configurarlo como porcentaje haría que el karaoke terminara en un segundo.

Si el usuario prefiere usar herramientas como Jianying para los subtítulos, esta fase se puede omitir, pero debe indicarse en la entrega.

Fase E: Composición y control de calidad

Las cuatro partes de video se recortan para alinearse con la duración del audio, se redimensionan a 1080×1920, 30 fps, la pista de audio se toma de la Fase A (se descarta la pista de audio original del video), y se componen con ffmpeg. La plantilla del comando de composición está en references/prompts.md.

Control de calidad: la duración total coincide con la suma de las partes; la forma de onda del audio está alineada con la voz; sin clipping; decodificación completa.

Reglas de hierro (cada una aprendida en casos reales)

1. Prohibido usar atempo u otros procesamientos para estirar el audio y alcanzar una duración. El estiramiento provoca una velocidad de habla reducida y una sensación de arrastre. Para ajustar la velocidad, usar el parámetro nativo prosody.speed de Fish TTS para regrabar (p. ej., s3=0.85, s4=0.9), o aceptar la duración natural.
2. Las claves API solo deben estar en la memoria del proceso. Se pasan mediante variables de entorno, el script las limpia con atexit, y cualquier cadena en la salida que coincida con una clave se reemplaza por un marcador de posición. No debe haber claves en archivos del proyecto, informes ni registros.
3. Si la misma operación falla dos veces seguidas, detenerse, escribir un informe con la causa, y no reintentar indefinidamente. HTTP 401 detiene inmediatamente (problema de clave). Si el coste estimado de un solo segmento de video supera 1 USD, detenerse.
4. La duración estimada es una referencia, no un indicador. El estándar de control de calidad para el ejecutor no debe ser "rellenar hasta alcanzar una cifra".
5. La preferencia auditiva del usuario prevalece sobre las estadísticas automáticas. Aunque la duración, el volumen y la ausencia de clipping sean correctos, si el usuario dice que a partir del segundo 10 algo suena mal, entonces hay un problema; investigar desde ese punto.
6. Lo que no haya pasado una revisión manual no puede llamarse producto final. En la entrega, indicar claramente qué elementos se han verificado y cuáles no.

Solución rápida de problemas de entorno (Windows)

En Windows, se han confirmado cuatro problemas al ejecutar esta tubería. Leer references/pitfalls.md antes de empezar:

Las peticiones Python deben tener trust_env=False para evitar conectarse a un proxy incorrecto; el sandbox y el sistema de archivos real son vistas diferentes; los enlaces directos de tmpfiles requieren analizar la página de vista previa; la cabecera WAV de Fish debe repararse. Cada problema incluye causa raíz y solución.

Uso de los scripts

export APIMART_API_KEY=... FISH_API_KEY=...   # O dejar que el script los pida al ejecutarse
python scripts/avatar_voice.py all     # Fase A completa
python scripts/avatar_video.py all     # Fase B completa
python scripts/avatar_bgm.py all       # Fase C
python scripts/avatar_caption.py all   # Fase D (no necesita clave)

Script	Fase	¿Necesita clave?	Función
avatar_voice.py	A	Fish Audio	Clonación de voz, TTS por frase, reparación de cabecera WAV, control de calidad
avatar_video.py	B	APIMART	Subir imagen, alojar audio, enviar video de sincronización labial, sondeo y descarga
avatar_bgm.py	C	APIMART (generate sí, mix no)	Generar candidatos de BGM con Suno, mezcla con sidechain ducking
avatar_caption.py	D	No	Generación e incrustación de subtítulos enriquecidos
avatar_compose.py	E	No	Montaje, redimensionado, transcripción, revisión final

Los scripts leen script.md y assets/ del directorio actual, escriben en output/, guardan el estado en output/state.json. Si se interrumpen y se vuelve a ejecutar el mismo comando, se reanudan. Cada script admite --help para ver los subcomandos.

Límites de seguridad (compromiso para distribuir a terceros)

• Los scripts solo se conectan a cuatro endpoints documentados: api.fish.audio, api.apimart.ai, tmpfiles.org, y ffmpeg/whisperx local. Sin telemetría, actualizaciones automáticas ni estadísticas anónimas.
• No leen ni escriben fuera del directorio del proyecto.
• Las claves API solo están en la memoria del proceso; se borran al salir. Todo el texto que se persiste pasa por un filtro de patrones de clave.
• El paquete completo se puede auditar por completo: SKILL.md + references/ + scripts/, sin binarios ni pasos de instalación ejecutables.