> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-ce69695c.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Venice Video Harness
> Guida Venice da Claude Code o Cursor con il toolkit Venice Video Harness per video con personaggi coerenti, storyboard e narrazioni.
Il [Venice Video Harness](https://github.com/jordanurbs/venice-video-harness) è un toolkit community, agent-first, ottimizzato per Venice per la **creazione di video consistency-first di qualsiasi durata**. Trasforma un agente IDE (Claude Code, Cursor, Codex, ecc.) in un operatore di un sistema di produzione Venice riutilizzabile che copre oltre 50 modelli Venice per video, immagini, audio e musica.
Licenza MIT. Mantenuto dalla community.
Blocca personaggi, voci ed estetiche in un'intera serie
Generazione dei pannelli a due passaggi con raffinamento multi-edit Venice
Trascrivi in locale con whisper.cpp, taglia da un pack di 12KB, auto-valutazione a ogni transizione
## Cos'è
La maggior parte delle integrazioni Venice sono semplici wrapper intorno alle chiamate API. Il Venice Video Harness è il **livello di alto livello** che si colloca tra il tuo agente e l'API Venice:
* **Regole di orchestrazione** in `CLAUDE.md`
* **Playbook riutilizzabili** in `.claude/commands/` (19 comandi di workflow)
* **Agenti specializzati** in `.claude/agents/` (art-director, prompt-engineer, cut-qa e altri)
* **Skill di produzione Venice** in `.claude/skills/` (compatibili con il formato [Agent Skills](/guides/integrations/venice-skills))
* **Livello di esecuzione TypeScript** in `src/`
* **Registry completo dei modelli** che copre oltre 50 modelli Venice per video, immagini, audio e musica
Costruito per creator che producono:
* Progetti video character-consistent (qualsiasi genere, qualsiasi durata)
* Serie o campagne con stile visivo bloccato
* Workflow storyboard-to-video
* Contenuti narrativi short-form e long-form
* Sequenze cinematiche brandizzate, trailer e teaser
* Serie social con personaggi ricorrenti
## Per iniziare
### Requisiti
LTS più recente consigliato
Nel tuo PATH
Da [venice.ai/settings/api](https://venice.ai/settings/api?utm_source=venice-api-documentation)
Opzionale, per la pipeline di editing: installa `whisper-cpp` per la trascrizione locale.
```bash theme={null}
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
```
### Setup
```bash theme={null}
git clone https://github.com/jordanurbs/venice-video-harness.git
cd venice-video-harness
```
```bash theme={null}
cp .env.example .env
# Aggiungi VENICE_API_KEY a .env
```
```bash theme={null}
npm install
npm run build
```
Apri il progetto in Cursor, Claude Code o qualsiasi IDE con chat agentica. L'agente legge `CLAUDE.md` e i playbook automaticamente.
Prova uno di questi primi messaggi:
* "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"
## Cosa lo rende Venice-optimized
* **Prompt per immagini ottimizzati per i modelli di immagini Venice** come `seedream-v5-lite`, `nano-banana-pro`, `flux-2-pro/max` e altri
* **Generazione dei pannelli a due passaggi** con raffinamento multi-edit Venice per la correzione dei personaggi
* **Logica di routing dei modelli** per i tier di azione, atmosfera e character-consistency
* **Generazione video reference-aware** che usa `elements`, `reference_image_urls` e `scene_image_urls` correttamente per ogni modello
* **Adattamento del prompt environment-aware** per la gestione delle scene diurne vs notturne
* **Percorsi audio Venice-native** per TTS (Kokoro, Qwen3, ElevenLabs), SFX e musica
* **Stima dei costi** prima della generazione tramite `/video/quote` e `/audio/quote`
* **Costruzione dei parametri model-aware** che salta automaticamente i parametri non supportati dal modello target
## Default di routing dei modelli
I default dell'harness sono opinionated perché la consistenza è il punto chiave. Il routing attuale (aprile 2026):
**Seedance 2.0 R2V di default. Fallback su Kling O3 R2V per scene con 3+ personaggi. Seedance 2.0 i2v per gli establishing shot.**
| Ruolo | Modello di default | Quando usato |
| - | - | - |
| Inquadrature con personaggi (1-2 personaggi) | `seedance-2-0-reference-to-video` | R2V di default con `reference_image_urls` flat, tag `@Image`, fino a 15s, audio stereo nativo |
| Inquadrature con personaggi (3+ personaggi) | `kling-o3-standard-reference-to-video` | Fallback automatico con `elements` strutturati per identità multi-personaggio |
| Establishing / mood / action | `seedance-2-0-image-to-video` | Nessun personaggio; qualità cinematica epica, fino a 15s |
Questi sono sovrascrivibili per progetto tramite `series.json → videoDefaults`. Per puntare a una famiglia non Seedance (es. account che non hanno accesso a Seedance), imposta `videoDefaults` su `kling-o3-standard-reference-to-video` e `veo3.1-fast-image-to-video`.
**Regola del volto Seedance:** Seedance 2.0 blocca le immagini di input con volti che non sono state prodotte da `seedream-v5-lite` o `seedream-v5-lite-edit`. L'harness gestisce questo automaticamente instradando il lavoro sulle immagini contenenti personaggi tramite Seedream ed eseguendo un gate pre-flight prima di ogni chiamata Seedance.
## Modelli Venice supportati
### Video (aprile 2026)
| Famiglia | i2v | t2v | Durata massima | Audio | Note |
| - | - | - | - | - | - |
| **Seedance 2.0** | i2v, R2V | t2v | 15s | Sì (stereo, lip-sync 8+ lingue) | Classificato #1. R2V: `reference_image_urls` flat, tag `@Image`. |
| **Kling V3** | Pro, Standard | Pro, Standard | 15s | Sì | `end_image_url` per il targeting del frame |
| **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ì | Fino a risoluzione 4K |
| **Sora 2** | Standard, Pro | Standard, Pro | 12s | Sì | Fino a 1080p |
| **Wan 2.6 / 2.5** | Std, Flash / Sì | Std / Sì | 15s / 10s | Sì | Input `audio_url` |
| **LTX Video 2.0** | Fast, Full, v2.3, 19B | Fast, Full, v2.3, 19B | 20s | Sì | Fino a 4K, il più lungo sincronizzato |
| **Longcat** | Std, Distilled | Std, Distilled | **30s** | No | Il più lungo single-shot |
| **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ì | Supporto wide aspect ratio |
### Immagine, audio e musica
* **Immagine (22+ modelli):** `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 altri
* **Multi-edit:** `qwen-edit`, `flux-2-max-edit`, `nano-banana-pro-edit`, `seedream-v5-lite-edit`, `gpt-image-2-edit` e altri
* **TTS:** `tts-kokoro` (50+ voci), `tts-qwen3-0-6b/1-7b`, `elevenlabs-tts-v3`, `elevenlabs-tts-multilingual-v2`
* **Musica:** `elevenlabs-music`, `minimax-music-v2`, `ace-step-15`, `stable-audio-25`
* **SFX:** `elevenlabs-sound-effects-v2`, `mmaudio-v2-text-to-audio`
## Pipeline di produzione
### Pipeline di generazione
Video narrativo end-to-end (script → storyboard → video → audio → montaggio):
```bash theme={null}
npm run dev -- produce-episode -p output/my-series -e 1
```
L'implementazione di riferimento in `src/mini-drama/` copre:
* Gestione di serie / personaggi / episodi
* Workshop di script con LLM
* Generazione dello storyboard a due passaggi (genera + raffina multi-edit)
* QA dei pannelli basato su vision
* Generazione video con frame chaining
* Post-produzione audio a strati
* Burn-in dei sottotitoli e montaggio finale
### Pipeline di editing
Taglia media già esistenti (riprese generate da Venice o filmati grezzi reali). **Text-first**: l'LLM legge un `takes_packed.md` compatto (\~12KB per 40 minuti di audio) anziché fare un frame-dump del video.
I cinque passi:
whisper.cpp locale produce per ogni sorgente `*.words.json` + `takes_packed.md`.
L'LLM formula una strategia di taglio dal solo testo.
Propone la strategia e attende "yes / revise / cancel".
Cut list JSON → concat ffmpeg con fade audio di 30ms. Archive-first, quindi gli originali non vengono mai sovrascritti.
L'agente `cut-qa` esegue 6 controlli programmatici a ogni transizione di taglio; massimo 3 iterazioni di fix.
I controlli `cut-qa` intercettano regressioni dell'aspect ratio, salti di frame-hash all'interno di una parola, troncamenti VO, discontinuità di illuminazione, picchi audio sopra -6 dBFS e sovrapposizioni di didascalie con testo in-frame.
La pipeline di editing è ispirata da [browser-use/video-use](https://github.com/browser-use/video-use). La loro intuizione di base, *"l'LLM non guarda mai il video, lo legge"*, è ciò che fa funzionare l'editing guidato da agenti senza annegare nei token di frame-dump.
## Comandi, agenti e skill
L'harness espone 19 comandi di workflow, 10 agenti specializzati e 7 skill di produzione. Punti salienti:
| Comando di workflow | Scopo |
| - | - |
| `new-series` | Crea una nuova serie con estetiche bloccate |
| `add-character` / `lock-character` | Lock di personaggio + voce |
| `workshop-episode` | Scripting collaborativo di un episodio |
| `storyboard-episode` | Crea lo storyboard di un episodio |
| `produce-episode` | Pipeline completa in un solo comando |
| `generate-trailer` | Pipeline completa per il trailer |
| `edit-footage` | Pipeline di editing text-first per media esistenti |
| `ingest-screenplay` | Importa una sceneggiatura Fountain o PDF |
| Agente specializzato | Ruolo |
| - | - |
| `art-director` | Decisioni su estetica, palette, illuminazione, composizione |
| `prompt-engineer` | Prompt per immagini Venice, consistenza dei personaggi |
| `storyboard-qa` | QA dei pannelli per controlli di continuity e personaggi |
| `cut-qa` | Quality gate post-render (6 controlli per taglio, max 3 iterazioni) |
| `overlay-designer` | Motion graphics brandizzati, sub-agenti paralleli |
| `trailer-curator` | Selezione delle inquadrature del trailer e regole anti-spoiler |
| Skill di produzione | Scopo |
| - | - |
| `venice-api` | Utilizzo dell'API REST Venice e default |
| `venice-video-model-routing` | Routing R2V-first, decision tree |
| `character-consistency` | Linee guida per consistenza dei personaggi multi-shot |
| `shot-composition` | Linee guida su composizione delle inquadrature e camera |
| `screenplay-parsing` | Workflow di parsing delle sceneggiature |
| `video-editing` | Filosofia editing text-first, formato EDL, loop cut-qa |
## Round-trip NLE
Dopo il rendering, esporta la timeline assemblata come XML per il fine-tuning nel tuo editor preferito. Ogni segmento video, clip di dialogo, clip SFX e cue musicale arriva sulla propria traccia.
```bash theme={null}
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
```
## Utilizzo programmatico
Puoi anche richiamare i moduli dell'harness direttamente dal tuo TypeScript:
```typescript theme={null}
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 });
```
## Risorse
Codice sorgente, issue e release
L'API sottostante che l'harness pilota
Guida R2V per la consistenza dei personaggi
La famiglia video di default dell'harness
Mantenuto dalla community e fornito as-is. Per problemi specifici dell'harness, segnalali sul [repository GitHub del progetto](https://github.com/jordanurbs/venice-video-harness/issues).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.