> ## 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) 是一个由社区维护、agent 优先、Venice 优化的工具包，专为**任意长度的一致性优先视频创作**而设计。它将 IDE agent（Claude Code、Cursor、Codex 等）转变为可复用 Venice 生产系统的操作员，覆盖 50+ 个 Venice 视频、图像、音频和音乐模型。

<Card title="GitHub: venice-video-harness" icon="github" href="https://github.com/jordanurbs/venice-video-harness">
  MIT 许可。社区维护。
</Card>

<CardGroup cols={3}>
  <Card title="角色一致性视频" icon="users">
    在整个系列中锁定角色、声音和美学风格
  </Card>

  <Card title="故事板到视频" icon="film">
    采用 Venice 多重编辑细化的两阶段面板生成
  </Card>

  <Card title="文本优先剪辑" icon="scissors">
    使用 whisper.cpp 在本地转录，从 12KB 包中剪辑，在每个边界自评
  </Card>
</CardGroup>

## 这是什么

大多数 Venice 集成只是 API 调用的薄包装。Venice Video Harness 是位于您的 agent 和 Venice API 之间的**更高层**：

* `CLAUDE.md` 中的**编排规则**
* `.claude/commands/` 中的**可复用 playbook**（19 个工作流命令）
* `.claude/agents/` 中的**专用 agent**（art-director、prompt-engineer、cut-qa 等）
* `.claude/skills/` 中的 **Venice 生产 skill**（与 [Agent Skills](/guides/integrations/venice-skills) 格式兼容）
* `src/` 中的 **TypeScript 执行层**
* **全面的模型注册表**，覆盖 50+ 个 Venice 视频、图像、音频和音乐模型

为生产以下内容的创作者构建：

* 角色一致性视频项目（任何题材、任何长度）
* 视觉风格锁定的系列或活动
* 故事板到视频工作流
* 短视频和长篇叙事内容
* 品牌化电影序列、预告片和宣传片
* 包含循环角色的社交媒体系列

## 入门

### 要求

<CardGroup cols={3}>
  <Card title="Node.js 20+" icon="node-js" href="https://nodejs.org/">
    推荐最新 LTS 版本
  </Card>

  <Card title="ffmpeg + ffprobe" icon="terminal" href="https://ffmpeg.org/">
    位于您的 PATH 中
  </Card>

  <Card title="Venice API 密钥" icon="key" href="/guides/getting-started/generating-api-key">
    来自 [venice.ai/settings/api](https://venice.ai/settings/api)
  </Card>
</CardGroup>

可选，用于编辑流水线：安装 `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
```

### 设置

<Steps>
  <Step title="克隆 harness">
    ```bash theme={"system"}
    git clone https://github.com/jordanurbs/venice-video-harness.git
    cd venice-video-harness
    ```
  </Step>

  <Step title="配置您的 API 密钥">
    ```bash theme={"system"}
    cp .env.example .env
    # Add VENICE_API_KEY to .env
    ```
  </Step>

  <Step title="安装并构建">
    ```bash theme={"system"}
    npm install
    npm run build
    ```
  </Step>

  <Step title="在您的 agent 中打开">
    在 Cursor、Claude Code 或任何支持 agent 聊天的 IDE 中打开项目。agent 会自动读取 `CLAUDE.md` 和 playbook。

    尝试这些首次消息之一：

    * "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"
  </Step>
</Steps>

## 它的 Venice 优化体现在哪里

* **针对 Venice 图像模型调优的图像 prompt**，如 `seedream-v5-lite`、`nano-banana-pro`、`flux-2-pro/max` 等
* **两阶段面板生成**，采用 Venice 多重编辑细化进行角色校正
* **针对动作、氛围和角色一致性层级的模型路由逻辑**
* **参考感知的视频生成**，按模型正确使用 `elements`、`reference_image_urls` 和 `scene_image_urls`
* **环境感知的 prompt 调整**，处理白天 vs 夜晚场景
* **Venice 原生音频路径**用于 TTS（Kokoro、Qwen3、ElevenLabs）、SFX 和音乐
* 通过 `/video/quote` 和 `/audio/quote` 在生成前进行**成本估算**
* **模型感知的参数构建**，自动跳过目标模型不支持的参数

## 模型路由默认值

harness 默认值是有主见的，因为一致性是关键。当前路由（2026 年 4 月）：

**默认 Seedance 2.0 R2V。3+ 角色场景回退到 Kling O3 R2V。建立镜头使用 Seedance 2.0 i2v。**

| 角色            | 默认模型                                   | 使用场景                                                           |
| ------------- | -------------------------------------- | -------------------------------------------------------------- |
| 角色镜头（1-2 个角色） | `seedance-2-0-reference-to-video`      | 默认 R2V，采用扁平 `reference_image_urls`、`@Image` 标签，最长 15 秒，原生立体声音频 |
| 角色镜头（3+ 个角色）  | `kling-o3-standard-reference-to-video` | 自动回退，采用结构化 `elements` 处理多角色身份                                  |
| 建立镜头/氛围/动作    | `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`。

<Note>
  **Seedance 人脸规则：** Seedance 2.0 屏蔽不是由 `seedream-v5-lite` 或 `seedream-v5-lite-edit` 生成的带人脸输入图像。harness 通过将带角色的图像工作路由经 Seedream 处理，并在每次 Seedance 调用之前运行预检门控来自动处理这一点。
</Note>

## 支持的 Venice 模型

### 视频（2026 年 4 月）

| 系列                        | i2v                     | t2v                | 最大时长      | 音频                  | 备注                                                       |
| ------------------------- | ----------------------- | ------------------ | --------- | ------------------- | -------------------------------------------------------- |
| **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，最长同步                                               |
| **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` 等
* **多重编辑：** `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 驱动的脚本工作坊
* 两阶段故事板生成（生成 + 多重编辑细化）
* 基于视觉的面板 QA
* 带帧链接的视频生成
* 分层音频后期制作
* 字幕烧录和最终组装

### 编辑流水线

剪辑已存在的媒体（Venice 生成的镜头或真实原始素材）。**文本优先**：LLM 读取紧凑的 `takes_packed.md`（每 40 分钟音频 \~12KB），而不是逐帧转储视频。

五个步骤：

<Steps>
  <Step title="转录">
    本地 whisper.cpp 生成每个来源的 `*.words.json` + `takes_packed.md`。
  </Step>

  <Step title="读取包">
    LLM 仅从文本形成剪辑策略。
  </Step>

  <Step title="确认">
    提议策略并等待 "yes / revise / cancel"。
  </Step>

  <Step title="渲染 EDL">
    JSON 剪辑列表 → ffmpeg concat，带 30ms 音频淡入淡出。Archive-first，因此原始文件永不会被覆盖。
  </Step>

  <Step title="自评">
    `cut-qa` agent 在每个剪辑边界运行 6 项程序化检查；最多 3 次修复迭代。
  </Step>
</Steps>

`cut-qa` 检查捕捉宽高比回归、单词内的帧哈希跳变、配音截断、光照不连续、超过 -6 dBFS 的音频峰值，以及字幕与画面内文字的重叠。

<Tip>
  编辑流水线的灵感来自 [browser-use/video-use](https://github.com/browser-use/video-use)。他们的核心见解，*"LLM 永远不看视频，它阅读视频"*，是 agent 驱动的编辑在不被帧转储 token 淹没的情况下工作的关键。
</Tip>

## 命令、Agent 和 Skill

harness 公开 19 个工作流命令、10 个专用 agent 和 7 个生产 skill。亮点：

| 工作流命令                              | 用途                   |
| ---------------------------------- | -------------------- |
| `new-series`                       | 创建带锁定美学的新系列          |
| `add-character` / `lock-character` | 角色 + 声音锁定            |
| `workshop-episode`                 | 协作集脚本编写              |
| `storyboard-episode`               | 为一集编写故事板             |
| `produce-episode`                  | 一条命令完成完整流水线          |
| `generate-trailer`                 | 完整预告片流水线             |
| `edit-footage`                     | 现有媒体的文本优先编辑流水线       |
| `ingest-screenplay`                | 摄取 Fountain 或 PDF 剧本 |

| 专用 Agent           | 角色                          |
| ------------------ | --------------------------- |
| `art-director`     | 美学、调色板、光照、构图决策              |
| `prompt-engineer`  | Venice 图像 prompt、角色一致性      |
| `storyboard-qa`    | 面板 QA，检查连贯性和角色              |
| `cut-qa`           | 渲染后质量门（每个剪辑 6 项检查，最多 3 次迭代） |
| `overlay-designer` | 品牌化动态图形，并行子 agent           |
| `trailer-curator`  | 预告片镜头选择和反剧透规则               |

| 生产 Skill                     | 用途                        |
| ---------------------------- | ------------------------- |
| `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/<project> -e 1 --format fcpxml      # Final Cut Pro X
mini-drama export-timeline -p output/<project> -e 1 --format premiere    # Premiere Pro
mini-drama export-timeline -p output/<project> -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 });
```

## 资源

<CardGroup cols={2}>
  <Card title="GitHub" icon="github" href="https://github.com/jordanurbs/venice-video-harness">
    源代码、issue 和发布
  </Card>

  <Card title="Venice 视频生成" icon="film" href="/guides/media/video-generation">
    harness 所驱动的底层 API
  </Card>

  <Card title="参考到视频" icon="image" href="/guides/media/reference-to-video">
    用于角色一致性的 R2V 指南
  </Card>

  <Card title="Seedance 2.0" icon="bolt" href="/guides/media/seedance-2-0">
    harness 默认的视频系列
  </Card>
</CardGroup>

<Note>
  社区维护，按现状提供。对于 harness 特定问题，请在[项目的 GitHub 仓库](https://github.com/jordanurbs/venice-video-harness/issues)上提交。
</Note>