> ## 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
> Use a Venice no Claude Code ou Cursor com um harness otimizado para vídeos com personagens consistentes, storyboards, trailers e narrativa longa.
O [Venice Video Harness](https://github.com/jordanurbs/venice-video-harness) é um kit de ferramentas comunitário, agent-first e otimizado para Venice, voltado para **criação de vídeo com foco em consistência, em qualquer duração**. Ele transforma um agente de IDE (Claude Code, Cursor, Codex etc.) em operador de um sistema reutilizável de produção Venice cobrindo mais de 50 modelos Venice de vídeo, imagem, áudio e música.
Licença MIT. Mantido pela comunidade.
Trave personagens, vozes e estética em uma série inteira
Geração de painéis em dois passos com refinamento multi-edit da Venice
Transcreva localmente com whisper.cpp, corte a partir de um pacote de 12KB, autoavalie em cada limite
## O que é isto
A maioria das integrações Venice são wrappers finos sobre chamadas de API. O Venice Video Harness é a **camada de mais alto nível** que fica entre seu agente e a API Venice:
* **Regras de orquestração** em `CLAUDE.md`
* **Playbooks reutilizáveis** em `.claude/commands/` (19 comandos de workflow)
* **Agentes especializados** em `.claude/agents/` (art-director, prompt-engineer, cut-qa e mais)
* **Skills de produção Venice** em `.claude/skills/` (compatíveis com o formato [Agent Skills](/guides/integrations/venice-skills))
* **Camada de execução TypeScript** em `src/`
* **Registro abrangente de modelos** cobrindo mais de 50 modelos Venice de vídeo, imagem, áudio e música
Construído para criadores produzindo:
* Projetos de vídeo com personagens consistentes (qualquer gênero, qualquer duração)
* Séries ou campanhas com estilo visual travado
* Workflows de storyboard para vídeo
* Conteúdo narrativo de curta ou longa duração
* Sequências cinemáticas de marca, trailers e teasers
* Séries sociais com personagens recorrentes
## Começando
### Requisitos
Recomenda-se o LTS mais recente
No seu PATH
De [venice.ai/settings/api](https://venice.ai/settings/api)
Opcional, para o pipeline de edição: instale `whisper-cpp` para transcrição 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
```
### Configuração
```bash theme={"system"}
git clone https://github.com/jordanurbs/venice-video-harness.git
cd venice-video-harness
```
```bash theme={"system"}
cp .env.example .env
# Adicione VENICE_API_KEY ao .env
```
```bash theme={"system"}
npm install
npm run build
```
Abra o projeto no Cursor, Claude Code ou em qualquer IDE com chat agêntico. O agente lê `CLAUDE.md` e os playbooks automaticamente.
Experimente uma destas primeiras mensagens:
* "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"
## O que é otimizado para Venice
* **Prompts de imagem ajustados para modelos de imagem Venice** como `seedream-v5-lite`, `nano-banana-pro`, `flux-2-pro/max` e mais
* **Geração de painéis em dois passos** com refinamento multi-edit da Venice para correção de personagens
* **Lógica de roteamento de modelos** para níveis de ação, atmosfera e consistência de personagens
* **Geração de vídeo ciente de referência** que usa `elements`, `reference_image_urls` e `scene_image_urls` corretamente por modelo
* **Adaptação de prompt ciente do ambiente** para tratamento de cenas diurnas vs noturnas
* **Caminhos de áudio nativos da Venice** para TTS (Kokoro, Qwen3, ElevenLabs), SFX e música
* **Estimativa de custo** antes da geração via `/video/quote` e `/audio/quote`
* **Construção de parâmetros ciente do modelo** que pula automaticamente parâmetros que o modelo alvo não suporta
## Padrões de roteamento de modelos
Os padrões do harness são opinativos porque consistência é o ponto. Roteamento atual (abril de 2026):
**Seedance 2.0 R2V por padrão. Fallback Kling O3 R2V para cenas com 3+ personagens. Seedance 2.0 i2v para tomadas de estabelecimento.**
| Papel | Modelo padrão | Quando usado |
| --------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------- |
| Tomadas de personagem (1-2 personagens) | `seedance-2-0-reference-to-video` | R2V padrão com `reference_image_urls` flat, tags `@Image`, até 15s, áudio estéreo nativo |
| Tomadas de personagem (3+ personagens) | `kling-o3-standard-reference-to-video` | Auto-fallback com `elements` estruturados para identidade multi-personagem |
| Estabelecimento / atmosfera / ação | `seedance-2-0-image-to-video` | Sem personagens; qualidade cinemática épica, até 15s |
Esses são sobrescritíveis por projeto via `series.json → videoDefaults`. Para mirar em uma família que não seja Seedance (por exemplo, contas que não têm acesso ao Seedance), defina `videoDefaults` como `kling-o3-standard-reference-to-video` e `veo3.1-fast-image-to-video`.
**Regra de face do Seedance:** o Seedance 2.0 bloqueia imagens de entrada com rostos que não foram produzidas por `seedream-v5-lite` ou `seedream-v5-lite-edit`. O harness trata isso automaticamente, roteando trabalhos de imagem com personagens pelo Seedream e executando um gate de pré-voo antes de cada chamada ao Seedance.
## Modelos Venice suportados
### Vídeo (abril de 2026)
| Família | i2v | t2v | Duração máx. | Áudio | Notas |
| ------------------------- | -------------------------- | --------------------- | ------------ | ---------------------------------- | ----------------------------------------------------------------- |
| **Seedance 2.0** | i2v, R2V | t2v | 15s | Sim (estéreo, lip-sync 8+ idiomas) | Nº 1 do ranking. R2V: `reference_image_urls` flat, tags `@Image`. |
| **Kling V3** | Pro, Standard | Pro, Standard | 15s | Sim | `end_image_url` para mirar frame |
| **Kling O3** | Pro, Std, Pro R2V, Std R2V | Pro, Standard | 15s | Sim | R2V: `elements`, `reference_image_urls`, `scene_image_urls` |
| **Kling 2.6 / 2.5 Turbo** | Pro | Pro | 10s | 2.6: Sim / 2.5: Não | `end_image_url` |
| **Veo 3.1** | Fast, Full | Fast, Full | 8s | Sim | Resolução até 4K |
| **Sora 2** | Standard, Pro | Standard, Pro | 12s | Sim | Até 1080p |
| **Wan 2.6 / 2.5** | Std, Flash / Sim | Std / Sim | 15s / 10s | Sim | Entrada `audio_url` |
| **LTX Video 2.0** | Fast, Full, v2.3, 19B | Fast, Full, v2.3, 19B | 20s | Sim | Até 4K, mais longo sincronizado |
| **Longcat** | Std, Distilled | Std, Distilled | **30s** | Não | Tomada única mais longa |
| **Vidu Q3** | Sim | Sim | 16s | Sim | `reference_image_urls` |
| **PixVerse v5.6** | Std, Transition | Standard | 8s | Sim | Transition: `end_image_url` |
| **Grok Imagine** | Sim | Sim | 15s | Sim | Suporte amplo a aspect ratio |
### Imagem, áudio e música
* **Imagem (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` e mais
* **Multi-edit:** `qwen-edit`, `flux-2-max-edit`, `nano-banana-pro-edit`, `seedream-v5-lite-edit`, `gpt-image-2-edit` e mais
* **TTS:** `tts-kokoro` (50+ vozes), `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 produção
### Pipeline de geração
Vídeo narrativo ponta a ponta (roteiro → storyboard → vídeo → áudio → montagem):
```bash theme={"system"}
npm run dev -- produce-episode -p output/my-series -e 1
```
A implementação de referência em `src/mini-drama/` cobre:
* Gerenciamento de séries / personagens / episódios
* Workshop de roteiro com LLM
* Geração de storyboard em dois passos (gerar + refinar com multi-edit)
* QA de painéis baseado em visão
* Geração de vídeo com encadeamento de frames
* Pós-produção de áudio em camadas
* Burn-in de legendas e montagem final
### Pipeline de edição
Corte mídia já existente (tomadas geradas pela Venice ou footage real). **Text-first**: o LLM lê um `takes_packed.md` compacto (\~12KB por 40 min de áudio) em vez de despejar frames de vídeo.
Os cinco passos:
O whisper.cpp local produz `*.words.json` por fonte + `takes_packed.md`.
O LLM forma uma estratégia de corte apenas a partir do texto.
Propõe a estratégia e espera por "yes / revise / cancel".
Lista de corte JSON → ffmpeg concat com fades de áudio de 30ms. Arquivo-first, então os originais nunca são sobrescritos.
O agente `cut-qa` executa 6 verificações programáticas em cada limite de corte; máximo de 3 iterações de correção.
As verificações do `cut-qa` pegam regressões de aspect-ratio, saltos de hash de frame dentro de uma palavra, truncamento de VO, descontinuidade de iluminação, picos de áudio acima de -6 dBFS e sobreposição de legendas com texto dentro do frame.
O pipeline de edição é inspirado em [browser-use/video-use](https://github.com/browser-use/video-use). A intuição central deles, *"o LLM nunca assiste ao vídeo, ele o lê"*, é o que faz a edição dirigida por agente funcionar sem se afogar em tokens de frame-dump.
## Comandos, agentes e skills
O harness expõe 19 comandos de workflow, 10 agentes especializados e 7 skills de produção. Destaques:
| Comando de workflow | Finalidade |
| ---------------------------------- | -------------------------------------------------- |
| `new-series` | Criar uma nova série com estética travada |
| `add-character` / `lock-character` | Travamento de personagem + voz |
| `workshop-episode` | Roteirização colaborativa de episódio |
| `storyboard-episode` | Storyboard de um episódio |
| `produce-episode` | Pipeline completo em um comando |
| `generate-trailer` | Pipeline completo de trailer |
| `edit-footage` | Pipeline de edição text-first para mídia existente |
| `ingest-screenplay` | Ingere um roteiro Fountain ou PDF |
| Agente especializado | Papel |
| -------------------- | --------------------------------------------------------------------------------- |
| `art-director` | Decisões de estética, paleta, iluminação, composição |
| `prompt-engineer` | Prompts de imagem Venice, consistência de personagem |
| `storyboard-qa` | QA de painéis para continuidade e verificações de personagem |
| `cut-qa` | Gate de qualidade pós-renderização (6 verificações por corte, máximo 3 iterações) |
| `overlay-designer` | Motion graphics de marca, sub-agentes em paralelo |
| `trailer-curator` | Seleção de tomadas de trailer e regras antiespóileres |
| Skill de produção | Finalidade |
| ---------------------------- | ------------------------------------------------------------- |
| `venice-api` | Uso da REST API da Venice e padrões |
| `venice-video-model-routing` | Roteamento R2V-first, árvores de decisão |
| `character-consistency` | Orientação de consistência de personagem em múltiplas tomadas |
| `shot-composition` | Composição de tomada e orientação de câmera |
| `screenplay-parsing` | Workflows de parsing de roteiro |
| `video-editing` | Filosofia de edição text-first, formato EDL, loop do cut-qa |
## Round-trip NLE
Após a renderização, exporte a timeline montada como XML para ajuste fino no editor de sua escolha. Cada segmento de vídeo, clipe de diálogo, clipe de SFX e cue musical fica em sua própria trilha.
```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
Você também pode chamar os módulos do harness diretamente do seu próprio 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-fonte, issues e releases
A API subjacente que o harness opera
Guia R2V para consistência de personagem
A família de vídeo padrão do harness
Mantido pela comunidade e fornecido como está. Para problemas específicos do harness, abra-os no [repositório do projeto no GitHub](https://github.com/jordanurbs/venice-video-harness/issues).