> ## 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
> Claude Code 또는 Cursor에서 Venice를 구동하는 Venice 최적화 harness로 캐릭터 일관성 있는 비디오, 스토리보드, 예고편, 장편 내러티브를 제작하세요.
[Venice Video Harness](https://github.com/jordanurbs/venice-video-harness)는 **모든 길이에서 일관성 우선 비디오 제작**을 위한 커뮤니티의 에이전트 우선, Venice 최적화 툴킷입니다. IDE 에이전트(Claude Code, Cursor, Codex 등)를 50개 이상의 Venice 비디오, 이미지, 오디오, 음악 모델을 아우르는 재사용 가능한 Venice 프로덕션 시스템의 운영자로 변환합니다.
MIT 라이선스. 커뮤니티에서 유지보수합니다.
시리즈 전체에서 캐릭터, 음성, 미학을 고정
Venice multi-edit 리파인이 들어간 2패스 패널 생성
whisper.cpp로 로컬 전사, 12KB 팩에서 컷, 모든 경계에서 자가 평가
## 이것은 무엇인가요
대부분의 Venice 통합은 API 호출의 얇은 래퍼입니다. Venice Video Harness는 에이전트와 Venice API 사이에 있는 **상위 레벨 레이어**입니다:
* `CLAUDE.md`의 **오케스트레이션 규칙**
* `.claude/commands/`의 **재사용 가능한 플레이북**(19개의 워크플로 명령)
* `.claude/agents/`의 **전문 에이전트**(art-director, prompt-engineer, cut-qa 등)
* `.claude/skills/`의 **Venice 프로덕션 스킬**([Agent Skills](/guides/integrations/venice-skills) 포맷과 호환)
* `src/`의 **TypeScript 실행 레이어**
* 50개 이상의 Venice 비디오, 이미지, 오디오, 음악 모델을 다루는 **포괄적 모델 레지스트리**
다음 제작자를 위해 설계되었습니다:
* 캐릭터 일관성이 있는 비디오 프로젝트(장르 무관, 길이 무관)
* 비주얼 스타일이 고정된 시리즈 또는 캠페인
* 스토리보드→비디오 워크플로
* 숏폼 및 롱폼 내러티브 콘텐츠
* 브랜드 시네마틱 시퀀스, 트레일러, 티저
* 반복 등장 캐릭터의 소셜 시리즈
## 시작하기
### 요구사항
최신 LTS 권장
PATH에 등록
[venice.ai/settings/api](https://venice.ai/settings/api)에서 발급
편집 파이프라인용 선택 사항: 로컬 전사를 위한 `whisper-cpp` 설치.
```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
```
### 설정
```bash theme={"system"}
git clone https://github.com/jordanurbs/venice-video-harness.git
cd venice-video-harness
```
```bash theme={"system"}
cp .env.example .env
# .env에 VENICE_API_KEY 추가
```
```bash theme={"system"}
npm install
npm run build
```
Cursor, Claude Code 등 에이전트 채팅이 있는 IDE에서 프로젝트를 여세요. 에이전트는 `CLAUDE.md`와 플레이북을 자동으로 읽습니다.
다음 중 하나의 첫 메시지를 시도해 보세요:
* "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"
## 무엇이 Venice에 최적화되어 있나요
* `seedream-v5-lite`, `nano-banana-pro`, `flux-2-pro/max` 등 **Venice 이미지 모델용으로 튜닝된 이미지 prompt**
* 캐릭터 보정을 위한 Venice multi-edit 리파인이 포함된 **2패스 패널 생성**
* 액션, 분위기, 캐릭터 일관성 등급을 위한 **모델 라우팅 로직**
* 모델별로 `elements`, `reference_image_urls`, `scene_image_urls`를 올바르게 사용하는 **레퍼런스 인식 비디오 생성**
* 낮 대 밤 장면 처리를 위한 **환경 인식 prompt 적응**
* TTS(Kokoro, Qwen3, ElevenLabs), SFX, 음악을 위한 **Venice 네이티브 오디오 경로**
* `/video/quote`와 `/audio/quote`를 통한 **생성 전 비용 추정**
* 타겟 모델이 지원하지 않는 파라미터를 자동으로 건너뛰는 **모델 인식 파라미터 빌더**
## 모델 라우팅 기본값
일관성이 핵심이기 때문에 harness 기본값은 의도적입니다. 현재 라우팅(2026년 4월):
**기본은 Seedance 2.0 R2V. 캐릭터 3명 이상 장면에는 Kling O3 R2V fallback. 설정 샷에는 Seedance 2.0 i2v.**
| Role | Default model | When used |
| -------------- | -------------------------------------- | --------------------------------------------------------------------- |
| 캐릭터 샷(1-2 캐릭터) | `seedance-2-0-reference-to-video` | 평면 `reference_image_urls`, `@Image` 태그, 최대 15초, 네이티브 스테레오 오디오의 기본 R2V |
| 캐릭터 샷(3+ 캐릭터) | `kling-o3-standard-reference-to-video` | 멀티 캐릭터 정체성을 위해 구조화된 `elements`로 자동 fallback |
| 설정 / 분위기 / 액션 | `seedance-2-0-image-to-video` | 캐릭터 없음. 서사적 시네마틱 품질, 최대 15초 |
이 기본값은 `series.json → videoDefaults`로 프로젝트별로 덮어쓸 수 있습니다. Seedance가 아닌 패밀리(예: Seedance 접근 권한이 없는 계정)를 타겟팅하려면 `videoDefaults`를 `kling-o3-standard-reference-to-video`와 `veo3.1-fast-image-to-video`로 설정하세요.
**Seedance 얼굴 규칙:** Seedance 2.0은 `seedream-v5-lite`나 `seedream-v5-lite-edit`에서 생성되지 않은 얼굴이 포함된 입력 이미지를 차단합니다. Harness는 캐릭터가 포함된 이미지 작업을 Seedream으로 라우팅하고, 모든 Seedance 호출 전에 사전 게이트를 실행해 이를 자동 처리합니다.
## 지원되는 Venice 모델
### 비디오 (2026년 4월)
| Family | i2v | t2v | Max duration | Audio | Notes |
| ------------------------- | -------------------------- | --------------------- | ------------ | ---------------------- | ----------------------------------------------------------- |
| **Seedance 2.0** | i2v, R2V | t2v | 15s | 예 (스테레오, 립싱크 8개 이상 언어) | #1 랭크. R2V: 평면 `reference_image_urls`, `@Image` 태그. |
| **Kling V3** | Pro, Standard | Pro, Standard | 15s | 예 | 프레임 타겟팅용 `end_image_url` |
| **Kling O3** | Pro, Std, Pro R2V, Std R2V | Pro, Standard | 15s | 예 | R2V: `elements`, `reference_image_urls`, `scene_image_urls` |
| **Kling 2.6 / 2.5 Turbo** | Pro | Pro | 10s | 2.6: 예 / 2.5: 아니오 | `end_image_url` |
| **Veo 3.1** | Fast, Full | Fast, Full | 8s | 예 | 최대 4K 해상도 |
| **Sora 2** | Standard, Pro | Standard, Pro | 12s | 예 | 최대 1080p |
| **Wan 2.6 / 2.5** | Std, Flash / 예 | Std / 예 | 15s / 10s | 예 | `audio_url` 입력 |
| **LTX Video 2.0** | Fast, Full, v2.3, 19B | Fast, Full, v2.3, 19B | 20s | 예 | 최대 4K, 가장 긴 sync 가능 |
| **Longcat** | Std, Distilled | Std, Distilled | **30s** | 아니오 | 가장 긴 단일 샷 |
| **Vidu Q3** | 예 | 예 | 16s | 예 | `reference_image_urls` |
| **PixVerse v5.6** | Std, Transition | Standard | 8s | 예 | Transition: `end_image_url` |
| **Grok Imagine** | 예 | 예 | 15s | 예 | 넓은 종횡비 지원 |
### 이미지, 오디오, 음악
* **이미지(22개 이상 모델):** `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` 등
* **Multi-edit:** `qwen-edit`, `flux-2-max-edit`, `nano-banana-pro-edit`, `seedream-v5-lite-edit`, `gpt-image-2-edit` 등
* **TTS:** `tts-kokoro`(50개 이상 음성), `tts-qwen3-0-6b/1-7b`, `elevenlabs-tts-v3`, `elevenlabs-tts-multilingual-v2`
* **음악:** `elevenlabs-music`, `minimax-music-v2`, `ace-step-15`, `stable-audio-25`
* **SFX:** `elevenlabs-sound-effects-v2`, `mmaudio-v2-text-to-audio`
## 프로덕션 파이프라인
### 생성 파이프라인
엔드 투 엔드 내러티브 비디오(스크립트 → 스토리보드 → 비디오 → 오디오 → 어셈블리):
```bash theme={"system"}
npm run dev -- produce-episode -p output/my-series -e 1
```
`src/mini-drama/`의 레퍼런스 구현은 다음을 다룹니다:
* 시리즈 / 캐릭터 / 에피소드 관리
* LLM 기반 스크립트 워크숍
* 2패스 스토리보드 생성(생성 + multi-edit 리파인)
* 비전 기반 패널 QA
* 프레임 체이닝이 있는 비디오 생성
* 레이어드 오디오 포스트 프로덕션
* 자막 번인과 최종 어셈블리
### 편집 파이프라인
이미 존재하는 미디어(Venice가 만든 샷이나 실제 원본 영상)를 컷합니다. **텍스트 우선**: LLM은 비디오를 프레임 덤프하지 않고 컴팩트한 `takes_packed.md`(40분 오디오당 약 12KB)를 읽습니다.
다섯 단계:
로컬 whisper.cpp가 소스별 `*.words.json` + `takes_packed.md`를 생성합니다.
LLM이 텍스트만으로 컷 전략을 수립합니다.
전략을 제안하고 "yes / revise / cancel"을 기다립니다.
JSON 컷 목록 → 30ms 오디오 페이드가 있는 ffmpeg concat. 아카이브 우선이라 원본은 절대 덮어쓰지 않습니다.
`cut-qa` 에이전트가 모든 컷 경계에서 6개의 프로그램적 검사를 실행. 최대 3회 수정 반복.
`cut-qa` 검사는 종횡비 회귀, 단어 내부의 프레임 해시 점프, VO 잘림, 조명 불연속, -6 dBFS 초과 오디오 피크, 화면 내 텍스트와 자막 겹침을 잡아냅니다.
편집 파이프라인은 [browser-use/video-use](https://github.com/browser-use/video-use)에서 영감을 받았습니다. \*"LLM은 비디오를 보지 않고 읽는다"\*는 그들의 핵심 통찰이 프레임 덤프 토큰에 빠지지 않고 에이전트 기반 편집이 동작하게 만드는 비결입니다.
## 명령, 에이전트, 스킬
Harness는 19개의 워크플로 명령, 10개의 전문 에이전트, 7개의 프로덕션 스킬을 노출합니다. 주요 항목:
| Workflow command | Purpose |
| ---------------------------------- | --------------------------- |
| `new-series` | 미학이 고정된 새 시리즈 생성 |
| `add-character` / `lock-character` | 캐릭터 + 음성 고정 |
| `workshop-episode` | 협업적 에피소드 스크립팅 |
| `storyboard-episode` | 한 에피소드 스토리보드 |
| `produce-episode` | 단일 명령으로 전체 파이프라인 |
| `generate-trailer` | 전체 트레일러 파이프라인 |
| `edit-footage` | 기존 미디어용 텍스트 우선 편집 파이프라인 |
| `ingest-screenplay` | Fountain 또는 PDF 시나리오 ingest |
| Specialized agent | Role |
| ------------------ | ------------------------------- |
| `art-director` | 미학, 팔레트, 조명, 구도 결정 |
| `prompt-engineer` | Venice 이미지 prompt, 캐릭터 일관성 |
| `storyboard-qa` | 연속성과 캐릭터 검사를 위한 패널 QA |
| `cut-qa` | 렌더 후 품질 게이트(컷당 6개 검사, 최대 3회 반복) |
| `overlay-designer` | 브랜드 모션 그래픽, 병렬 서브 에이전트 |
| `trailer-curator` | 트레일러 샷 선택과 스포일러 방지 규칙 |
| Production skill | Purpose |
| ---------------------------- | ------------------------------- |
| `venice-api` | Venice REST API 사용법과 기본값 |
| `venice-video-model-routing` | R2V 우선 라우팅, 결정 트리 |
| `character-consistency` | 멀티 샷 캐릭터 일관성 안내 |
| `shot-composition` | 샷 구도와 카메라 안내 |
| `screenplay-parsing` | 시나리오 파싱 워크플로 |
| `video-editing` | 텍스트 우선 편집 철학, EDL 포맷, cut-qa 루프 |
## NLE 라운드 트립
렌더 후 어셈블된 타임라인을 XML로 내보내 원하는 편집기에서 미세 조정할 수 있습니다. 모든 비디오 세그먼트, 다이얼로그 클립, SFX 클립, 음악 큐가 자체 트랙에 배치됩니다.
```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
```
## 프로그래밍 방식 사용
자체 TypeScript에서 harness의 모듈을 직접 호출할 수도 있습니다:
```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 });
```
## 리소스
소스 코드, 이슈, 릴리스
Harness가 구동하는 기반 API
캐릭터 일관성을 위한 R2V 가이드
Harness의 기본 비디오 패밀리
커뮤니티에서 유지보수하며 있는 그대로 제공됩니다. Harness 관련 이슈는 [프로젝트 GitHub 레포](https://github.com/jordanurbs/venice-video-harness/issues)에 등록해 주세요.