Producción de Documentales con IA

Primer uso: Primero, configura el entorno

Imágenes: Por defecto, el usuario genera las imágenes con GPT; la IA no llama a la API de imágenes; image_mode=agent requiere aprobación explícita.
Entorno: Python 3.10+, ffmpeg, ffprobe; contact_sheet.py además necesita Pillow; sin dependencia de PyYAML.
H3: Si no has configurado MiniMax H3, primero consulta references/00_setup.md:
- Registro/verificación de identidad/recarga en la plataforma abierta;
- Crear una clave API;
- Variable de entorno MINIMAX_API_KEY o archivo de clave;
- base_url / nombre del modelo / alineación de resolución;
- Primero ejecuta una prueba de 4 segundos, luego procesa en lote.
La clave no va en el código, ni en los registros, ni en git.
Si H3 no está disponible, cambia de proveedor o primero haz un animatic; no finjas que puedes generar.
Sin configurar H3, no entres en G5.

Cuándo usar

El usuario quiere hacer un cortometraje人物/temático, cuya duración la determina el brief;
30 segundos, 1 minuto, 3 minutos son solo ejemplos, no rangos fijos;
Hay personas reales, materiales históricos, recreaciones con IA;
Se necesita ir desde cero hasta un producto final entregable;
Se necesita controlar costos, conservar fuentes y escribir créditos.

No aplica

Retratos grupales de múltiples personas, largometrajes de tipo entrevista;
Anuncios comerciales, vídeos puramente de producto;
Animación pura, producción virtual pura;
Documentales de campo que requieran filmación real.

La duración no tiene un límite estricto; los proyectos muy largos necesitan gestión adicional de materiales, pero el flujo no cambia.

Preguntas obligatorias antes de empezar

Duración del producto final, relación de aspecto, fotogramas por segundo, idioma, plataforma;
Quién es el personaje, de qué parte se habla, qué hechos no pueden fallar;
Límite de presupuesto, si se permiten reintentos;
Quién genera las imágenes (image_mode=human/agent), qué modelo para el video, qué software para la edición;
La narración es de una persona real o TTS; la música es una pista separada;
Si hay fotos históricas/música con derechos de autor; si se necesita una declaración de IA;
Formato de entrega y fecha límite;
perfil: short (aproximadamente 15–60s) / standard (aproximadamente 2–5min) / custom (según necesidad);
model_routing: hybrid / gpt_only / codex_deepseek;
Si H3 ya está configurado (clave/base_url/modelo/límite); si no, primero enseña a configurarlo;
Tarjeta de apertura: none / static; cuántos segundos; si cuenta en la duración objetivo; el texto del título se decide en G2.5.

Sin brief, no se pasa a la investigación.

Duración y perfil

La duración la determina duration_target_sec en project.yaml, no está fija.

perfil	duración ejemplo	número de tomas (ejemplo)	párrafos (ejemplo)	música (ejemplo)
short	15–60s	8–18	1–2	1 segmento
standard	2–5min	24–60	3–5	3–5 segmentos
custom	usuario define	usuario define	usuario define	usuario define

Estos son estimaciones, no requisitos estrictos; 30 segundos y 3 minutos son solo dos ejemplos comunes.

Entrega de imágenes en G4

Después de completar los prompts, primero recuerda al usuario que genere las imágenes, luego haz el trabajo paralelo:

Envía image_batch_request.md: número de toma, nombre de archivo, ubicación del prompt, cantidad, prioridad; si la tarjeta de apertura está habilitada, 0-1_card.png va en el primer lote;
Di claramente: "Ahora puedes empezar a generar las imágenes";
Después de que el usuario comience, el agente hace el trabajo que no depende de imágenes/video: subtítulos, hoja de referencia, tabla de costos, fuentes/créditos, esqueleto de edición, QA del siguiente lote de prompts;
No revises las imágenes, no generes video, no hagas la composición final;
Cuando el usuario devuelva las imágenes, primero revísalas; no vuelvas a discutir la narración/las tomas ya bloqueadas;
La tarjeta de apertura es una tarjeta estática, no se hace con H3; verifica el texto carácter por carácter; si el chino es inestable, cambia a superposición de texto en la edición.

No hagas otras cosas en silencio que hagan esperar al usuario; la tarea de generar imágenes debe entregarse primero. Consulta references/13_parallel_work.md para más detalles.

Enrutamiento de modelos

Por defecto hybrid:

Fase	Modelo	Qué hacer
G0–G3	Codex + DeepSeek	brief, investigación, narración, storyboard, prompts
G4	GPT	Generar/revisar imágenes; `image_mode` decide quién genera
G5–G8	Codex + DeepSeek	Tareas, costos, archivos de edición, QC; cambia a GPT temporalmente al ver imágenes

Para texto y archivos usa DeepSeek, para píxeles y visión usa GPT;
image_mode=human: el usuario genera las imágenes con GPT; image_mode=agent: Codex + herramientas de imagen generan las imágenes (requiere aprobación explícita);
Antes de cambiar, escribe image_handoff.md; el archivo del proyecto es el comprobante de entrega;
Consulta references/10_model_routing.md para más detalles.

Las 9 fases y los controles de acceso G0–G8

Fase	Producto	Control de acceso
G0 Brief	`project_brief.md`	Duración, presupuesto, derechos, plataforma bloqueados
Investigación/Verificación de hechos	`fact_check.csv`, `research.md`	G1 Hechos bloqueados
Guion/Narración	`script.md`, `vo.csv`, `vo_text_review.md`, `voice_audition.md`, `vo_lock.md`, `vo_review.md`	G2 Narración bloqueada (texto + tono de voz + versión)
Storyboard/Línea de tiempo	`beats.csv`, `shots.csv`, `segments.csv`, `timeline.csv`, `animatic.mp4`, `v0_review.md`	G3 Ritmo reclamado + tabla de tomas + confirmación v0
Primer fotograma (según image_mode)	`首帧/`, `image_review.md`, `image_handoff.md`, `image_batch_request.md`	G4 Primer fotograma bloqueado
Generación de video	`h3_package/`, `clips/`, `tasks.json`, `cost.csv`	G5 Video bloqueado
Corte初步/Subtítulos	`cut/`, `subtitles.srt`	G6 Imagen bloqueada
Música/Efectos de sonido	`music/`, `cue_sheet.csv`	G7 Sonido bloqueado
Control de calidad final/Entrega	`final.mp4`, `final_qc.md`, `credits.md`	G8 Entrega

Regla: Si la fase anterior no está completada, no se pasa a la siguiente; no se gasta dinero.

Tarjeta de apertura

Solo se pregunta en G0 "si se quiere, cuántos segundos, si cuenta en la duración objetivo"; el texto del título se decide en G2.5.

G0: opening_card: none|static; opening_seconds; opening_in_target;
G2.5: Título principal/subtítulo/estilo de fuente; opening_card.md confirmación carácter por carácter;
G3: Se escribe como toma estática 0-1 en shots.csv (static=yes, sin narración); en segments.csv se escribe una línea CARD (static=yes);
G4: Va en el primer lote de generación de imágenes, nombre de archivo 首帧/0-1_card.png; cuando el texto y la imagen se generan juntos, verifica carácter por carácter;
G5: No se hace con H3; export_h3.py omite static=yes; la tabla de tareas H3 no lo incluye;
G6: En la edición, se mantiene estático; se puede hacer un lento zoom de 1–2%;
La duración de la tarjeta de apertura se descuenta de la duración objetivo, o se añade explícitamente a la duración total; se decide en G0.

La tarjeta de apertura es "una decisión de duración al inicio del proyecto", no "una opción decorativa al generar imágenes".

Orden de revisión de la narración

Revisión del texto: Muestra todo el texto de vo.csv, códigos de tiempo, notas de hechos al usuario; después de que el usuario confirme, haz la voz;
Audición del tono de voz: Genera 2–3 candidatos para la misma frase; el usuario elige A/B/C o graba él mismo;
Scratch completo: Genera la narración completa con el tono de voz seleccionado;
v0 animatic: Solo entonces haz fotogramas fijos + narración;
Si algún paso no se confirma, no se pasa al siguiente.

La narración primero

Este es el orden central de esta habilidad:

Primero define la narración, luego define las tomas, el primer fotograma, el video;
Una frase de narración combinada con 2–3 planos es la norma;
Un plano por frase es un caso especial (reacción breve, eslogan, montaje de un solo plano), no es el valor por defecto;
La narración es independiente en vo.csv, no la fragmentes por tomas;
No generes TTS por tomas; genera por frases/párrafos, coloca el segmento completo en una pista de audio;
Cada frase contiene una información; cada 1–2 frases al menos una información sólida (año/nombre/número/acción/causa-efecto);
Las imágenes poéticas deben tener un ancla concreta, una cadena, que pueda aterrizar; "puerta/semilla" puede ser un motivo, no un error automático; el eslogan sin ancla es una palabra vacía; primero explica la causa y el efecto, luego habla de poesía;
Después de escribir, primero ejecuta narration_lint.py, luego léelo una vez más para fijar la versión;
Al editar, usa J-cut/L-cut: el plano cambia, la narración continúa;
Entre frase y frase, deja un espacio de 0.3–1.0 segundos; una narración de 5 segundos no debe pegarse a un plano de 5 segundos; es mejor que el espacio lo ocupe un plano corto sin narración, no que se meta dentro de un plano con narración;
El espacio solo se coloca entre frases de narración; el punto de corte debe caer dentro del espacio, no dentro de una frase con narración;
Después de bloquear la narración, no modifiques directamente la versión antigua; primero ejecuta vo_diff.py, solo modifica los archivos afectados;
Un párrafo de narración puede abarcar múltiples tomas; una toma normal tiene como máximo un párrafo de narración; una toma larga con long_take=yes puede contener múltiples párrafos de narración, pero cada párrafo debe estar completo dentro de la toma;
La ventana de espacio entre narraciones adyacentes debe contener al menos un punto de corte de toma; el inicio y el final de una frase pueden caer dentro de una toma, no es necesario que coincidan con el punto de corte; cuando hay un intervalo, el espacio se toma como el mayor;
Después de ordenar shots.csv / timeline.csv, primero genera un v0 animatic (fotograma fijo fotograma negro + narración), recuerda claramente al usuario que escuche los espacios entre frases; después de la confirmación, entonces genera el primer fotograma/video;
Primero muestra el texto, luego define el tono de voz, luego haz el v0: sin la confirmación del usuario sobre el texto y el tono de voz, no generes TTS/animatic.

Primero la narración, luego las imágenes; no es que primero tengas 40 tomas y luego metas una frase en cada una.

Contrato de archivos

`shots.csv`

id,story_segment,scene_id,duration,shot_size,camera,scene,action,expression,vo_ids,anchor,first_frame,video,status,cost,notes,long_take,static

story_segment es el número del segmento narrativo, no el segmento de generación H3; el segmento de generación está en generation_id de segments.csv;
scene_id es el número de escena, debe coincidir con segments.csv;
duration en segundos, admite decimales;
status solo usa todo/image_ready/video_running/video_ok/conditional/retake/final;
vo_ids puede estar vacío; una toma normal tiene como máximo un vo_id; una toma larga con long_take=yes puede escribir V01|V02;
long_take=yes: una toma larga continua, permite 2 o más párrafos de narración, pero cada párrafo debe estar completo dentro de la toma;
static=yes: tarjeta de apertura/inserción estática, no se hace con H3; debe tener first_frame; segments.csv usa el segmento static=yes;
Esta es la fuente de verdad de la imagen; la narración está en vo.csv, ambas se relacionan mediante vo_ids.

`vo.csv`

vo_id,start,end,text,shot_ids,notes
V01,0.0,4.2,"Frase de narración completa","1-1|1-2","4.2s; espacio de 0.8s después de la frase"
V02,5.0,6.2,"Siguiente frase","1-3","1.2s; espacio de 0.8s al final"

start/end son en segundos absolutos;
Una frase de narración puede abarcar 2–3 tomas;
Una toma por frase solo se usa en casos especiales;
Entre frase y frase, deja un espacio de 0.3–1.0 segundos;
Un shot_id solo puede pertenecer a un cue; un cue puede cubrir múltiples shots;
Los subtítulos se generan desde vo.csv, no están vinculados a las tomas.

`beats.csv`

beat_id,story_segment,kind,shot_id,vo_id,text,notes
B01,1,action,1-1,V01,Resolviendo problemas detrás del mostrador,
B02,1,action,2-1,V02,Mete el artículo en un sobre,

Un beat es la unidad más pequeña de la historia, no un compás musical;
Cada beat es exactamente reclamado por un shot_id;
Cada toma no estática tiene al menos un beat; las tarjetas de apertura static=yes pueden no tener beat; cada párrafo de narración tiene al menos un beat;
Una narración puede abarcar múltiples beats, repitiendo el mismo vo_id en cada línea;
El orden de los beats debe ser consistente con el orden de las tomas; los beats faltantes, duplicados o desordenados son interceptados por validate.py.

`segments.csv`

generation_id,scene_id,cut_order,shot_id,start,end,duration,keyframe,static,notes
S01,1,1,1-1,0,5,5,首帧/1-1_first.png,no,Corte único
S02,1,1,1-2,5,9,4,首帧/1-2_first.png,no,Corte 1 dentro del segmento
S02,1,2,1-3,9,15,6,首帧/1-3_first.png,no,Corte 2 dentro del segmento

generation_id = una generación H3; un segmento ≤15 segundos, no cruza escenas;
scene_id debe ser igual al scene_id de la misma toma en shots.csv; cambiar de escena debe cambiar de segmento;
cut_order = el número de corte dentro del segmento, comenzando desde 1 consecutivamente;
keyframe = la imagen de anclaje de la composición de este corte; el primer corte se fija en 0.00 segundos, los siguientes en el punto de corte;
static=yes = tarjeta estática, no va a H3; debe ser un solo corte; export_h3.py lo omitirá;
Cada shot solo puede aparecer en una generación;
Los start/end/duration de cada corte deben ser iguales a los acumulados de shots.csv; todo el video debe ser sin espacios ni superposiciones;
validate.py intercepta desbordamientos, desalineaciones, espacios y duplicados.

`h3_prompts.csv`

shot_id,prompt,soundscape,notes
1-1,"Mantener el primer fotograma; la punta del bolígrafo se mueve lentamente, la llama de la lámpara oscila ligeramente.","Sonido de papel y bolígrafo, sonido del viento a lo lejos.",

export_h3.py agrupa según segments.csv, y concatena los prompts de cada corte en un prompt de alineación de múltiples imágenes;
Genera h3_package/<generation_id>/prompt.md + manifest.json;
No llama a la API; la generación aún la ejecuta la tabla de tareas H3.

Versiones de narración

vo_versions/vo_v1.csv
vo_v1_scratch.wav
vo_lock.md

Antes de bloquear, primero prueba la lectura/TTS, mide la duración real;
Después de bloquear, solo añade nuevas versiones, no modifiques directamente la versión antigua;
Para cambiar la narración, primero ejecuta vo_diff.py, luego modifica según el alcance de la afectación;
Consulta references/12_change_control.md para más detalles.

`project.json`

Configuración de máquina generada por init_project.py: profile/model_routing/image_mode/duration_target_sec/shot_target/fps/resolution/providers. project.yaml es la versión legible por humanos; los scripts leen project.json.

`tasks.json`

[{"generation_id":"S01","provider":"minimax_h3","model":"MiniMax-H3","resolution":"768P","duration":9,"status":"todo","prompt":"h3_package/S01/prompt.md","first_frames":["首帧_h3/1-1_first.png"],"cost_cny":0.0}]

generation_id corresponde al segmento de generación en segments.csv;
duration debe ser un entero entre 4 y 15;
prompt / first_frames son las rutas del paquete de producción;
Las tareas fallidas no se facturan; los reintentos se listan por separado;
Las antiguas tareas por toma pueden usar id, pero h3_tasks.json siempre usa generation_id.

Paquete de entrega

final.mp4
subtitles.srt
vo.wav
vo.csv
music/A-E.wav + cue_sheet.csv
credits.md
source_list.csv
fact_check.csv
final_qc.md

Reglas estrictas

Por defecto, el usuario genera las imágenes con GPT; la IA no llama a la API de imágenes; solo cuando image_mode=agent y el usuario lo aprueba explícitamente se permiten herramientas de imagen;
Por defecto, el video se genera en una sola versión; solo si no funciona se hace una versión adicional;
El video generado solo permite sonido ambiente/voz humana, no permite música de fondo/BGM;
El material de origen 768P puede ser 1344×768 (7:4), el producto final se entrega en 1920×1080;
El primer fotograma debe ser 16:9, de lo contrario la relación de aspecto del video de imagen a video se desviará;
Las fotos históricas indican la fuente; las imágenes de IA indican "recreación";
Subtítulos: 16–20 caracteres/línea, máximo 2 líneas, márgenes izquierdo y derecho ≥100px;
Cada segmento de música deja un handle de 1.5–2 segundos; los valles no son silencio;
Los costos se calculan según el registro de tareas, no de memoria;
Antes de la entrega, usa ffprobe para verificar resolución/fotogramas por segundo/audio;
Primero define la narración, luego las tomas; por defecto, una frase de narración abarca 2–3 tomas; una toma por frase es un caso especial;
La narración no debe llenar el plano; una narración de 5 segundos con un plano de 5 segundos se siente apresurada; deja un espacio de 0.3–1.0 segundos entre frases;
La narración puede ser poética, pero la poesía debe tener un ancla de objeto/acción; la sección explicativa solo requiere una información sólida por frase; no mezcles dos estándares;
Después de bloquear la narración, está prohibido reescribir todo el proyecto por cambiar una frase; primero ejecuta vo_diff.py, luego solo modifica los archivos afectados;
Después de completar los prompts en G4, primero recuerda al usuario que genere las imágenes; después de que el usuario comience a generar, entonces haz el trabajo paralelo que no depende de imágenes/video;
Un párrafo de narración puede abarcar múltiples tomas; una toma normal tiene como máximo un párrafo de narración; una toma larga con long_take=yes puede contener múltiples párrafos de narración, pero todos deben estar dentro de la toma;
La ventana de espacio debe contener el punto de corte de la toma; no exijas que el inicio y el final de la frase se ajusten al punto de corte; cuando hay un intervalo en el espacio, toma el mayor;
Después de generar el v0 animatic, primero recuerda al usuario que verifique los espacios entre frases; antes de la confirmación, no generes el primer fotograma ni el video;
El tono de voz debe ser seleccionado por el usuario después de escuchar 2–3 candidatos; no se puede usar un TTS por defecto;
La narración por defecto es "clara pero no directa": primero explica la persona/evento/causa-efecto, luego usa imágenes concretas y frases cortas para dejar espacio; se permite añadir 1–2 frases, pero cada frase debe tener nueva información o una nueva imagen, no uses adjetivos para alargar la duración;
Cada beat en beats.csv debe ser reclamado exactamente por una toma; cada toma y cada párrafo de narración deben tener cobertura de beat; los beats faltantes/duplicados/desordenados son interceptados por validate.py;
Un segmento en segments.csv ≤15 segundos; el orden de los cortes dentro del segmento es consecutivo, cada corte tiene un keyframe, cada shot aparece solo una vez; el inicio y el final de cada corte deben ser iguales al tiempo acumulado en shots.csv; para la alineación de múltiples imágenes de H3, usa export_h3.py para generar el paquete de producción;
Tarjeta de apertura: G0 define la duración, G2.5 define el texto, G3 escribe 0-1 static=yes, G4 genera la imagen, G5 no se hace con H3.

Proveedor

config/providers.yaml es la documentación; la configuración de la máquina es providers.json (generado por init_project.py, timeline.py lo verificará).

Por defecto: imágenes=user_gpt, video=minimax_h3, narración=capcut_tts, música=local_midi_fluidsynth, edición=capcut, control de calidad=ffmpeg.

El proveedor de imágenes siempre es human; esta regla no cambia con la configuración.

Comandos

python scripts/init_project.py --root my-film --profile short --duration 30 --shots 10 --segments 2
python scripts/timeline.py --shots shots.csv --vo vo.csv --vo-out vo_report.csv --project project.json --min-gap 0.4
python scripts/timeline.py --shots shots.csv --vo vo.csv --max-density 0.85 --allow-single
python scripts/narration_lint.py --text vo.csv --style lyrical --max-chars 28
python scripts/validate.py --shots shots.csv --vo vo.csv --beats beats.csv --segments segments.csv --project project.json
python scripts/validate.py --shots shots.csv --vo vo.csv --beats beats.csv --segments segments.csv --project project.json --strict-files
python scripts/validate_tasks.py --tasks h3_tasks.json --segments segments.csv
python scripts/selftest.py
python scripts/export_h3.py --shots shots.csv --segments segments.csv --prompts h3_prompts.csv --out h3_package
python scripts/timeline.py --shots shots.csv --vo vo.csv --animatic animatic.mp4
python scripts/vo_gap_report.py --vo vo.csv --audio vo_scratch.wav --out vo_gap.md
python scripts/vo_diff.py --old vo_versions/vo_v1.csv --new vo.csv --out vo_diff.md
python scripts/vo2srt.py --vo vo.csv --out subtitles.srt --max-chars 18
python scripts/contact_sheet.py --clips clips --out review --frames 6
python scripts/cost_report.py --tasks tasks.json --out cost.csv --default-model MiniMax-H3

Scripts: init_project.py, validate.py, selftest.py, export_h3.py, timeline.py, narration_lint.py, vo2srt.py, vo_gap_report.py, vo_diff.py, contact_sheet.py, cost_report.py. --animatic por defecto usa fotograma negro como placeholder si falta el primer fotograma; --animatic-missing error puede cambiarse para que dé error.

validate.py gestiona el contrato estructural (esquema/ritmo/corte de segmento/cobertura). G3 por defecto no verifica archivos de keyframe; G5 usa --strict-files para verificarlos. timeline.py --vo gestiona el tiempo (espacio/densidad/toma larga). Ejecuta ambos, no se reemplazan mutuamente.

Manejo de fallos

Fallo de video: verifica el estado de la tarea; los fallos no se facturan; cambia a H3-Max o modifica el primer fotograma, no vuelvas a ejecutar ciegamente;
Cambio de rostro/muchas manos en el人物: regenera o cambia a perfil/vista trasera;
La acción no ocurrió: regenera, no la suplanes con la edición;
Desbordamiento de subtítulos: cambia el estilo/divide líneas, no reduzcas hasta que sea ilegible;
Música abrupta: añade pickup, expression ramp, handle, no cortes bruscos;
Relación de aspecto incorrecta en la exportación: vuelve al proyecto y cambia a 1920×1080, no estires la imagen.

Referencias

SOP.md: Flujo de trabajo y lista de verificación para humanos
references/: Detalles de las fases (incluye 00_setup.md, 09_vo_spans.md, 10_model_routing.md, 11_narration.md, 12_change_control.md, 13_parallel_work.md, 14_v0_animatic.md, 15_beats_segments.md)
providers/: Herramientas reemplazables
templates/: Tarjeta de proyecto, tabla de tomas, prompts, tabla de revisión, cue sheet, créditos, control de calidad final

yinguozhang/ai-documentary-production

¿Qué es ai-documentary-production?

Preguntar en tu IA favorita

Documentación