Video UGC de Vansaar
Foto de rostro + foto de producto + guion → un MP4 9:16, 1080×1920, 30 fps que parece grabado por un cliente indio de 45+ años en su teléfono en casa. Claude es el director: escribe el plan, verifica afirmaciones, revisa cada imagen y maneja un motor Python incluido (scripts/ugc.py) que llama a modelos de IA en fal.ai y edita el resultado con ffmpeg.
guion ─► voz (ElevenLabs) ─► tiempos de palabras ─► pausas ajustadas ─► un fragmento de audio por toma
rostro+producto ─► keyframes (Nano Banana Pro) ─► clips parlantes (OmniHuman 1.5) / B-roll (Kling 3)
todo ─► edición con cortes de salto + deriva de mano alzada + grano/grado de teléfono + audio de micrófono de teléfono
─► subtítulos + etiqueta de IA + tarjeta final (foto real del producto) ─► control de calidad ─► final.mp4
Reglas fundamentales
Estas protegen la marca y a las personas en el video. Explícalas al usuario cuando surjan; no te limites a rechazar.
- El rostro debe ser utilizable. Debe ser un personaje generado por IA o una persona real que haya dado permiso por escrito para usar su imagen en anuncios. Nunca un celebridad, influencer, médico o figura pública, y nunca alguien fotografiado sin consentimiento. Si no estás seguro de dónde vino el rostro, pregunta una vez.
- Mantén la etiqueta "Generado por IA". Está activada por defecto, como una pequeña etiqueta en la parte superior. Las pautas de influencers virtuales de ASCI y las reglas de contenido de IA de las plataformas la esperan. "Realista" significa buena artesanía, no engañar a los espectadores. Si el usuario quiere eliminarla, dile lo que las reglas esperan y deja la decisión a su responsable de cumplimiento (
disclosure.show: false). - Las afirmaciones deben ser seguras. Los productos ayurvédicos están sujetos a la Ley de Medicamentos y Remedios Mágicos y a las reglas de afirmaciones de salud de ASCI. Antes de generar cualquier cosa, ejecuta
check, luego reescribe cada bandera HIGH y señala cada una MEDIUM al usuario. El personaje de IA nunca debe describir sus propios resultados de salud ("mi azúcar bajó"): eso es un testimonio fabricado. Puede hablar sobre rutina, ingredientes, sabor y facilidad de uso. Los detalles están enreferences/compliance-india.md. - El dinero se mueve solo después de un "adelante". La voz y los keyframes cuestan centavos; los clips parlantes cuestan dólares. Detente en ambos puntos de control a continuación y muestra el costo antes de cada etapa pagada.
- Nunca le pidas al usuario que pegue una clave API en el chat. Indícales los pasos de configuración (archivo
.env,setkeyen su propia terminal, o su configuración de entorno).
Configuración (una vez por máquina / sesión)
SKILL_DIR es la carpeta que contiene este archivo. Los trabajos van en una carpeta que el usuario pueda abrir: en Claude Code usa ./ugc_jobs/<slug> en el proyecto actual; en un chat de claude.ai usa /mnt/user-data/outputs/ugc/<slug>.
pip install -r "$SKILL_DIR/requirements.txt" # añade --break-system-packages si pip se niega
python3 "$SKILL_DIR/scripts/ugc.py" doctor # verifica librerías Python, ffmpeg+libass, fuentes, clave, red
- Sin clave de fal.ai. Dile al usuario que cree una en fal.ai (Panel → Claves) y agregue crédito (US$10-20 cubren algunos videos). Luego la almacenan ellos mismos de una de tres maneras: un archivo
.envque contengaFAL_KEY=...en la carpeta donde se ejecuta Claude; ejecutandopython3 scripts/ugc.py setkeyen su propia terminal; o, en una sesión en la nube, una variable de entornoFAL_KEYen la configuración del entorno. - Red bloqueada (doctor muestra "no se puede alcanzar fal.ai"). El sandbox necesita permitir
queue.fal.run,rest.fal.ai,*.fal.mediaystorage.googleapis.com, además deapi.elevenlabs.iopara la opción de voz directa. Dile exactamente eso al usuario. Dónde cambiarlo está enreferences/troubleshooting.md. - ffmpeg faltante. Consulta
references/troubleshooting.md. - Pruébalo gratis.
python3 "$SKILL_DIR/scripts/ugc.py" demo --out <carpeta>ejecuta todo el pipeline con sustitutos offline (--mock). Prueba que la instalación funciona antes de gastar dinero.
Flujo de trabajo
Ejecuta comandos como python3 "$SKILL_DIR/scripts/ugc.py" <comando> --job <carpeta del trabajo>. Cada resultado pagado se almacena en caché en state.json del trabajo. Re-ejecutar un comando nunca paga dos veces por la misma entrada, y una solicitud interrumpida se recoge en la siguiente ejecución.
1. Recepción
Necesitas tres entradas: la imagen del rostro, la imagen del producto y el guion. Pregunta en un mensaje si falta algo, más lo que no puedas inferir:
- idioma: inglés, o hindi/hinglish
- el nombre exacto del producto
- duración objetivo (predeterminado: lo que el guion necesite naturalmente, entre 20-60 s)
- el género de la persona o preferencia de voz
- cualquier preferencia de entorno (predeterminado: un apartamento indio soleado)
Confirma aquí el consentimiento del rostro si no está claro.
Luego revisa ambas imágenes tú mismo:
- Rostro. Escribe
character.description: edad aparente, cabello, tono de piel, rasgos notables y vestimenta. Refuerza la identidad en cada prompt. Si la foto es de baja resolución, de perfil o está cubierta por gafas de sol, manos o una mascarilla, pide una clara de frente, porque la calidad de la sincronización de labios depende de ello. - Producto. Verifica que la etiqueta sea legible. Observa si el fondo es blanco liso o transparente (la tarjeta final puede recortarlo) o está ocupado (la tarjeta final lo muestra como una tarjeta). Si el usuario tiene un recorte PNG transparente, pídelo.
2. Pase del guion
Ejecuta init con --face, --product, --script (o --text), --lang, --title y --product-name. Luego ejecuta check --job <trabajo>.
Reescribe el guion para UGC hablado usando references/script-and-voice.md:
- un gancho en los primeros 2 segundos
- frases cortas habladas
- una idea por segmento
- una CTA suave
Corrige cada afirmación HIGH y mantén el significado del usuario. La duración es aproximadamente 2.5 palabras por segundo, así que 20 s son unas 50 palabras y 60 s unas 150. Para hindi, escribe say en devanagari (las palabras de marca en inglés pueden permanecer en escritura latina), porque el TTS lo pronuncia mucho mejor. Pon un caption en escritura romana junto a él si el usuario quiere subtítulos en hinglish.
3. Plan
Edita plan.yaml. La referencia de campos está en references/plan-reference.md; un ejemplo completo está en templates/plan.example.yaml. Lo que lo hace sentir real (detalles en references/realism-playbook.md):
- 2-3 escenarios en un hogar (p. ej., sofá medio, sofá cercano, producto en cocina). Debe parecer que una persona filmó algunas tomas, no una producción.
- Segmentos parlantes de 2-8 s. Los segmentos consecutivos con el mismo escenario obtienen zoom de corte automático.
- Un B-roll cada 2-3 segmentos parlantes: manos sirviendo, producto en la encimera, caminata matutina. El B-roll oculta cortes y muestra el producto adecuadamente. Usa
with_person: falsepara primeros planos del producto para que no se generen rostros dos veces. - El producto se sostiene en como máximo un escenario (
framing: product). Los productos pueden distorsionarse mientras las personas gesticulan, así que deja que el B-roll y la tarjeta final muestren el producto. - Dale a cada segmento una breve indicación de
performanceque coincida con la emoción de la línea. - Tarjeta final al final. La foto real del producto y el logotipo real se componen allí, por lo que la etiqueta siempre es correcta.
- Voz. Elígela con
references/script-and-voice.md. Las voces preestablecidas de fal son en su mayoría americanas o británicas. Para un acento indio, usaprovider: elevenlabscon una voz india de la Biblioteca de Voces de ElevenLabs, oprovider: filecon una grabación real (la opción más realista de todas).
Luego ejecuta validate (corrige todos los errores) y estimate.
PUNTO DE CONTROL 1. Envía un mensaje que contenga:
- la tabla de segmentos (id, toma, escenario, línea)
- las afirmaciones que se marcaron y lo que cambiaste
- la elección de voz
- los escenarios en una línea cada uno
- la duración y el costo estimados
Pregunta "¿adelante?" y no continúes hasta que el usuario diga que sí.
4. Voz y keyframes (baratos)
Ejecuta voice. Lee la tabla de duración. Si aparece una advertencia de "el transcript coincide solo con N%", el TTS pronunció mal o saltó palabras: reescribe esa línea (escribe los números, usa devanagari) y ejecuta voice --only <id> --force. Si el total está fuera de 20-60 s, recorta el guion o ajusta voice.speed (0.9-1.15).
Ejecuta frames, luego abre work/frames/contact.jpg y los candidatos a tamaño completo en work/frames/<key>/. Revisa cada uno contra la lista de verificación de keyframes en references/realism-playbook.md: la identidad coincide con la foto del rostro, piel natural, manos correctas, la etiqueta del producto coincide con la foto del producto, un hogar real, luz de cámara de teléfono. Establece pick: al mejor candidato. Si ninguno pasa, mejora la escena o descripción y ejecuta frames --only <escenario> --force. Haz como máximo 2 rondas por escenario, luego muestra al usuario qué está mal.
PUNTO DE CONTROL 2. Envía work/voice/vo_preview.mp3 y la hoja de contactos, di qué candidatos elegiste y por qué, y da el costo de los clips parlantes (la parte cara). Espera la confirmación. Cambiar la voz más tarde implica volver a hacer los clips parlantes.
5. Clips
Ejecuta clips. Los clips parlantes toman aproximadamente 1-5 minutos cada uno y se ejecutan 3 a la vez. Si uno falla, los demás se conservan, así que vuelve a ejecutar clips para reintentar solo los fallidos. Asegúrate de que ninguna advertencia diga que un clip es más corto que su audio.
6. Ensamblaje y control de calidad
Ejecuta assemble, luego qa. Abre out/<slug>_contact.jpg y verifica:
- sin deriva facial entre cortes
- sin manos o producto distorsionados
- los subtítulos no cubren la boca ni la etiqueta del producto
- el texto de la tarjeta final es legible
Si un clip es malo, ejecuta clips --only <id> --force, luego assemble nuevamente. Corrige cada FALLO que reporte QA; investiga cada VERIFICACIÓN.
7. Entrega
Envía out/<slug>.mp4 (y la hoja de contactos si es útil). En 3-5 líneas, da:
- duración y gasto estimado (
state.jsonmantiene el total acumulado) - cualquier afirmación que el usuario aún necesita que su responsable de cumplimiento apruebe
- que la etiqueta de IA está activada
- el uno o dos ajustes más probables para mejorar el siguiente video
Para producir también una copia sin subtítulos para editores, establece captions.clean_copy: true.
Correcciones rápidas
| Síntoma | Corrección |
|---|---|
| El rostro no se parece a la foto | character.description más rico, candidates: 3, foto fuente frontal más clara |
| Piel plástica o de filtro de belleza | regenerar; evita "hermosa/impecable" en las escenas; mantén grain ≥ 0.4 |
| Etiqueta del producto distorsionada | regenerar ese keyframe, o elimina el producto de los escenarios parlantes (la tarjeta final + B-roll lo muestran) |
| Labios se desvían o la boca se embarra | segmento más corto (≤ 6 s), keyframe frontal con boca visible, prueba el modelo Kling Avatar en config/models.yaml |
| Voz robótica | baja stability (0.35-0.45), comas para respiraciones, una grabación real, o el modelo eleven-v3 |
| Demasiado lento / demasiado largo | finish.tighten_pauses: 0.22, voice.speed: 1.08, recorta palabras |
| B-roll se ve falso | movimiento más simple (una acción), with_person: false, o motion: kenburns en un buen fotograma |
Más en references/troubleshooting.md.
Archivos de referencia (leer cuando sea necesario)
references/realism-playbook.md: qué hace que el UGC de IA se vea real; listas de verificación de keyframes y de revisión del video final. Leer antes de planificar escenarios y al revisar imágenes.references/script-and-voice.md: estructura de guion UGC para una audiencia india de 45+ años, escritura para TTS (hindi/hinglish), elección y ajuste de voces, ejemplos de guiones.references/compliance-india.md: consentimiento de imagen, divulgación de IA, reglas de la DMR Act / ASCI sobre afirmaciones, tabla de redacción segura. Leer cuandocheckmarque algo.references/plan-reference.md: cada campo deplan.yaml.references/models-and-costs.md: qué modelo hace qué, precios, cómo cambiar a modelos más nuevos.references/troubleshooting.md: instalación, claves, listas blancas de red, errores de API, correcciones.