> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Venice Video Harness
> Controla Venice desde Claude Code o Cursor con un harness para vídeos con personajes consistentes, storyboards, tráileres y narrativa.
El [Venice Video Harness](https://github.com/jordanurbs/venice-video-harness) es un toolkit comunitario, agent-first y optimizado para Venice para **creación de vídeo consistente de cualquier duración**. Convierte un agente de IDE (Claude Code, Cursor, Codex, etc.) en operador de un sistema de producción Venice reutilizable que cubre más de 50 modelos de vídeo, imagen, audio y música de Venice.
Licencia MIT. Mantenido por la comunidad.
Bloquea personajes, voces y estética en toda una serie
Generación de paneles en dos pasadas con refinamiento multi-edit de Venice
Transcribe en local con whisper.cpp, corta desde un pack de 12 KB, self-eval en cada límite
## Qué es esto
La mayoría de integraciones de Venice son envoltorios finos sobre llamadas a la API. El Venice Video Harness es la **capa de más alto nivel** que se sitúa entre tu agente y la API de Venice:
* **Reglas de orquestación** en `CLAUDE.md`
* **Playbooks reutilizables** en `.claude/commands/` (19 comandos de flujo de trabajo)
* **Agentes especializados** en `.claude/agents/` (art-director, prompt-engineer, cut-qa y más)
* **Skills de producción de Venice** en `.claude/skills/` (compatibles con el formato [Agent Skills](/guides/integrations/venice-skills))
* **Capa de ejecución en TypeScript** en `src/`
* **Registro de modelos completo** que cubre más de 50 modelos de vídeo, imagen, audio y música de Venice
Construido para creadores que producen:
* Proyectos de vídeo con personajes consistentes (cualquier género, cualquier duración)
* Series o campañas con estilo visual bloqueado
* Flujos de trabajo de storyboard a vídeo
* Contenido narrativo de corta y larga duración
* Secuencias cinematográficas de marca, tráileres y teasers
* Series sociales con personajes recurrentes
## Empezar
### Requisitos
Se recomienda la última LTS
En tu PATH
Desde [venice.ai/settings/api](https://venice.ai/settings/api)
Opcional, para la pipeline de edición: instala `whisper-cpp` para transcripción local.
```bash theme={"system"}
brew install whisper-cpp
mkdir -p ~/.cache/whisper.cpp
curl -L -o ~/.cache/whisper.cpp/ggml-base.en.bin \
https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin
```
### Configuración
```bash theme={"system"}
git clone https://github.com/jordanurbs/venice-video-harness.git
cd venice-video-harness
```
```bash theme={"system"}
cp .env.example .env
# Añade VENICE_API_KEY a .env
```
```bash theme={"system"}
npm install
npm run build
```
Abre el proyecto en Cursor, Claude Code o cualquier IDE con chat agéntico. El agente lee `CLAUDE.md` y los playbooks automáticamente.
Prueba uno de estos primeros mensajes:
* "Set up this Venice video harness for first use"
* "Create a new character-consistent video series"
* "Generate a 30-second branded video sequence"
* "Build a multi-episode narrative with locked characters"
* "Create a product launch trailer with consistent visual style"
## Qué tiene de optimizado para Venice
* **Prompts de imagen afinados para los modelos de imagen de Venice** como `seedream-v5-lite`, `nano-banana-pro`, `flux-2-pro/max` y más
* **Generación de paneles en dos pasadas** con refinamiento multi-edit de Venice para corrección de personajes
* **Lógica de enrutamiento de modelos** para niveles de acción, atmósfera y consistencia de personajes
* **Generación de vídeo consciente de referencias** que usa `elements`, `reference_image_urls` y `scene_image_urls` correctamente por modelo
* **Adaptación de prompts consciente del entorno** para manejo de escenas de día vs noche
* **Rutas de audio nativas de Venice** para TTS (Kokoro, Qwen3, ElevenLabs), SFX y música
* **Estimación de coste** antes de generar mediante `/video/quote` y `/audio/quote`
* **Construcción de parámetros consciente del modelo** que omite automáticamente los parámetros que el modelo de destino no admite
## Defaults de enrutamiento de modelos
Los defaults del harness son opinionados porque la consistencia es lo importante. El enrutamiento actual (abril de 2026):
**Seedance 2.0 R2V por defecto. Fallback a Kling O3 R2V para escenas con 3+ personajes. Seedance 2.0 i2v para tomas de establecimiento.**
| Rol | Modelo predeterminado | Cuándo se usa |
| ------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Tomas de personaje (1-2 personajes) | `seedance-2-0-reference-to-video` | R2V por defecto con `reference_image_urls` planos, etiquetas `@Image`, hasta 15s, audio estéreo nativo |
| Tomas de personaje (3+ personajes) | `kling-o3-standard-reference-to-video` | Fallback automático con `elements` estructurados para identidad multi-personaje |
| Establecimiento / atmósfera / acción | `seedance-2-0-image-to-video` | Sin personajes; calidad cinematográfica épica, hasta 15s |
Estos son sobrescribibles por proyecto vía `series.json → videoDefaults`. Para apuntar a una familia que no sea Seedance (p. ej., cuentas sin acceso a Seedance), establece `videoDefaults` en `kling-o3-standard-reference-to-video` y `veo3.1-fast-image-to-video`.
**Regla de rostros de Seedance:** Seedance 2.0 bloquea las imágenes de entrada con rostros que no hayan sido producidas por `seedream-v5-lite` o `seedream-v5-lite-edit`. El harness lo gestiona automáticamente enrutando el trabajo de imagen con personajes a través de Seedream y ejecutando un control previo antes de cada llamada a Seedance.
## Modelos de Venice admitidos
### Vídeo (abril de 2026)
| Familia | i2v | t2v | Duración máx. | Audio | Notas |
| ------------------------- | -------------------------- | --------------------- | ------------- | ------------------------------------ | ----------------------------------------------------------------------- |
| **Seedance 2.0** | i2v, R2V | t2v | 15s | Sí (estéreo, lip-sync en 8+ idiomas) | Nº 1 en ranking. R2V: `reference_image_urls` plano, etiquetas `@Image`. |
| **Kling V3** | Pro, Standard | Pro, Standard | 15s | Sí | `end_image_url` para apuntar a frames |
| **Kling O3** | Pro, Std, Pro R2V, Std R2V | Pro, Standard | 15s | Sí | R2V: `elements`, `reference_image_urls`, `scene_image_urls` |
| **Kling 2.6 / 2.5 Turbo** | Pro | Pro | 10s | 2.6: Sí / 2.5: No | `end_image_url` |
| **Veo 3.1** | Fast, Full | Fast, Full | 8s | Sí | Hasta resolución 4K |
| **Sora 2** | Standard, Pro | Standard, Pro | 12s | Sí | Hasta 1080p |
| **Wan 2.6 / 2.5** | Std, Flash / Sí | Std / Sí | 15s / 10s | Sí | Entrada `audio_url` |
| **LTX Video 2.0** | Fast, Full, v2.3, 19B | Fast, Full, v2.3, 19B | 20s | Sí | Hasta 4K, el más largo sincronizado |
| **Longcat** | Std, Distilled | Std, Distilled | **30s** | No | Toma única más larga |
| **Vidu Q3** | Sí | Sí | 16s | Sí | `reference_image_urls` |
| **PixVerse v5.6** | Std, Transition | Standard | 8s | Sí | Transition: `end_image_url` |
| **Grok Imagine** | Sí | Sí | 15s | Sí | Soporte amplio de aspect ratio |
### Imagen, audio y música
* **Imagen (22+ modelos):** `nano-banana-pro/2`, `gpt-image-2`, `flux-2-pro/max`, `grok-imagine`, `qwen-image-2-pro`, `recraft-v4-pro`, `seedream-v4` / `v5-lite`, `lustify-sdxl/v7`, `wai-Illustrious` y más
* **Multi-edit:** `qwen-edit`, `flux-2-max-edit`, `nano-banana-pro-edit`, `seedream-v5-lite-edit`, `gpt-image-2-edit` y más
* **TTS:** `tts-kokoro` (50+ voces), `tts-qwen3-0-6b/1-7b`, `elevenlabs-tts-v3`, `elevenlabs-tts-multilingual-v2`
* **Música:** `elevenlabs-music`, `minimax-music-v2`, `ace-step-15`, `stable-audio-25`
* **SFX:** `elevenlabs-sound-effects-v2`, `mmaudio-v2-text-to-audio`
## Pipelines de producción
### Pipeline de generación
Vídeo narrativo de extremo a extremo (guion → storyboard → vídeo → audio → ensamblaje):
```bash theme={"system"}
npm run dev -- produce-episode -p output/my-series -e 1
```
La implementación de referencia en `src/mini-drama/` cubre:
* Gestión de series / personajes / episodios
* Workshopping de guion impulsado por LLM
* Generación de storyboard en dos pasadas (generar + refinar con multi-edit)
* QA de paneles basada en visión
* Generación de vídeo con encadenamiento de frames
* Post-producción de audio por capas
* Burn-in de subtítulos y ensamblaje final
### Pipeline de edición
Corta medios ya existentes (tomas generadas con Venice o metraje real). **Text-first**: el LLM lee un `takes_packed.md` compacto (\~12 KB por 40 min de audio) en lugar de hacer dump de frames del vídeo.
Los cinco pasos:
whisper.cpp local produce un `*.words.json` por fuente + `takes_packed.md`.
El LLM forma una estrategia de corte solo a partir del texto.
Propone la estrategia y espera "yes / revise / cancel".
Lista de cortes JSON → concat de ffmpeg con fades de audio de 30 ms. Archive-first, los originales nunca se sobrescriben.
El agente `cut-qa` ejecuta 6 comprobaciones programáticas en cada límite de corte; máximo 3 iteraciones de corrección.
Las comprobaciones de `cut-qa` detectan regresiones de aspect-ratio, saltos de hash de frame dentro de una palabra, truncamientos de VO, discontinuidad de iluminación, picos de audio por encima de -6 dBFS y solapamiento de subtítulos con texto en pantalla.
La pipeline de edición está inspirada en [browser-use/video-use](https://github.com/browser-use/video-use). Su insight central, *"el LLM nunca ve el vídeo, lo lee"*, es lo que hace que la edición conducida por agentes funcione sin ahogarse en tokens de dump de frames.
## Comandos, agentes y skills
El harness expone 19 comandos de flujo de trabajo, 10 agentes especializados y 7 skills de producción. Aspectos destacados:
| Comando de workflow | Propósito |
| ---------------------------------- | ----------------------------------------------------- |
| `new-series` | Crea una nueva serie con estética bloqueada |
| `add-character` / `lock-character` | Bloqueo de personaje + voz |
| `workshop-episode` | Guion de episodio colaborativo |
| `storyboard-episode` | Storyboard de un episodio |
| `produce-episode` | Pipeline completa en un comando |
| `generate-trailer` | Pipeline completa de tráiler |
| `edit-footage` | Pipeline de edición text-first para medios existentes |
| `ingest-screenplay` | Ingesta de un guion Fountain o PDF |
| Agente especializado | Rol |
| -------------------- | ------------------------------------------------------------------------------ |
| `art-director` | Decisiones de estética, paleta, iluminación y composición |
| `prompt-engineer` | Prompts de imagen de Venice, consistencia de personajes |
| `storyboard-qa` | QA de paneles para continuidad y comprobaciones de personajes |
| `cut-qa` | Filtro de calidad post-render (6 comprobaciones por corte, máx. 3 iteraciones) |
| `overlay-designer` | Gráficos animados de marca, sub-agentes en paralelo |
| `trailer-curator` | Selección de tomas del tráiler y reglas anti-spoiler |
| Skill de producción | Propósito |
| ---------------------------- | ---------------------------------------------------------- |
| `venice-api` | Uso y defaults de la API REST de Venice |
| `venice-video-model-routing` | Enrutamiento R2V-first, árboles de decisión |
| `character-consistency` | Guía de consistencia de personajes multi-toma |
| `shot-composition` | Composición de toma y guía de cámara |
| `screenplay-parsing` | Flujos de parseo de guion |
| `video-editing` | Filosofía de edición text-first, formato EDL, bucle cut-qa |
## Round-trip con NLE
Tras renderizar, exporta el timeline ensamblado como XML para ajustes finos en tu editor preferido. Cada segmento de vídeo, clip de diálogo, clip de SFX y entrada de música cae en su propia pista.
```bash theme={"system"}
mini-drama export-timeline -p output/ -e 1 --format fcpxml # Final Cut Pro X
mini-drama export-timeline -p output/ -e 1 --format premiere # Premiere Pro
mini-drama export-timeline -p output/ -e 1 --format davinci # DaVinci Resolve
```
## Uso programático
También puedes llamar a los módulos del harness directamente desde tu propio TypeScript:
```typescript theme={"system"}
import { VeniceClient } from './src/venice/client.js';
import { generateVideo, quoteVideo } from './src/venice/video.js';
import { listVideoModels } from './src/venice/models.js';
const client = new VeniceClient();
const quote = await quoteVideo(client, {
model: 'kling-v3-pro-image-to-video',
duration: '8s',
audio: true,
});
console.log(`Estimated cost: $${quote.quote}`);
const result = await generateVideo(client, {
model: 'kling-v3-pro-image-to-video',
prompt: 'A slow dolly shot pushes forward...',
duration: '8s',
imageUrl: 'data:image/png;base64,...',
audio: true,
outputPath: 'output/shot-001.mp4',
});
const longModels = listVideoModels({ minDurationSec: 20 });
```
## Recursos
Código fuente, issues y releases
La API subyacente que controla el harness
Guía de R2V para consistencia de personajes
La familia de vídeo predeterminada del harness
Mantenido por la comunidad y proporcionado tal cual. Para problemas específicos del harness, ábrelos en el [repositorio de GitHub del proyecto](https://github.com/jordanurbs/venice-video-harness/issues).