> ## 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.

# 参考到视频（Reference to Video）

> 在 Venice API 上使用 Kling O3 和 Grok Imagine R2V 模型，通过角色元素、场景参考和多镜头控制生成一致的 AI 视频。

参考到视频（Reference to Video）让您可以锁定角色、对象和场景的外观，使您的 AI 生成视频保持视觉一致性。您不再寄希望于模型正确解读您的 prompt，而是提供视觉锚点——告诉模型主体确切外观的参考图像。

此功能在 [Venice Video Studio](https://venice.ai/video) 中的 **Kling O3** 和 **Grok Imagine R2V** 模型上可用。每个模型系列对参考图像使用不同的方法——请参阅下面的模型特定章节。

## 何时使用 Reference to Video

在以下情况下使用 Reference to Video：

* **角色一致性** — 跨多个镜头的同一个人物或角色
* **产品准确性** — 必须与原物外观完全相同的真实产品
* **场景连续性** — 跨生成的特定环境或背景
* **多角色场景** — 多个不同角色互动而不混合

对于一致性不关键的简单 text-to-video 或 image-to-video，标准模型在没有参考的情况下也能很好地工作。

## 可用模型

| 模型                        | 方法              | 最适合                 |
| ------------------------- | --------------- | ------------------- |
| **Kling O3 Pro R2V**      | Elements + 场景图像 | 需要精确身份控制的复杂多角色场景    |
| **Kling O3 Standard R2V** | Elements + 场景图像 | 基于元素场景的更快迭代         |
| **Grok Imagine R2V**      | 扁平参考图像          | 使用最多 7 张图像的快速参考驱动生成 |

**Kling O3** 使用结构化方法，包括 Elements（带正面 + 参考图像的角色身份锚点）和场景图像。**Grok Imagine R2V** 采用更简单的方法——您直接上传参考图像并在 prompt 中用 `@Image1`、`@Image2` 等引用它们。

***

## Kling O3 Reference to Video

### 核心概念

Kling O3 Reference to Video 使用三种类型的视觉输入协同工作：

| 输入           | 必需         | 用途         | 如何在 prompt 中引用            |
| ------------ | ---------- | ---------- | ------------------------- |
| **Elements** | 至少一个视觉输入\* | 锁定角色或对象的身份 | `@Element1`、`@Element2` 等 |
| **场景参考图像**   | 至少一个视觉输入\* | 设置环境、风格和氛围 | `@Image1`、`@Image2` 等     |
| **起始帧**      | 至少一个视觉输入\* | 控制视频的第一帧   | N/A（通过上传设置）               |
| **结束帧**      | 否          | 控制视频的最后一帧  | N/A（通过上传设置）               |

\*至少需要以下之一：起始帧、elements 或场景参考图像。

### Elements

Element 是您希望在整个视频中保持视觉稳定的角色或对象。每个 element 包含：

* **正面图像**（每个 element 必需） — 主体的清晰正面照片。这是主要的身份锚点。可以将其视为您角色或产品的"护照照片"。
* **参考图像**（1–3 张，可选） — 同一主体的其他角度（侧视图、45 度角、背面）。这些有助于模型在 3D 空间中理解主体。如果未提供，正面图像将自动用作参考。

每次生成最多可添加 **7 个 element**（受合计总数限制）。在 prompt 中使用 `@Element1`、`@Element2` 等引用它们。

### 场景参考图像

场景参考定义动作发生的"舞台"。它们影响：

* 光照和调色板
* 建筑和环境细节
* 整体视觉风格和氛围

您最多可以添加 **4 张场景图像**。在 prompt 中以 `@Image1`、`@Image2` 等方式引用它们。

### 限制

所有输入类型的图像总数受到限制：

| 限制                                     | 值                             |
| -------------------------------------- | ----------------------------- |
| **最低要求**                               | 至少 1 个视觉输入（起始帧、element 或场景图像） |
| **合计总数**（第一帧 + 最后一帧 + elements + 场景图像） | **最多 7 个**                    |
| Elements（无起始/结束帧）                      | 最多 7 个                        |
| Elements（有起始或结束帧）                      | 最多 3 个                        |
| 场景参考图像                                 | 最多 4 张                        |
| 每个 element 的参考图像                       | 1–3 张                         |

**示例场景：**

* 7 个 elements + 0 张场景图像 = 7 ✓（无帧）
* 5 个 elements + 2 张场景图像 = 7 ✓（无帧）
* 第一帧 (1) + 3 个 elements + 3 张场景图像 = 7 ✓
* 第一帧 (1) + 最后一帧 (1) + 3 个 elements + 2 张场景图像 = 7 ✓
* 第一帧 (1) + 4 个 elements = ✗（带帧时最多 3 个 elements）
* 第一帧 (1) + 最后一帧 (1) + 4 个 elements = ✗（带帧时最多 3 个 elements）

<Note>
  每个 element 都需要**正面图像**。如果您不为 element 提供参考图像，正面图像将自动用作参考。
</Note>

### 多镜头模式

多镜头让您将单次生成拆分为多个场景，每个场景都有自己的 prompt 和时长。Elements 和场景参考跨所有镜头保留，保持一致性。所有镜头的总时长不能超过 **15 秒**。

***

### 分步指南（Video Studio）

#### 1. 打开 Video Studio 并选择模型

前往 [venice.ai/video](https://venice.ai/video)。在左侧的 Model Browser 中，选择 **Kling O3 Reference to Video** 模型之一：

* **Kling O3 Pro R2V** — 更高质量，生成时间更长（\~6 分钟）
* **Kling O3 Standard R2V** — 更快，更经济，适合迭代

#### 2. 添加视觉输入（至少需要一个）

您必须提供**至少一个视觉输入**才能生成视频：起始帧、element 或场景参考图像。在输入面板中，您将看到 **Elements** 部分。点击 **Add Element** 为您希望保持视觉一致的角色或对象创建 element。

对于每个 element：

1. 点击 **Frontal** 图块上传您的角色或对象的清晰正面图像
2. 可选地点击 **Reference Images** 下的 **Add** 上传额外角度（1–3 张）

为其他角色或对象重复操作（总共最多 7 个 elements，使用起始/结束帧时最多 3 个）。

<Warning>
  第一帧、最后一帧、elements 和场景图像的合计总数不能超过 **7**。详情请参阅 [限制](#limitations)。
</Warning>

<Tip>
  **最佳参考图像：** 使用光线良好、背景干净的照片。提供正面、侧面和 45 度角视图以获得最强的身份锁定。确保所有参考图像共享相同的视觉风格（不要混合写实和动漫）。
</Tip>

#### 3. 添加场景参考图像（可选）

在 Elements 部分下方，您将看到 **Scene Reference Images**。上传定义您想要的环境的图像——特定位置、光照设置或艺术风格。

这些自动标记为 `@Image1`、`@Image2` 等。

#### 4. 上传起始帧（可选）

如果您想精确控制视频的第一帧，切换到 **Image** 输入类型并上传起始帧。您还可以选择性地设置结束帧。

#### 5. 编写您的 prompt

在 prompt 字段中，描述您想要的动作，同时使用 `@` 标签引用您的 elements 和场景图像：

```
@Element1 walks through the streets of @Image1, looking up at the buildings.
The camera slowly tracks from behind, revealing the city skyline.
```

对于**多角色场景**：

```
@Element1 and @Element2 enter the cafe in @Image1 from opposite sides.
@Element1 waves and walks toward @Element2, who is sitting at a corner table.
```

#### 6. 配置设置

打开 **Video Settings** 调整：

| 设置   | 选项            | 默认值  |
| ---- | ------------- | ---- |
| 时长   | 3s – 15s      | 5s   |
| 宽高比  | 16:9、9:16、1:1 | 16:9 |
| 生成音频 | 开/关           | 关    |

<Note>
  音频生成添加与视频同步的原生音效、对话和环境音频。它会使成本增加约 25%。
</Note>

#### 7. 生成

点击 **Generate Video**。Kling O3 通常需要 4–6 分钟，具体取决于模型层级和时长。您可以排队多个生成并在 Video Gallery 中浏览结果。

***

### 多镜头故事板

对于叙事序列，使用多镜头模式在单次生成中定义独立的场景。

1. 在 prompt 区域，点击 **Add Shot** 创建额外的镜头
2. 为每个镜头编写单独的 prompt
3. 为每个镜头设置时长（每个 3–15s，总计 ≤ 15s）

Elements 和场景参考自动跨所有镜头持续：

```
Shot 1 (5s): @Element1 stands at the edge of @Image1, looking out at the horizon.
Slow camera push forward.

Shot 2 (5s): Close-up of @Element1's face as they turn toward the camera.
Soft natural lighting, shallow depth of field.

Shot 3 (5s): @Element1 walks away from camera into the distance.
Wide cinematic shot, golden hour lighting.
```

<Warning>
  多镜头总时长不能超过 15 秒。例如，三个 5 秒镜头 = 15s 最大值。
</Warning>

***

### Prompt 技巧

#### 构建您的 prompt

按照此模式获得可靠结果：

```
[带 @Element 标签的主体] + [动作] + [带 @Image 标签的环境] + [摄影机运动] + [光照/风格]
```

**示例：**

```
@Element1 hops happily across the candy ground of @Image1, stops to look at a
giant lollipop, tilts its head curiously. Cinematic tracking shot, soft warm lighting.
```

#### 保持 prompt 在 50–150 字之间

较短的 prompt 缺少细节。较长的 prompt 会引入矛盾。瞄准甜蜜点。

#### 使用简单的摄影机语言

模型对简单的摄影机指令响应最好：

| 使用                          | 避免                                              |
| --------------------------- | ----------------------------------------------- |
| `slow camera push forward`  | `dolly zoom with rack focus transition`         |
| `tracking shot from behind` | `complex handheld parallax movement`            |
| `close-up`                  | `extreme macro with tilt-shift bokeh`           |
| `wide cinematic shot`       | `anamorphic ultra-wide establishing crane shot` |

#### 使用一致的词汇

如果您在一个 prompt 中描述角色穿着"a red jacket"，请勿在下一个 prompt 中切换为"crimson coat"。模型将不同的词视为不同的意图。

#### 将摄影机指令放在前面

将摄影机指令放在 prompt 开头附近以获得更可靠的结果：

```
Cinematic tracking shot of @Element1 walking through @Image1, leaves
blowing in the wind, golden afternoon light.
```

***

### Kling O3 定价

Kling O3 Reference to Video 模型使用基于时长的定价：

| 模型                    | 每秒（无音频） | 每秒（带音频） |
| --------------------- | ------- | ------- |
| Kling O3 Pro R2V      | \$0.112 | \$0.140 |
| Kling O3 Standard R2V | \$0.112 | \$0.140 |

**示例：** 一段 10 秒带音频的视频 = 10 × $0.14 = **$1.40\*\*

生成前使用 [Video Quote API](https://docs.venice.ai/api-reference/endpoint/video/quote) 获取精确定价。

***

### Kling O3 API 用法

Kling O3 Reference to Video 也通过 Venice API 可用。完整详情请参阅 [Video Queue API](https://docs.venice.ai/api-reference/endpoint/video/queue)。

#### Python

```python theme={"system"}
import requests

response = requests.post(
    "https://api.venice.ai/api/v1/video/queue",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "kling-o3-pro-reference-to-video",
        "prompt": "@Element1 walks through @Image1, camera tracking from behind",
        "duration": "8",
        "aspect_ratio": "16:9",
        "audio": True,
        "elements": [
            {
                "frontal_image_url": "https://example.com/character-front.jpg",
                "reference_image_urls": [
                    "https://example.com/character-side.jpg",
                    "https://example.com/character-angle.jpg"
                ]
            }
        ],
        "image_urls": [
            "https://example.com/scene-background.jpg"
        ]
    }
)

queue_id = response.json()["id"]
```

#### Node.js

```javascript theme={"system"}
const response = await fetch("https://api.venice.ai/api/v1/video/queue", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "kling-o3-pro-reference-to-video",
    prompt: "@Element1 walks through @Image1, camera tracking from behind",
    duration: "8",
    aspect_ratio: "16:9",
    audio: true,
    elements: [
      {
        frontal_image_url: "https://example.com/character-front.jpg",
        reference_image_urls: [
          "https://example.com/character-side.jpg",
          "https://example.com/character-angle.jpg"
        ]
      }
    ],
    image_urls: [
      "https://example.com/scene-background.jpg"
    ]
  })
});

const { id: queueId } = await response.json();
```

#### cURL

```bash theme={"system"}
curl https://api.venice.ai/api/v1/video/queue \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-o3-pro-reference-to-video",
    "prompt": "@Element1 walks through @Image1, camera tracking from behind",
    "duration": "8",
    "aspect_ratio": "16:9",
    "audio": true,
    "elements": [
      {
        "frontal_image_url": "https://example.com/character-front.jpg",
        "reference_image_urls": [
          "https://example.com/character-side.jpg",
          "https://example.com/character-angle.jpg"
        ]
      }
    ],
    "image_urls": [
      "https://example.com/scene-background.jpg"
    ]
  }'
```

#### Element 模式

`elements` 数组中的每个 element 接受：

| 字段                     | 类型        | 必需    | 说明                              |
| ---------------------- | --------- | ----- | ------------------------------- |
| `frontal_image_url`    | string    | **是** | 清晰的正面图像 URL                     |
| `reference_image_urls` | string\[] | 否     | 其他角度 URL（1–3 张）。如果省略，正面图像将用作参考。 |

<Note>
  API 还支持基于视频的 element 的 `video_url`，但目前在 Video Studio UI 中不可用。
</Note>

***

### Kling O3 故障排查

| 问题                                      | 可能原因            | 解决方案                                                     |
| --------------------------------------- | --------------- | -------------------------------------------------------- |
| Generate 按钮被禁用                          | 未提供视觉输入         | 添加至少一个视觉输入：起始帧、element 或场景参考图像                           |
| "Number of images exceeds the limit" 错误 | 合计输入过多          | 第一帧 + 最后一帧 + elements + 场景图像的总数必须 ≤ 7                    |
| 角色面部在镜头之间变化                             | 不同或缺少正面图像       | 一致地使用相同的正面图像，保持描述相同                                      |
| 摄影机运动感觉随机                               | 多个或冲突的摄影机指令     | 使用单个摄影机指令，将其放在 prompt 早期                                 |
| 生成之间风格变化                                | 场景参考不一致或混合风格    | 复用相同的场景图像，保持风格关键词一致                                      |
| 多角色场景中元素混合                              | 模糊的空间指令         | 明确每个 element 的位置："foreground left"、"entering from right" |
| 背景看起来扭曲                                 | 杂乱或复杂的场景参考图像    | 使用干净、高质量的场景参考图像                                          |
| 运动看起来不自然                                | 一个 prompt 中动作过多 | 简化动作，使用较短时长，每个镜头一个动作                                     |

<Tip>
  在投入更长时长之前，使用 3–5 秒的剪辑进行测试。较短的剪辑保持更好的一致性，让您更快迭代。
</Tip>

***

## Grok Imagine Reference to Video

Grok Imagine R2V 采用比 Kling O3 更简单的方法。它不是带有正面/参考图像分离的结构化 Elements，而是上传**扁平参考图像**并使用 `@Image1`、`@Image2` 等在 prompt 中直接引用它们。模型将这些主体整合到生成的视频中。

### 工作原理

1. 上传 **1–7 张参考图像** — 您希望在视频中出现的角色、对象或场景的照片
2. 编写描述视频的 prompt，使用 `@Image1`、`@Image2` 等引用特定图像
3. 模型生成融入这些参考的视频

如果您不在 prompt 中包含 `@Image` 标签，所有上传的图像都会自动被引用。

### 设置

| 设置  | 选项                            | 默认值  |
| --- | ----------------------------- | ---- |
| 宽高比 | 16:9、4:3、3:2、1:1、2:3、3:4、9:16 | 16:9 |
| 分辨率 | 480p、720p                     | 480p |
| 时长  | 5s、8s、10s                     | 8s   |

<Note>
  Grok Imagine R2V 不支持音频生成、多镜头模式或 Elements。要使用这些功能，请使用 Kling O3 R2V。
</Note>

### 分步指南（Video Studio）

#### 1. 选择模型

前往 [venice.ai/video](https://venice.ai/video)。在 Model Browser 中，选择 **Grok Imagine R2V**。

#### 2. 上传参考图像

点击输入工具栏中的 **References**（或使用 + 菜单）打开参考图像面板。上传 1–7 张您希望在视频中出现的角色、对象或场景图像。

每张图像按您上传的顺序（从左到右）自动标记为 `@Image1`、`@Image2` 等。

#### 3. 编写您的 prompt

描述您想要的视频。使用 `@Image` 标签引用特定图像：

```
@Image1 and @Image2 walking together through a sunlit park,
camera slowly tracking alongside them, warm afternoon light.
```

在 prompt 字段中输入 `@` 可查看可用图像引用的自动完成菜单。

<Tip>
  如果您完全省略 `@Image` 标签，后端会自动预添加对所有上传图像的引用。当您希望使用所有图像但不指定哪个是哪个时，这非常有用。
</Tip>

#### 4. 配置设置并生成

打开 **Video Settings** 调整宽高比、分辨率和时长。点击 **Generate Video**。

### Grok Imagine R2V 定价

Grok Imagine R2V 使用基于时长和分辨率的定价：

| 分辨率  | 每秒        |
| ---- | --------- |
| 480p | \~\$0.063 |
| 720p | \~\$0.088 |

**示例：** 8 秒 480p 视频 = 8 × $0.063 = **~$0.50\*\*

<Note>
  Grok Imagine 对生成的视频收取内容审核费，即使视频被拒绝也是如此。这反映在生成前显示的 credit 成本中。
</Note>

### Grok Imagine R2V API 用法

#### Python

```python theme={"system"}
import requests

response = requests.post(
    "https://api.venice.ai/api/v1/video/queue",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "grok-imagine-reference-to-video",
        "prompt": "@Image1 and @Image2 walking through a park, cinematic tracking shot",
        "duration": "8",
        "aspect_ratio": "16:9",
        "referenceImageUrls": [
            "https://example.com/character-a.jpg",
            "https://example.com/character-b.jpg"
        ]
    }
)

queue_id = response.json()["id"]
```

#### Node.js

```javascript theme={"system"}
const response = await fetch("https://api.venice.ai/api/v1/video/queue", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "grok-imagine-reference-to-video",
    prompt: "@Image1 and @Image2 walking through a park, cinematic tracking shot",
    duration: "8",
    aspect_ratio: "16:9",
    referenceImageUrls: [
      "https://example.com/character-a.jpg",
      "https://example.com/character-b.jpg"
    ]
  })
});

const { id: queueId } = await response.json();
```

#### cURL

```bash theme={"system"}
curl https://api.venice.ai/api/v1/video/queue \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-reference-to-video",
    "prompt": "@Image1 and @Image2 walking through a park, cinematic tracking shot",
    "duration": "8",
    "aspect_ratio": "16:9",
    "referenceImageUrls": [
      "https://example.com/character-a.jpg",
      "https://example.com/character-b.jpg"
    ]
  }'
```

#### API 参数

| 字段                   | 类型        | 必需    | 说明                                    |
| -------------------- | --------- | ----- | ------------------------------------- |
| `model`              | string    | **是** | 必须为 `grok-imagine-reference-to-video` |
| `prompt`             | string    | **是** | 带可选 `@Image1`、`@Image2` 引用的文本 prompt  |
| `referenceImageUrls` | string\[] | **是** | 1–7 个图像 URL 或 data URL                |
| `duration`           | string    | 否     | `"5"`、`"8"`（默认）或 `"10"`               |
| `aspect_ratio`       | string    | 否     | 例如 `"16:9"`（默认）、`"9:16"`、`"1:1"`      |
| `resolution`         | string    | 否     | `"480p"`（默认）或 `"720p"`                |

<Note>
  Grok Imagine R2V 不使用 `elements`、`image_urls` 或 `imageUrl` 字段。所有参考图像通过 `referenceImageUrls` 传递。
</Note>

### Grok Imagine R2V 故障排查

| 问题                                            | 可能原因                       | 解决方案                                        |
| --------------------------------------------- | -------------------------- | ------------------------------------------- |
| Generate 按钮被禁用                                | 未上传参考图像                    | 上传至少 1 张参考图像                                |
| "At least one reference image is required" 错误 | `referenceImageUrls` 为空或缺失 | 在 `referenceImageUrls` 中提供至少一个图像 URL        |
| 错误的图像与 `@Image` 标签关联                          | 图像顺序与标签不匹配                 | `@Image1` 对应于您上传顺序中的第一张图像（从左到右）。如有需要重新排序上传。 |
| 主体未出现在视频中                                     | 没有显式标签的引用过多                | 在 prompt 中使用 `@Image` 标签明确指定要使用的图像          |
| 低质量输出                                         | 使用 480p 分辨率                | 尝试 720p 获得更高质量（成本更高）                        |
| 视频过短                                          | 默认时长为 8s                   | 将时长设置为 `"10"` 以获得更长的视频                      |