Generación de Video
Hace solo una cosa: hacer que las imágenes ya definidas cobren movimiento y dejar un registro rastreable.
El modelo de video aquí se encarga de tres cosas: movimiento, cámara y la lectura de la narración. La apariencia del sujeto, la vestimenta, el escenario, la paleta de colores, la iluminación, la composición y el texto en pantalla ya están fijados en S1/S2; esta capa no puede volver a crearlos. Si el modelo comienza a "improvisar", la consistencia de todo el metraje se rompe.
La narración ya no usa locución independiente. El diálogo se escribe en el prompt y el modelo lo lee directamente: esta es la mayor diferencia entre este flujo de trabajo y el enfoque tradicional, y también el punto que requiere más atención en esta capa.
I. Requisitos de entrada
Se necesitan cuatro elementos, sin uno de ellos, se devuelve el proceso a la etapa anterior:
| Elemento | Ubicación | ¿Qué pasa si falta? |
|---|---|---|
03-lista-de-generacion.md | Producido por short-video-prompt y aprobado en G2 | No se sabe cuántos segmentos generar ni su duración |
| Texto del diálogo por segmento | En el prompt de cada segmento de la lista | El modelo no sabe qué leer e inventará el diálogo |
| Imagen de activo / primer fotograma | 04-materiales/01-imagenes-activo/, 04-materiales/02-primer-fotograma/ | El sujeto varía de un segmento a otro |
KIE_API_KEY | Variable de entorno | No se pueden enviar tareas |
No tener un primer fotograma no significa que no se pueda hacer: para tomas puramente atmosféricas, de transición o de recurso, se puede usar directamente el modo texto a video. Pero para segmentos donde aparece un sujeto, es obligatorio tener una imagen; esta es una regla estricta.
Para segmentos sin diálogo se puede omitir la narración, como tomas de recurso o secuencias puramente musicales. Pero si un segmento debe hablar, el diálogo debe estar en el prompt; esta es la única fuente de sonido actual.
II. Tres modos, mutuamente excluyentes y no mezclables
Una solicitud de la plataforma solo puede elegir un modo. Si los campos se cruzan, se convierte en otro modo y la tarea falla directamente.
| Modo | Campos obligatorios | ¿Cuándo usarlo? | Prohibido explícitamente |
|---|---|---|---|
text (Texto a video) | prompt | Tomas atmosféricas, de recurso, efectos de luz de fondo puros, transiciones | Incluir first_frame_url / last_frame_url |
first (Primer fotograma a video) | prompt + first_frame_url | Por defecto, este: se necesita fijar la composición inicial | Incluir last_frame_url |
first-last (Primer y último fotograma) | prompt + primer fotograma + último fotograma | Se necesita fijar tanto el inicio como el final para asegurar la continuidad entre segmentos adyacentes | — |
Cómo implementar el modo "imagen de referencia" de la lista
La columna de modo de la lista de short-video-prompt puede ser "primer-último fotograma / imagen de referencia / texto a video". El modelo actual no tiene modo de imagen de referencia — los campos como reference_image_urls no están disponibles en este modelo. Por lo tanto, se debe hacer una asignación:
| Lo que dice la lista | Lo que se envía realmente | Explicación |
|---|---|---|
| Primer-último fotograma | first-last | Directo |
| Imagen de referencia | first | Usar la imagen de referencia como primer fotograma para fijar la composición inicial |
| Texto a video | text | Directo, pero solo para tomas sin sujeto |
Esto no es un compromiso, es un límite de capacidad. Si un segmento realmente necesita "imagen de referencia para fijar el sujeto + composición libre", la única opción es fijar la composición con el primer fotograma, o volver a S2 para modificar la segmentación.
III. Parámetros
| Parámetro | Valores | Valor por defecto | Explicación |
|---|---|---|---|
duration | 4-15 segundos, entero | 5 | Si supera 15, dividir en múltiples tomas; por debajo de 4, pasar a postproducción para efectos o recorte |
aspect_ratio | 9:16 / 16:9 / 1:1 / 3:4 / 4:3 / 21:9 / adaptive | 9:16 | adaptive solo para texto a video; para generación con imagen, la proporción debe ser fija |
resolution | 480p / 720p | 480p | Por defecto para controlar costos de generación; para resolución de entrega formal, pasar explícitamente 720p |
generate_audio | true / false | true | No se puede desactivar. La narración está en esta pista de audio; desactivarla significa que no hay sonido |
web_search | true / false | false | Solo disponible para texto a video, generalmente no se usa |
Tres puntos propensos a errores:
- La proporción debe coincidir con la salida real. Si el modelo devuelve un resultado con una proporción claramente diferente o con bordes negros, se considera un fallo de calidad. No se permite hacer letterbox y entregarlo como producto final.
- El audio debe estar activado. La narración y los sonidos ambientales están todos en esta pista. Solo para tomas puramente atmosféricas que realmente no necesiten sonido se usa
--no-audio. durationdebe ser un entero. Pasar 5.5 será rechazado.
IV. Proceso de siete pasos
① Leer lista → ② Definir modo → ③ Escribir prompt de video → ④ Enviar → ⑤ Consultar y descargar → ⑥ Inspeccionar medios → ⑦ Extraer fotogramas para control de calidad
① Leer la lista, primero verificar si se puede ejecutar
Revisar tres cosas por segmento. Si algo no coincide, detenerse y preguntar, no adivinar:
- Si la
durationde cada segmento está entre 4 y 15 (si supera, dividir primero) - Si el archivo del primer fotograma declarado realmente existe
- Si los números de material referenciados están todos en el inventario de activos
② Definir el modo
Definir por segmento según la tabla de la Sección II. Intentar que todo el proyecto sea lo más uniforme posible. Mezclar modos no es un error, pero hará que la transición entre segmentos adyacentes sea más fea.
③ Escribir el prompt de video
Escribir según la estructura de siete secciones en references/video-prompt.md. Dos reglas principales:
- Describir solo el "cambio", no redescibir "qué es". El primer fotograma ya le ha dado al modelo la apariencia del producto. Si el prompt la describe de nuevo, el modelo la volverá a dibujar según el texto, perdiendo la consistencia inmediatamente.
- Copiar el diálogo textualmente, sin cambiar ni una palabra. La narración ahora la lee el modelo directamente, por lo que el texto original del diálogo debe estar en el prompt. Cambiar una palabra hará que los subtítulos no coincidan con el audio.
④ Enviar
python scripts/kie_seedance.py create \
--prompt "…" --mode first \
--first 04-materiales/02-primer-fotograma/S01_f01_v1.png \
--duration 6 --out 04-materiales/03-clips/S01_v1.mp4 --wait
Inmediatamente después del envío exitoso, escribir el taskId y la huella en el libro de registro, y luego hacer otra cosa. Registrar primero, luego hacer; si se interrumpe a medio camino, no se podrá recuperar.
④-2 Ejecución por lotes de toda la película (5 concurrentes por defecto)
Ejecutar un segmento tras otro de forma secuencial: para 6 segmentos serían más de 30 minutos, y la mayor parte del tiempo se espera. La ejecución por lotes concurrente hace que el tiempo total sea aproximadamente igual al del segmento más lento.
# Primero, un ensayo para ver la solicitud ensamblada
python scripts/kie_seedance.py batch --tasks tasks.json --out-dir 04-materiales/03-clips --dry-run
# Después de confirmar, ejecutar realmente, por defecto 5 segmentos a la vez
python scripts/kie_seedance.py batch --tasks tasks.json --out-dir 04-materiales/03-clips
# Si hay limitación de velocidad, reducir
python scripts/kie_seedance.py batch --tasks tasks.json --out-dir 04-materiales/03-clips --concurrency 2
El formato del archivo de tareas está en assets/batch-tasks-example.json, una entrada por segmento. Los campos mode / first / last / duration / prompt tienen el mismo significado que en el comando individual.
La concurrencia no siempre es mejor: tiene una trampa real: desordenará el libro de registro.
Si 5 segmentos terminan al mismo tiempo y cada uno intenta modificar 00-libro-de-registro-generacion.md al finalizar, las cinco escrituras se sobrescribirán mutuamente, dejando solo el registro del último segmento. La forma correcta de hacerlo es:
① Ejecutar todo el lote, recoger los items en el resumen (ya ordenados según la lista)
② Escribir el libro de registro de una sola vez: los cinco segmentos juntos, no uno por uno
③ Inmediatamente después de escribir, verificar: la lista debe tener tantas filas como el libro de registro
Si prefieres registrar sobre la marcha, reduce la concurrencia a 1 — la ejecución secuencial con registro sobre la marcha es la única manera de no desordenar los datos. Esta compensación debes decidirla tú mismo, pero no puedes tener concurrencia y escritura fragmentada al mismo tiempo.
La limitación de velocidad se manifiesta con code != 200 o HTTP 429, no con "peor calidad de imagen". Al ver estos errores, primero reduce la concurrencia, no modifiques el prompt.
El fallo no interrumpe el lote: si un segmento falla, el resto continúa. Al final, revisa los failed en el resumen. Si quieres detenerte al primer error, añade --stop-on-error; esto detendrá el envío de nuevas tareas, pero las que ya se están ejecutando no se verán afectadas.
⑤ Consultar y descargar
--wait esperará hasta que la descarga esté completa. También se puede hacer por separado: create para obtener el taskId → wait --task-id.
El intervalo de consulta comienza en 6 segundos y se extiende gradualmente hasta 30 segundos, con un límite de 15 minutos. Superar el límite no significa que haya fallado; primero verifica el estado y luego decide.
⑥ Inspección de medios (con script)
# Para segmentos con diálogo: la pista de audio debe existir
python scripts/inspect_clip.py --file 04-materiales/03-clips/S01_v1.mp4 \
--ratio 9:16 --duration 6 --expect-audio
# Para tomas de recurso sin diálogo: no debe haber pista de audio
python scripts/inspect_clip.py --file S02_v1.mp4 --no-expect-audio
Verifica cinco hechos objetivos: si el archivo existe, si el tamaño es normal, si la duración es correcta, si la proporción es correcta y si la pista de audio está presente. Pasar esta verificación solo significa "se ha descargado un archivo reproducible", no que la imagen sea utilizable, y mucho menos que el diálogo se haya leído correctamente.
La pista de audio ahora es más importante que antes: la narración está en esta pista. Sin pista de audio = el segmento no tiene sonido, es un clip inservible. Si la pista existe pero se lee mal una palabra, el script no lo detectará; solo se puede verificar escuchando.
⑦ Extracción de fotogramas para control de calidad + escucha (humano)
Imagen: Extraer al menos tres puntos (inicio, mitad, final) y revisar según los siete puntos de references/clip-review.md.
Audio: Como la narración ahora la lee el modelo, cada segmento con diálogo debe escucharse por completo, comparando con el guion original para verificar tres cosas:
| Qué escuchar | Criterio |
|---|---|
| Si falta alguna frase | El guion original tiene X frases, se deben escuchar X frases |
| Si se ha leído mal alguna palabra | Palabras clave, nombre de marca, números, ¿son correctos? |
| Si hay sonidos no deseados | Música de fondo no deseada, otras voces, ruido |
Cuando lo que se escucha no coincide con el guion, no lo aceptes. Hay dos opciones: regenerar este segmento o modificar los subtítulos para que coincidan con lo que realmente se dijo. Lo único que no se puede hacer es poner subtítulos según el guion original: el público oirá una cosa y verá otra, lo cual es peor que el propio error de lectura.
Este paso es obligatorio. Para palabras clave ambiguas, se puede usar la transcripción repetida al menos tres veces como ayuda, pero la revisión final debe ser humana, frase por frase. Luego, escribir la conclusión en 04-materiales/00-dialogo-definitivo.json; ver references/clip-review.md.
V. Tres niveles de estado, no mezclar
| Estado | Quién lo decide | Significado |
|---|---|---|
| Medio aprobado | Script | Archivo completo, parámetros correctos, pista de audio presente |
| Imagen aprobada | Humano | Sujeto sin cambiar, sin deformidades, puede continuar al siguiente segmento |
| Diálogo aprobado | Humano | Diálogo completo, palabras clave sin errores |
Solo cuando los tres están aprobados, el estado puede ser "Aprobado en calidad".
Tomar "descarga completa" como "utilizable" es el error más común en esta cadena: el metraje llega a la sala de edición y se descubre que el sujeto del segmento 4 ha cambiado, y todo el trabajo de edición anterior fue en vano. Ahora hay una capa más: la imagen puede estar bien, pero si el diálogo tiene una palabra mal leída, todo el segmento sigue siendo inservible porque los subtítulos no coincidirán.
La capa del diálogo es la que más fácilmente se salta, porque requiere ponerse auriculares y escuchar con atención, no solo echar un vistazo.
VI. Libro de registro: escribir en 04-materiales/00-libro-de-registro-generacion.md
Una fila por segmento, registrando seis elementos: huella de la solicitud, modo, taskId, estado, archivo de salida, razón del fallo.
La función del libro de registro no es solo archivar, sino evitar envíos duplicados. Si se vuelve a trabajar en la misma película un día después, al leer el libro de registro se sabe qué segmento está completo, cuál se envió pero no se descargó y cuál falló.
Las reglas están en references/task-ledger.md, cuatro resúmenes:
- Estado "Aprobado en calidad" y archivo presente → Saltar
- Tiene taskId y estado "Esperando / Generando" → Solo consultar, no crear uno nuevo
- Estado "Generado con éxito, pendiente de descarga" → Solo descargar; si la URL ha expirado, consultar el mismo taskId para obtener una nueva URL
- Estado "Fallido" → No reintentar automáticamente, esperar a que el usuario diga explícitamente que lo rehaga
VII. Cómo manejar los fallos
Primero localizar en qué capa ocurrió el fallo, luego decidir qué cambiar. No empieces modificando el prompt.
| Síntoma | Causa raíz | Dónde cambiar |
|---|---|---|
| Sujeto deformado, producto cambiado | No hay primer fotograma, o el primer fotograma en sí es incorrecto | Añadir / cambiar el primer fotograma |
| Imagen temblorosa, parpadeante | Demasiadas acciones descritas | Reducir a una sola acción |
| Texto desordenado, dedos extra | Pedir al modelo que escriba texto o haga gestos complejos con las manos | Texto a postproducción, simplificar gestos |
| Proporción incorrecta, bordes negros | Parámetros y resultado no coinciden | Marcar como fallido, regenerar, no recortar bordes negros |
| Segmentos que no conectan | El último fotograma no coincide con el primer fotograma del segmento siguiente | Usar modo primer-último fotograma, o añadir fotograma de transición |
| Omisión de frase, solo se lee la mitad | La cantidad de texto del diálogo excede la duración del segmento | Acortar el diálogo, o dividir este segmento en dos |
| Palabra mal leída, se dice otra palabra | Caracteres poco comunes, homógrafos, nombres de marca dentro de una frase larga | Cambiar a una expresión más común; poner el nombre de la marca en una frase separada |
| Diálogo tapado por la música | El prompt no especifica "sin música de fondo" o "no cubrir la voz" | Añadir una restricción de sonido y regenerar |
| Sin sonido en absoluto | Se usó --no-audio por error, o el audio no se activó | Revisar los parámetros de envío, regenerar |
| Error al enviar / HTTP 429 | Demasiada concurrencia, limitado por la plataforma | Reintentar con --concurrency 2, no cambiar el prompt |
| El mismo segmento falla repetidamente | Múltiples variables cambiando a la vez | Cambiar solo una variable a la vez |
Los problemas relacionados con el diálogo representan más de la mitad de los casos. La característica común de estos problemas es: la imagen se ve bien, solo se descubre al escuchar. Por lo tanto, cada segmento debe escucharse por completo antes de aprobarlo.
Al rehacer, cambiar solo una variable a la vez. Si cambias prompt, duración y primer fotograma al mismo tiempo, incluso si tiene éxito, no sabrás qué variable funcionó, y el mismo problema volverá a ocurrir la próxima vez.
Para un diagnóstico detallado, ver references/clip-review.md.
VIII. Límites
- No rediseñar el aspecto visual: El sujeto, el escenario, la paleta de colores y la iluminación ya están fijados en S2; aquí solo se les da movimiento.
- No cambiar el texto del diálogo: Se lee tal como está escrito. Para cambiar palabras, volver a S1/S2, no hacer ajustes temporales aquí.
- No hacer subtítulos: El texto siempre se añade en postproducción. El modelo puede "leer" chino, pero no "escribir" caracteres chinos.
- No editar audio: Los segmentos con errores de lectura solo se pueden regenerar o modificar los subtítulos para que coincidan. Aquí no se mezcla ni se regraba audio.
- No hacer edición: No se unen segmentos, no se ajustan al ritmo, no se corrigen colores; eso es para S4.
- No juzgar "si es bonito" : Solo se juzga "si es utilizable". La apreciación visual es responsabilidad de la revisión del metraje.
- No prometer que funcione a la primera: La generación es un evento probabilístico; tener 2-4 candidatos es normal, no un fallo.
IX. Referencias
| Archivo | Cuándo leerlo |
|---|---|
references/api-and-modes.md | Para consultar la API, parámetros, campos de los tres modos, respuestas de error |
references/video-prompt.md | Para escribir o modificar prompts de video |
references/task-ledger.md | Para crear el libro de registro, reanudar el trabajo, decidir si se debe reenviar |
references/clip-review.md | Para extraer fotogramas para control de calidad, determinar fallos, decidir la dirección de la corrección |
| references/assembly-ops.md | Detalles de implementación de FFmpeg para edición S4, subtítulos y mezcla de audio |
assets/gen-ledger-template.md | Para crear el libro de registro |
| assets/dialogue-final-template.json | Para registrar el diálogo definitivo, transcripciones auxiliares y revisión humana final |
assets/batch-tasks-example.json | Para ejecuciones por lotes |
Scripts:
| Script | Propósito |
|---|---|
scripts/kie_seedance.py | Enviar / por lotes / consultar / esperar descarga / subir fotogramas de referencia |
scripts/inspect_clip.py | Inspección de medios (requiere ffprobe) |