ai-product-video

Video de Producto con IA

División principal del trabajo:

• Fotos 3D o del producto: Determinan dónde está, qué tamaño tiene, cómo se mueve y cuándo cambia.
• Modelo de imagen: Se encarga de que el producto se vea realista.
• Modelo de video: Se encarga de que el producto se mueva.
• Código: Utiliza los datos del producto y el modelo 3D como regla para medir cada imagen y cada video generado por la IA; si no pasa la medida, no se gasta dinero.

La edición, los subtítulos, las anotaciones y el audio son capas superpuestas basadas en datos; cambiar una palabra no requiere regenerar las imágenes.

Este método proviene de un proyecto real: un video demostrativo para inversionistas de un producto de hardware inteligente, que requirió cuatro iteraciones de la ruta para lograr el resultado deseado. El análisis anónimo se encuentra en examples/case-study.md. A continuación se describe la versión genérica después de que la ruta funcionó, aplicable tanto a videos explicativos como a anuncios.

Por qué no se puede copiar directamente el flujo de trabajo de las series animadas con IA

El flujo de trabajo de las series animadas con IA es: Configuración → Storyboard → Biblioteca de activos → Fijar fotogramas estáticos → El modelo de video hace que la imagen se mueva → Doblaje y edición. No tiene modelos 3D, y la audiencia tolera imprecisiones en los detalles, por lo que la imagen generada por IA es la respuesta estándar.

Los videos de productos venden "este producto se ve así y funciona así". Si la dirección de la interfaz, las etiquetas o la posición de la luz se dibujan incorrectamente, el video está mintiendo. Por lo tanto:

• Copiar el esqueleto: Primero los activos, primero lo estático y luego lo dinámico, elegir el modo por toma, escribir solo los cambios en el prompt, probar en baja resolución, inspeccionar toma por toma.
• Cambiar solo una cosa: La respuesta estándar no es la imagen de IA, sino los hechos del producto + 3D (o fotos reales del producto / planos CAD).

También hay una experiencia: Los píxeles renderizados en 3D no deben ir directamente al video final, sin importar cuán detallados sean, siempre se verán CG. Deja que el modelo de imagen vuelva a dibujar sobre la base del render 3D, y luego usa esa imagen como el primer y último fotograma del video; así se logra el realismo.

Primer paso: Inicio del proyecto, primero aclara estas 8 preguntas

Los detalles y cómo preguntar al usuario se encuentran en references/01-intake.md.

1. Estimación de tiempo: En la primera respuesta, indica aproximadamente cuántos minutos o días, y a qué hora estará listo, listado por fases, incluyendo los pasos que el usuario debe hacer personalmente; actualiza inmediatamente si hay retrasos.
2. Tipo de video y plataforma de publicación: Video explicativo, anuncio de marca, video corto vertical, video de comercio electrónico o video corto para lanzamiento, dónde se reproducirá, duración y formato. Elige la estrategia según references/02-formats.md; se pueden producir múltiples versiones de entrega en una sola producción.
3. La audiencia es interna o pública: Los videos internos y para inversionistas pueden mostrar vistas explosionadas, vistas en corte y estructura interna; los videos para publicación pública no deben mostrar ninguna estructura interna, ni nombres de componentes. Esto determina qué tomas se pueden filmar.
4. Formulario de confirmación de hechos del producto (templates/product_facts.md): De qué componente depende cada función, de dónde sale, cómo se ve en la toma, cómo no debe verse, si es un objetivo de diseño o ya está implementado, y si se puede hacer público. Todas las inferencias deben marcarse como "pendiente de confirmación" hasta que el responsable las confirme.
5. Punto de referencia de calidad: Pide al usuario un video de referencia, mide su nivel de movimiento y método de producción; aprende solo la calidad, no la estructura.
6. Herramientas que tiene el usuario:
   • Modelo de imagen: ¿Solo tiene suscripción, requiere que el usuario dibuje manualmente, o tiene una API que se puede llamar mediante script?
   • Modelo de video: ¿Cuenta con API (llamable por script) o es miembro de página web o aplicación (solo se puede generar manualmente: usa paquetes de video manuales, primero verifica los términos comerciales, no asumas que se puede actualizar desde borrador)?
   • ¿Tiene un modelo 3D del producto o CAD? Si no, ¿tiene una muestra física o alguna imagen renderizada? Si no hay 3D, sigue la "ruta sin 3D" (references/03-previs.md sección 10).
7. Presupuesto y facturación: Fórmula de precios, paquetes y cuánto descuentan realmente los cupones, saldo de la cuenta, límite total. Antes de la generación masiva y la actualización a alta definición, el usuario debe verificar primero el saldo.
8. Prueba pequeña para decidir la ruta: Genera dos borradores de baja resolución para la misma toma, uno usando la imagen 3D o del producto como primer fotograma, y otro usando un fotograma clave realista dibujado por el modelo de imagen como primer fotograma. Con unos pocos dólares y unos minutos se puede ver la diferencia.

Convención de carpetas del proyecto

Todos los scripts usan la carpeta especificada con --project como raíz (por defecto es el directorio actual). Para proyectos nuevos, sigue esta estructura:

<project>/
  .env                    Claves (ARK_API_KEY, etc.), no entran al repositorio, no aparecen en el chat
  brief/                  creative_brief.md, product_facts.md, benchmark.md, budget.md, decisions.md, feedback_brief.md, claims.md, licenses.md
  shots/shot_list.json    Lista de tomas, única fuente de la línea de tiempo
  shots/prompts/<id>.txt  Prompts de video para cada toma (agrega número de versión al modificar, conserva versión anterior)
  plates/<id>/            Base 3D, máscaras, coordenadas de cámara (sin 3D, coloca imágenes de referencia del producto)
  packs/                  look_bible.txt (configuración unificada, única fuente), paquetes de generación manual de imágenes, paquetes de video manual
  keyframes/keyframes.json  Lista de fotogramas clave (maestros, primero y último, orden de subida)
  keyframes/raw/          Imágenes originales del modelo de imagen
  keyframes/norm/         Fotogramas clave normalizados al tamaño de salida
  footage/                Material grabado, capturas de pantalla, capturas de interfaz real, etc. (opcional)
  gen/                    Salidas del modelo de video, y video_log.jsonl (registro de llamadas y gastos)
  qc/                     Mosaico de fotogramas, informes Gate K / Gate V
  edit/                   edl.json, captions.json, callouts.json, approved_drafts.json, approved_bridges.json
  renders/                Video sin audio de la salida del editor y .timeline.json (ubicación de salida predeterminada de edit.py)
  sound/                  Pistas de música y efectos de sonido, hoja de referencia, ventana de mezcla
  deliver/                Videos finales (versión pública y versión interna separadas)
  work/                   Scripts y flujos de trabajo propios del proyecto (generar EDL, paquetes de imágenes, comprobaciones), cada paso escribe en disco

Copia las plantillas de templates/ en las carpetas correspondientes: creative_brief.md, product_facts.md, benchmark.md, budget.md, feedback_brief.md, claims.md, licenses.md van a brief/, decision_list.md se guarda como brief/decisions.md; shot_list.json va a shots/; keyframes.example.json se guarda como keyframes/keyframes.json; el bloque de código de prompts/look_bible.md completado se guarda como packs/look_bible.txt; sfx_cue_sheet.md va a sound/; los cinco archivos *.example.json (edl, captions, callouts, approved_drafts, approved_bridges) se renombran quitando .example y se colocan en edit/.

El formato de video se escribe en los datos, no se memoriza en comandos:

• Generación de video: El formato de las tareas de primer y último fotograma sigue el formato del primer fotograma (primero normaliza los fotogramas clave con scripts/qc/normalise_keyframes.py --size 1080x1920); para el modo de referencia vertical, agrega --aspect 9:16.
• Edición: edit/edl.json escribe "size": [1080, 1920], luego uv run scripts/edl_editor/edit.py --project <project> --edl edit/edl.json --dry organiza en vertical; --res 480 genera una vista previa pequeña del mismo formato, --size WxH genera otro formato.
• Feed vertical: El style de edit/captions.json escribe "preset": "feed_safe", los subtítulos y el texto pequeño al final entran en el área segura conservadora; --dry verifica uno por uno.

El primer día, haz git init y agrega .env, gen/, renders/, .cache/ a .gitignore. Cada tipo de datos reconoce solo un archivo como fuente:

• Apariencia del producto: Archivo de especificaciones o modelo 3D maestro; configuración unificada: packs/look_bible.txt;
• Línea de tiempo: shots/shot_list.json;
• Subtítulos: edit/captions.json;
• Edición: edit/edl.json;
• Tomas aprobadas: edit/approved_drafts.json, edit/approved_bridges.json;
• Afirmaciones y licencias: brief/claims.md, brief/licenses.md;
• Comentarios del usuario: brief/feedback_brief.md.

Pipeline

Dos líneas paralelas: Línea de imagen y Línea de sonido. El sonido no debe esperar a que la imagen se actualice a HD; una vez que la estructura de edición esté definida, comienza.

#	Fase	Producto	Revisión del usuario	Verificación automática / Registro	Detalles
1	Inicio y hechos	Brief creativo, formulario de confirmación de hechos del producto, lista de entrega	Confirmar hechos, tipo de video, presupuesto	—	01, 02
2	Creatividad y lista de tomas	Estructura, ritmo, lista de tomas (cada toma: posición de cámara, acción, efecto, estado del producto, modo, transición, subtítulos, efectos de sonido)	Definir estructura y dirección del texto	Si la duración y el tiempo de lectura caben	02, rulebook §1
3	Previsualización y base	Modelo 3D maestro, contrato de base para cada fotograma clave, video en gris si es necesario; sin 3D, usar imágenes de referencia del producto	Ver la vista general de la base	Verificar orientación, cables, intersecciones desde cada posición de cámara real	03
4	Configuración maestra	Modelo maestro del producto, modelo maestro de escena, diseño de personajes (primero los activos, antes de todos los fotogramas clave de las tomas)	Revisar punto por punto	—	04 §2, §3
5	Fotogramas clave	Un paquete de imágenes por fotograma, o llamada a API mediante script; tamaño unificado	Dibujar manualmente o revisar imágenes	Gate K (script del proyecto): contorno, proporción, estado del efecto, consistencia de escala, archivos duplicados	04
6	Borrador de video	Borrador 480p	El usuario mismo activa y paga; ver saldo antes de lote; ver borrador	Ensayo y condiciones de rechazo (incluyendo verificación de prompts); mosaico cada 0.25 segundos; Gate V (script del proyecto)	05
7	Revisión y registro	edit/approved_drafts.json, edit/approved_bridges.json, corte inicial	Dar comentarios, numerados y escritos en el brief	La liberación manual vincula la huella digital del archivo	05 §13
8	Edición y subtítulos	Vista previa EDL: transiciones, tomas de transición AI, subtítulos, anotaciones, tarjetas de inicio y fin	Modificar redacción y orden	--dry verifica intervalos y tiempo de lectura; revisión de fotogramas estáticos de subtítulos	06
9	Actualización a HD	Las tomas aprobadas se actualizan a 1080p tal como están	Liberar después de que el orden y los subtítulos estén finalizados; primero ver saldo	Consistencia de duración y fotogramas intermedios	05 §6
S1	Diseño de sonido (paralelo a 8, 9)	Selección de música y licencias, hoja de referencia de efectos de sonido, sonido propio del producto, narración si es necesario	Seleccionar música (enviar archivos reproducibles), escuchar transiciones	Registro de licencias	07
S2	Mezcla	Pista de audio equilibrada del video final	Escuchar el video final	Medir dB de "efectos de sonido menos música" por ventana de tiempo; objetivo de sonoridad	07
10	Entrega	Video maestro, versión para compartir (menos de 30 MB), formatos para cada plataforma, versiones cortas de 15/6 segundos	Definir texto de inicio, pedir video final	Duración, flujos de audio y video, sonoridad, imagen del fotograma clave	08
11	Multilingüe	Un archivo de texto genera subtítulos y EDL paralelos	Definir texto	El video original no cambia píxel a píxel; los caracteres residuales del idioma original son 0	08
12	Cumplimiento final	brief/claims.md, brief/licenses.md, etiquetas de IA	Firmar	Verificación de lista de palabras + verificación frase por frase contra los hechos del producto	09

Las 12 reglas más importantes

Las 139 reglas completas se encuentran en references/rulebook.md.

1. Primero escribe la hoja de inicio: Tipo de video, audiencia (interna o pública), plataforma, duración, formato, luego habla de creatividad.
2. Los hechos del producto se escriben y confirman primero; una corrección se aplica a todos los pasos posteriores (3D, base, prompts de imagen, prompts de video, subtítulos, anotaciones, brief), luego busca globalmente palabras residuales.
3. El 3D solo define la posición, los píxeles finales los dibuja la IA; para cada toma, pregúntate "¿De dónde vienen los píxeles finales?".
4. Los fotogramas clave de IA deben usarse como primer y último fotograma para impulsar la toma, no solo como una imagen más en un conjunto de referencia.
5. Cada píxel que se le da al modelo de video se copiará tal cual: El modelo en gris debe ser uniformemente gris y sin ruido; no coloques imágenes con posiciones de cámara diferentes en el paquete de referencia; la imagen de referencia en sí debe ser correcta.
6. Los prompts de video se escriben como un guión segundo a segundo, los números se derivan del 3D o de la lista de tomas, no se escriben a mano; solo escribe los cambios, no repitas la descripción de la apariencia.
7. Los efectos se escriben como los capturaría la cámara, y se especifica "qué no es"; las luces constantes escriben "brillo constante"; las cantidades se miden con estándares verificables a simple vista.
8. El gasto se divide en dos niveles: Primero pasa la verificación gratuita, genera borrador 480p; solo después de la aprobación se actualiza a HD, y primero se verifica el saldo.
9. Revisa el video original fotograma a fotograma: El modo de primer y último fotograma puede hacer transiciones suaves en el medio; la revisión independiente debe ver el video original generado.
10. Los subtítulos, las anotaciones y el audio están en la capa de edición, generados por los datos de la línea de tiempo; cambiar texto, reordenar o actualizar a HD no requiere regenerar las imágenes.
11. Dos controles de cumplimiento: Primero pasa la lista de palabras (palabras prohibidas, eficacia, médicas, números), luego verifica frase por frase contra los hechos del producto buscando "funciones implícitas". La práctica predeterminada para la etiqueta de IA es marcarla una vez al inicio del video (al menos unos 2 segundos), explicarla en texto pequeño al final, más la declaración de IA de la plataforma; no se coloca una marca de agua permanente a menos que la plataforma lo requiera.
12. Cada comentario del usuario se numera y se escribe en el brief, y todos los agentes y la revisión final lo verifican. Las conversaciones largas se comprimen, los archivos no.

Colaboración con el usuario

• Tiempo: Primero da una estimación; para tareas largas sin salida visible, informa activamente la fase actual, la hora de la última actividad y la nueva hora estimada.
• Cuando sea el turno del usuario, entrega todo de una vez: Archivos de instrucciones completos, materiales que se puedan abrir o reproducir directamente, enviados al teléfono (cada archivo de menos de 30 MB). Informa al usuario en qué carpeta colocar el modelo maestro.
• Escucha la forma de trabajo: "Solo analiza" significa solo analizar; "no te detengas a mitad" significa llegar hasta la entrega; "última ronda" significa saltar las escuchas intermedias.
• Conclusión primero: Si el usuario pregunta "¿Hay que empezar de nuevo?", la primera oración da la conclusión, luego explica las razones, y finalmente enumera los puntos que el usuario debe decidir.
• Seguridad:
  • No leer, mostrar ni solicitar claves (solo poner en .env);
  • No registrar cuentas, ingresar contraseñas o información de pago;
  • Para aceptar acuerdos, pagar, activar, recargar, detenerse antes del botón, explicar el costo, y dejar que el usuario haga clic;
  • Preguntar antes de descargar archivos.
• Tareas largas:
  • Antes de comenzar, pide al usuario que conecte la alimentación, configure el modo de suspensión del sistema en "nunca" y solicite mantener el sistema activo;
  • Los flujos de trabajo y los lotes deben poder reanudarse desde el disco;
  • Enviar y consultar resultados en dos pasos;
  • El renderizado 3D solo abre un proceso a la vez.

Detalles en references/10-working-with-user.md.

Publicación externa

Para todo el contenido público, incluyendo anuncios, redes sociales, imágenes de presentaciones públicas:

• No colocar vistas explosionadas, vistas en corte, tomas que muestren la estructura interna, ni escribir nombres de componentes internos o principios de funcionamiento;
• En publicaciones de redes sociales, no mencionar productos de IA específicos (escribe "modelo de imagen grande", "modelo de video", "software 3D");
• No mostrar gastos;
• Los problemas se escriben como problemas generales del flujo de trabajo, no como experiencias personales;
• Agregar la declaración de generación por IA requerida por la plataforma.

Ver detalles en references/09-compliance.md.

Herramientas

Todos los scripts se ejecutan con uv run, las dependencias están en el bloque PEP 723 al inicio de cada script, ffmpeg proviene de imageio-ffmpeg.

Script	Propósito
scripts/edl_editor/edit.py	Genera video según EDL: tarjetas, transiciones suaves, pantalla negra, destellos, movimiento de cámara, tomas de transición AI, subtítulos, anotaciones, marca de agua; soporta 16:9, 9:16, 1:1; --dry para ensayo, genera timeline.json. Con make_demo.py se puede generar un proyecto de demostración con un solo clic
scripts/edl_editor/typeset.py	Motor de composición de subtítulos y tarjetas: jerarquía de chino e inglés, ajuste de puntuación, zona segura, fallback de fuentes entre plataformas; --specimen puede verificar las fuentes del sistema
scripts/video_api/seedance.py	Cliente Seedance de Volcano Engine: modos de primer y último fotograma, imagen de referencia, etc., borrador y actualización a HD, consulta reanudable, estimación de costos y registro, --dry sin conexión, solo verifica (incluyendo verificación de prompts); también se puede usar como referencia para escribir adaptadores para otros modelos de video
scripts/audio/mix.py	Pistas de música y efectos de sonido equilibradas por ventana de tiempo, mide la diferencia de dB, limitador y normalización de sonoridad en dos pasos, luego mezcla con el video
scripts/qc/strip.py	Extrae un fotograma cada 0.25 segundos y los une en una imagen larga, dibuja curvas de movimiento y brillo, marca cortes bruscos, saltos y congelados
scripts/qc/contact_sheet.py	Cuadrícula de imágenes etiquetadas para revisar bases, fotogramas clave y borradores
scripts/qc/normalise_keyframes.py	raw de fotogramas clave → norm: recorta el fotograma de la toma al formato de salida, los modelos maestros y las imágenes de referencia solo se reducen, no se recortan; la ampliación y el recorte forzado generan una advertencia
scripts/qc/lint_prompts.py	Escaneo de palabras prohibidas en prompts de video (incluyendo palabras prohibidas de mecanismos de este producto); si no se encuentra ningún archivo, reporta error

Scripts no incluidos, que el proyecto debe escribir en work/: Juicio de Gate K y Gate V (seedance.py no lee informes Gate K, "sin informe no se envía" lo garantiza el paso de envío del proyecto), generación de paquetes de imágenes (keyframes.json → packs/), shot_list.json → EDL y borrador de subtítulos. Los requisitos están en 04, 05, 06 y templates/prompts/keyframe_pack.md.

Las instrucciones de uso se encuentran en el archivo README de cada directorio. Las capacidades, precios y limitaciones de los modelos cambian rápidamente; antes de usarlos, verifica la documentación oficial; las "notas del modelo" al final de cada archivo de referencia indican la fecha de verificación.

Cuándo leer qué archivo

Archivo	Cuándo leerlo
references/01-intake.md	El primer día de un nuevo proyecto
references/02-formats.md	Al definir el tipo de video, duración, formato, estructura, o al hacer anuncios y videos cortos verticales
references/03-previs.md	Antes de crear la previsualización 3D o la base; cuando no hay modelo 3D
references/04-keyframes.md	Al escribir paquetes de imágenes, definir la configuración unificada, verificar fotogramas clave
references/05-video-gen.md	Al escribir prompts de video, seleccionar modo de generación, enviar, revisar borradores, actualizar a HD
references/06-edit-type.md	Edición, transiciones, subtítulos, anotaciones, tarjetas de inicio y fin
references/07-sound.md	Selección de música, efectos de sonido, narración, mezcla
references/08-delivery.md	Entrega, versiones para cada plataforma, versiones cortas, multilingüe
references/09-compliance.md	Antes de escribir cualquier texto en pantalla o narración; antes de la publicación pública
references/10-working-with-user.md	Colaborar con usuarios que no escriben código, tareas largas, límites de seguridad, problemas de entorno
references/rulebook.md	Cuando no estés seguro en una fase, consulta el grupo correspondiente
references/pitfalls.md	Cuando surja un problema, primero verifica según el síntoma
templates/	Al comenzar, copia al proyecto, completa y usa
examples/case-study.md	Si quieres ver cómo se desarrolló un proyecto completo