Reference to Video Guide | Venice API Docs

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

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

多镜头模式

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

分步指南（Video Studio）

1. 打开 Video Studio 并选择模型

前往 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：

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

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

第一帧、最后一帧、elements 和场景图像的合计总数不能超过 7。详情请参阅限制。

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

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
生成音频	开/关	关

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

7. 生成

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

多镜头故事板

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

在 prompt 区域，点击 Add Shot 创建额外的镜头
为每个镜头编写单独的 prompt
为每个镜头设置时长（每个 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.

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

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 获取精确定价。

Kling O3 API 用法

Kling O3 Reference to Video 也通过 Venice API 可用。完整详情请参阅 Video Queue API。

Python

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

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

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 张）。如果省略，正面图像将用作参考。

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

Kling O3 故障排查

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

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

Grok Imagine Reference to Video

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

工作原理

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

如果您不在 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

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

分步指南（Video Studio）

1. 选择模型

前往 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 字段中输入 @ 可查看可用图像引用的自动完成菜单。

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

4. 配置设置并生成

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

Grok Imagine R2V 定价

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

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

示例： 8 秒 480p 视频 = 8 ×

0.063 = **~

0.50**

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

Grok Imagine R2V API 用法

Python

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

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

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"`

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

Grok Imagine R2V 故障排查

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

​何时使用 Reference to Video

​可用模型

​Kling O3 Reference to Video

​核心概念

​Elements

​场景参考图像

​限制

​多镜头模式

​分步指南（Video Studio）

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

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

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

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

​5. 编写您的 prompt

​6. 配置设置

​7. 生成

​多镜头故事板

​Prompt 技巧

​构建您的 prompt

​保持 prompt 在 50–150 字之间

​使用简单的摄影机语言

​使用一致的词汇

​将摄影机指令放在前面

​Kling O3 定价

​Kling O3 API 用法

​Python

​Node.js

​cURL

​Element 模式

​Kling O3 故障排查

​Grok Imagine Reference to Video

​工作原理

​设置

​分步指南（Video Studio）

​1. 选择模型

​2. 上传参考图像

​3. 编写您的 prompt

​4. 配置设置并生成

​Grok Imagine R2V 定价

​Grok Imagine R2V API 用法

​Python

​Node.js

​cURL

​API 参数

​Grok Imagine R2V 故障排查

何时使用 Reference to Video

可用模型

Kling O3 Reference to Video

核心概念

Elements

场景参考图像

限制

多镜头模式

分步指南（Video Studio）

1. 打开 Video Studio 并选择模型

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

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

4. 上传起始帧（可选）

5. 编写您的 prompt

6. 配置设置

7. 生成

多镜头故事板

Prompt 技巧

构建您的 prompt

保持 prompt 在 50–150 字之间

使用简单的摄影机语言

使用一致的词汇

将摄影机指令放在前面

Kling O3 定价

Kling O3 API 用法

Python

Node.js

cURL

Element 模式

Kling O3 故障排查

Grok Imagine Reference to Video

工作原理

设置

分步指南（Video Studio）

1. 选择模型

2. 上传参考图像

3. 编写您的 prompt

4. 配置设置并生成

Grok Imagine R2V 定价

Grok Imagine R2V API 用法

Python

Node.js

cURL

API 参数

Grok Imagine R2V 故障排查