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

> Gere vídeos consistentes com elementos de personagem, referências de cena e controle multi-shot na Venice API usando Kling O3 e Grok Imagine R2V.

O Reference to Video permite travar a aparência de personagens, objetos e cenas para que seus vídeos gerados por IA permaneçam visualmente consistentes. Em vez de torcer para que o modelo interprete seu prompt corretamente, você fornece âncoras visuais — imagens de referência que dizem ao modelo exatamente como seu sujeito se parece.

Esse recurso está disponível nos modelos **Kling O3** e **Grok Imagine R2V** no [Venice Video Studio](https://venice.ai/video). Cada família de modelo usa uma abordagem diferente para imagens de referência — veja as seções específicas de cada modelo abaixo.

## Quando usar Reference to Video

Use Reference to Video quando você precisar de:

* **Consistência de personagem** — a mesma pessoa ou personagem em várias tomadas
* **Precisão de produto** — um produto real que deve parecer idêntico ao original
* **Continuidade de cena** — um ambiente ou plano de fundo específico entre gerações
* **Cenas multi-personagem** — vários personagens distintos interagindo sem se misturar

Para texto-para-vídeo ou imagem-para-vídeo simples, onde consistência não é crítica, os modelos padrão funcionam bem sem referências.

## Modelos disponíveis

| Modelo                    | Abordagem                    | Melhor para                                                         |
| ------------------------- | ---------------------------- | ------------------------------------------------------------------- |
| **Kling O3 Pro R2V**      | Elements + imagens de cena   | Cenas multi-personagem complexas com controle de identidade preciso |
| **Kling O3 Standard R2V** | Elements + imagens de cena   | Iteração mais rápida em cenas baseadas em Elements                  |
| **Grok Imagine R2V**      | Imagens de referência planas | Geração rápida guiada por referência com até 7 imagens              |

O **Kling O3** usa uma abordagem estruturada com Elements (âncoras de identidade de personagem com imagens frontais + de referência) e Scene Images. O **Grok Imagine R2V** usa uma abordagem mais simples — você faz upload de imagens de referência diretamente e as referencia no seu prompt com `@Image1`, `@Image2` etc.

***

## Kling O3 Reference to Video

### Conceitos centrais

O Kling O3 Reference to Video usa três tipos de entrada visual que trabalham juntas:

| Entrada                    | Obrigatório                     | Finalidade                                    | Como referenciar no prompt    |
| -------------------------- | ------------------------------- | --------------------------------------------- | ----------------------------- |
| **Elements**               | Pelo menos uma entrada visual\* | Trava a identidade de um personagem ou objeto | `@Element1`, `@Element2` etc. |
| **Scene Reference Images** | Pelo menos uma entrada visual\* | Define o ambiente, estilo e atmosfera         | `@Image1`, `@Image2` etc.     |
| **Start Frame**            | Pelo menos uma entrada visual\* | Controla o primeiro frame do vídeo            | N/D (definido via upload)     |
| **End Frame**              | Não                             | Controla o último frame do vídeo              | N/D (definido via upload)     |

\*Pelo menos um de: start frame, elements ou scene reference images é obrigatório.

### Elements

Um Element é um personagem ou objeto que você quer manter visualmente estável ao longo do vídeo. Cada elemento consiste em:

* **Frontal Image** (obrigatória por elemento) — uma foto clara, de frente, do sujeito. Esta é a âncora de identidade primária. Pense nela como a "foto de passaporte" do seu personagem ou produto.
* **Reference Images** (1–3, opcionais) — ângulos adicionais do mesmo sujeito (vista lateral, 45 graus, costas). Eles ajudam o modelo a entender o sujeito no espaço 3D. Se não forem fornecidas, a imagem frontal é automaticamente usada como referência.

Você pode adicionar até **7 elements** por geração (limitado pelo total combinado). Referencie-os no seu prompt usando `@Element1`, `@Element2` etc.

### Scene Reference Images

As referências de cena definem o "palco" onde a ação acontece. Elas influenciam:

* Iluminação e paleta de cores
* Arquitetura e detalhes do ambiente
* Estilo visual geral e atmosfera

Você pode adicionar até **4 imagens de cena**. Referencie-as como `@Image1`, `@Image2` etc. no seu prompt.

### Limitações

O número total de imagens em todos os tipos de entrada é limitado:

| Limite                                                                        | Valor                                                             |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Mínimo obrigatório**                                                        | Pelo menos 1 entrada visual (start frame, element ou scene image) |
| **Total combinado** (primeiro frame + último frame + elements + scene images) | **7 no máximo**                                                   |
| Elements (sem start/end frame)                                                | 7 no máximo                                                       |
| Elements (com start ou end frame)                                             | 3 no máximo                                                       |
| Scene reference images                                                        | 4 no máximo                                                       |
| Reference images por element                                                  | 1–3                                                               |

**Exemplos de cenários:**

* 7 elements + 0 scene images = 7 ✓ (sem frames)
* 5 elements + 2 scene images = 7 ✓ (sem frames)
* Primeiro frame (1) + 3 elements + 3 scene images = 7 ✓
* Primeiro frame (1) + último frame (1) + 3 elements + 2 scene images = 7 ✓
* Primeiro frame (1) + 4 elements = ✗ (máx. 3 elements com frame)
* Primeiro frame (1) + último frame (1) + 4 elements = ✗ (máx. 3 elements com frames)

<Note>
  Cada element requer uma **imagem frontal**. Se você não fornecer reference images para um element, a imagem frontal é usada automaticamente como referência.
</Note>

### Modo multi-shot

O multi-shot permite quebrar uma única geração em várias cenas, cada uma com seu próprio prompt e duração. Elements e scene references são mantidos em todos os shots, mantendo a consistência. A duração total em todos os shots não pode exceder **15 segundos**.

***

### Guia passo a passo (Video Studio)

#### 1. Abra o Video Studio e selecione o modelo

Vá em [venice.ai/video](https://venice.ai/video). No Model Browser à esquerda, selecione um dos modelos **Kling O3 Reference to Video**:

* **Kling O3 Pro R2V** — maior qualidade, tempo de geração mais longo (\~6 min)
* **Kling O3 Standard R2V** — mais rápido, mais econômico para iteração

#### 2. Adicione Visual Inputs (pelo menos um obrigatório)

Você deve fornecer **pelo menos uma entrada visual** para gerar um vídeo: um start frame, um element ou uma scene reference image. No Input Panel, você verá a seção **Elements**. Clique em **Add Element** para criar um element para personagens ou objetos que você quer manter visualmente consistentes.

Para cada element:

1. Clique no quadro **Frontal** para fazer upload de uma imagem clara, de frente, do seu personagem ou objeto
2. Opcionalmente clique em **Add** sob **Reference Images** para fazer upload de ângulos adicionais (1–3)

Repita para personagens ou objetos adicionais (até 7 elements no total, ou 3 se estiver usando start/end frames).

<Warning>
  O total combinado de primeiro frame, último frame, elements e scene images não pode exceder **7**. Veja [Limitações](#limitations) para detalhes.
</Warning>

<Tip>
  **Melhores imagens de referência:** Use fotos bem iluminadas com um fundo limpo. Forneça vistas de frente, lateral e em ângulo de 45 graus para o travamento de identidade mais forte. Garanta que todas as imagens de referência compartilhem o mesmo estilo visual (não misture fotorrealista e anime).
</Tip>

#### 3. Adicione Scene Reference Images (opcional)

Abaixo da seção Elements, você verá **Scene Reference Images**. Faça upload de imagens que definam o ambiente que você quer — uma localização específica, esquema de iluminação ou estilo artístico.

Elas são automaticamente marcadas como `@Image1`, `@Image2` etc.

#### 4. Faça upload de um Start Frame (opcional)

Se você quiser controlar o primeiro frame exato do seu vídeo, mude para o tipo de entrada **Image** e faça upload de um start frame. Você também pode opcionalmente definir um end frame.

#### 5. Escreva seu prompt

No campo de prompt, descreva a ação que você quer, referenciando seus elements e scene images usando as tags `@`:

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

Para **cenas multi-personagem**:

```
@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. Configure as definições

Abra **Video Settings** para ajustar:

| Configuração   | Opções           | Padrão    |
| -------------- | ---------------- | --------- |
| Duração        | 3s – 15s         | 5s        |
| Aspect Ratio   | 16:9, 9:16, 1:1  | 16:9      |
| Generate Audio | Ligado/Desligado | Desligado |

<Note>
  A geração de áudio adiciona efeitos sonoros nativos, diálogo e áudio ambiente sincronizados com o vídeo. Aumenta o custo em \~25%.
</Note>

#### 7. Gere

Clique em **Generate Video**. O Kling O3 normalmente leva 4–6 minutos dependendo do tier do modelo e da duração. Você pode enfileirar várias gerações e navegar pelos resultados na Video Gallery.

***

### Storyboarding multi-shot

Para sequências narrativas, use o modo multi-shot para definir cenas separadas dentro de uma única geração.

1. Na área de prompt, clique em **Add Shot** para criar shots adicionais
2. Escreva um prompt separado para cada shot
3. Defina a duração para cada shot (3–15s cada, total ≤ 15s)

Elements e scene references persistem em todos os shots automaticamente:

```
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>
  A duração total multi-shot não pode exceder 15 segundos. Por exemplo, três shots de 5 segundos = 15s no máximo.
</Warning>

***

### Dicas de prompting

#### Estruture seu prompt

Siga este padrão para resultados confiáveis:

```
[subject with @Element tag] + [action] + [environment with @Image tag] + [camera movement] + [lighting/style]
```

**Exemplo:**

```
@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.
```

#### Mantenha prompts entre 50–150 palavras

Prompts mais curtos carecem de detalhes. Prompts mais longos introduzem contradições. Mire no ponto ideal.

#### Use linguagem de câmera simples

O modelo responde melhor a direções de câmera diretas:

| Use                         | Evite                                           |
| --------------------------- | ----------------------------------------------- |
| `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` |

#### Use vocabulário consistente

Se você descreve um personagem usando "a red jacket" em um prompt, não troque para "crimson coat" no próximo. O modelo trata palavras diferentes como intenções diferentes.

#### Coloque instruções de câmera no início

Coloque a direção de câmera próximo ao começo do prompt para resultados mais confiáveis:

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

***

### Preços do Kling O3

Os modelos Kling O3 Reference to Video usam preços baseados em duração:

| Modelo                | Por segundo (sem áudio) | Por segundo (com áudio) |
| --------------------- | ----------------------- | ----------------------- |
| Kling O3 Pro R2V      | \$0,112                 | \$0,140                 |
| Kling O3 Standard R2V | \$0,112                 | \$0,140                 |

**Exemplo:** Um vídeo de 10 segundos com áudio = 10 × $0,14 = **$1,40\*\*

Use a [Video Quote API](https://docs.venice.ai/api-reference/endpoint/video/quote) para preços exatos antes da geração.

***

### Uso da API Kling O3

O Kling O3 Reference to Video também está disponível via API Venice. Veja a [Video Queue API](https://docs.venice.ai/api-reference/endpoint/video/queue) para detalhes completos.

#### 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"
    ]
  }'
```

#### Schema do element

Cada element no array `elements` aceita:

| Campo                  | Tipo      | Obrigatório | Descrição                                                                               |
| ---------------------- | --------- | ----------- | --------------------------------------------------------------------------------------- |
| `frontal_image_url`    | string    | **Sim**     | URL de imagem clara de frente                                                           |
| `reference_image_urls` | string\[] | Não         | URLs de ângulos adicionais (1–3). Se omitido, a imagem frontal é usada como referência. |

<Note>
  A API também suporta `video_url` para elements baseados em vídeo, mas isso atualmente não está disponível na UI do Video Studio.
</Note>

***

### Solução de problemas do Kling O3

| Problema                                       | Causa provável                                           | Correção                                                                                 |
| ---------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Botão Generate está desabilitado               | Nenhuma entrada visual fornecida                         | Adicione pelo menos uma entrada visual: start frame, element ou scene reference image    |
| Erro "Number of images exceeds the limit"      | Muitas entradas combinadas                               | Total de primeiro frame + último frame + elements + scene images deve ser ≤ 7            |
| Rosto do personagem muda entre shots           | Imagem frontal diferente ou ausente                      | Use a mesma imagem frontal consistentemente, mantenha a descrição idêntica               |
| Movimento de câmera parece aleatório           | Múltiplas ou conflitantes instruções de câmera           | Use uma única instrução de câmera, coloque-a cedo no prompt                              |
| Estilo muda entre gerações                     | Referências de cena inconsistentes ou estilos misturados | Reutilize as mesmas scene images, mantenha palavras-chave de estilo consistentes         |
| Elements se misturam em cenas multi-personagem | Instruções espaciais vagas                               | Seja explícito sobre a posição de cada element: "foreground left", "entering from right" |
| Plano de fundo parece distorcido               | Imagem de referência de cena bagunçada ou complexa       | Use scene reference images limpas e de alta qualidade                                    |
| Movimento parece não natural                   | Muitas ações em um único prompt                          | Simplifique a ação, use duração mais curta, uma ação por shot                            |

<Tip>
  Teste com um clipe de 3–5 segundos antes de se comprometer com durações mais longas. Clipes mais curtos mantêm melhor consistência e permitem iterar mais rapidamente.
</Tip>

***

## Grok Imagine Reference to Video

O Grok Imagine R2V usa uma abordagem mais simples que o Kling O3. Em vez de Elements estruturados com separação frontal/reference image, você faz upload de **imagens de referência planas** e as referencia diretamente no seu prompt usando `@Image1`, `@Image2` etc. O modelo incorpora esses sujeitos no vídeo gerado.

### Como funciona

1. Faça upload de **1–7 imagens de referência** — fotos de personagens, objetos ou cenas que você quer no vídeo
2. Escreva um prompt que descreva o vídeo, usando `@Image1`, `@Image2` etc. para referenciar imagens específicas
3. O modelo gera um vídeo incorporando essas referências

Se você não incluir tags `@Image` no seu prompt, todas as imagens enviadas são referenciadas automaticamente.

### Configurações

| Configuração | Opções                              | Padrão |
| ------------ | ----------------------------------- | ------ |
| Aspect Ratio | 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16 | 16:9   |
| Resolution   | 480p, 720p                          | 480p   |
| Duration     | 5s, 8s, 10s                         | 8s     |

<Note>
  O Grok Imagine R2V não suporta geração de áudio, modo multi-shot ou Elements. Para esses recursos, use Kling O3 R2V.
</Note>

### Guia passo a passo (Video Studio)

#### 1. Selecione o modelo

Vá em [venice.ai/video](https://venice.ai/video). No Model Browser, selecione **Grok Imagine R2V**.

#### 2. Faça upload das imagens de referência

Clique em **References** na barra de ferramentas de entrada (ou use o menu +) para abrir o painel de imagens de referência. Faça upload de 1–7 imagens dos personagens, objetos ou cenas que você quer no vídeo.

Cada imagem é automaticamente marcada como `@Image1`, `@Image2` etc. na ordem em que você as envia (da esquerda para a direita).

#### 3. Escreva seu prompt

Descreva o vídeo que você quer. Use tags `@Image` para referenciar imagens específicas:

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

Digite `@` no campo de prompt para ver um menu de autocomplete das referências de imagem disponíveis.

<Tip>
  Se você omitir as tags `@Image` totalmente, o backend automaticamente prepende referências a todas as imagens enviadas. Isso é útil quando você quer que todas as imagens sejam usadas sem especificar qual é qual.
</Tip>

#### 4. Configure as definições e gere

Abra **Video Settings** para ajustar aspect ratio, resolução e duração. Clique em **Generate Video**.

### Preços do Grok Imagine R2V

O Grok Imagine R2V usa preços baseados em duração e resolução:

| Resolução | Por segundo |
| --------- | ----------- |
| 480p      | \~\$0,063   |
| 720p      | \~\$0,088   |

**Exemplo:** Um vídeo de 8 segundos em 480p = 8 × $0,063 = **~$0,50\*\*

<Note>
  O Grok Imagine cobra uma taxa de moderação de conteúdo para vídeos gerados, mesmo se o vídeo for rejeitado. Isso é refletido no custo de créditos exibido antes da geração.
</Note>

### Uso da API Grok Imagine R2V

#### 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"
    ]
  }'
```

#### Parâmetros da API

| Campo                | Tipo      | Obrigatório | Descrição                                                      |
| -------------------- | --------- | ----------- | -------------------------------------------------------------- |
| `model`              | string    | **Sim**     | Deve ser `grok-imagine-reference-to-video`                     |
| `prompt`             | string    | **Sim**     | Prompt de texto com referências opcionais `@Image1`, `@Image2` |
| `referenceImageUrls` | string\[] | **Sim**     | 1–7 URLs de imagem ou data URLs                                |
| `duration`           | string    | Não         | `"5"`, `"8"` (padrão) ou `"10"`                                |
| `aspect_ratio`       | string    | Não         | por exemplo, `"16:9"` (padrão), `"9:16"`, `"1:1"`              |
| `resolution`         | string    | Não         | `"480p"` (padrão) ou `"720p"`                                  |

<Note>
  O Grok Imagine R2V não usa os campos `elements`, `image_urls` ou `imageUrl`. Todas as imagens de referência são passadas via `referenceImageUrls`.
</Note>

### Solução de problemas do Grok Imagine R2V

| Problema                                        | Causa provável                              | Correção                                                                                                               |
| ----------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Botão Generate está desabilitado                | Nenhuma imagem de referência foi enviada    | Faça upload de pelo menos 1 imagem de referência                                                                       |
| Erro "At least one reference image is required" | `referenceImageUrls` está vazio ou ausente  | Forneça pelo menos uma URL de imagem em `referenceImageUrls`                                                           |
| Imagem errada associada à tag `@Image`          | A ordem das imagens não corresponde às tags | `@Image1` corresponde à primeira imagem na ordem de upload (esquerda para direita). Reordene os uploads se necessário. |
| Sujeito não aparece no vídeo                    | Muitas referências sem tags explícitas      | Use tags `@Image` no seu prompt para ser explícito sobre quais imagens usar                                            |
| Saída de baixa qualidade                        | Usando resolução 480p                       | Tente 720p para maior qualidade (custa mais)                                                                           |
| Vídeo muito curto                               | Duração padrão é 8s                         | Defina duração para `"10"` para vídeos mais longos                                                                     |