Guia de Reference to Video | Documentação da API Venice

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

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

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

Clique no quadro Frontal para fazer upload de uma imagem clara, de frente, do seu personagem ou objeto
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).

O total combinado de primeiro frame, último frame, elements e scene images não pode exceder 7. Veja Limitações para detalhes.

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

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

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

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.

Na área de prompt, clique em Add Shot para criar shots adicionais
Escreva um prompt separado para cada shot
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.

A duração total multi-shot não pode exceder 15 segundos. Por exemplo, três shots de 5 segundos = 15s no máximo.

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 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 para detalhes completos.

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

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.

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.

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

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.

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

Faça upload de 1–7 imagens de referência — fotos de personagens, objetos ou cenas que você quer no vídeo
Escreva um prompt que descreva o vídeo, usando @Image1, @Image2 etc. para referenciar imagens específicas
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

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

Guia passo a passo (Video Studio)

1. Selecione o modelo

Vá em 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.

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.

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

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.

Uso da API Grok Imagine R2V

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

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

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.

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

​Quando usar Reference to Video

​Modelos disponíveis

​Kling O3 Reference to Video

​Conceitos centrais

​Elements

​Scene Reference Images

​Limitações

​Modo multi-shot

​Guia passo a passo (Video Studio)

​1. Abra o Video Studio e selecione o modelo

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

​3. Adicione Scene Reference Images (opcional)

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

​5. Escreva seu prompt

​6. Configure as definições

​7. Gere

​Storyboarding multi-shot

​Dicas de prompting

​Estruture seu prompt

​Mantenha prompts entre 50–150 palavras

​Use linguagem de câmera simples

​Use vocabulário consistente

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

​Preços do Kling O3

​Uso da API Kling O3

​Python

​Node.js

​cURL

​Schema do element

​Solução de problemas do Kling O3

​Grok Imagine Reference to Video

​Como funciona

​Configurações

​Guia passo a passo (Video Studio)

​1. Selecione o modelo

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

​3. Escreva seu prompt

​4. Configure as definições e gere

​Preços do Grok Imagine R2V

​Uso da API Grok Imagine R2V

​Python

​Node.js

​cURL

​Parâmetros da API

​Solução de problemas do Grok Imagine R2V

Quando usar Reference to Video

Modelos disponíveis

Kling O3 Reference to Video

Conceitos centrais

Elements

Scene Reference Images

Limitações

Modo multi-shot

Guia passo a passo (Video Studio)

1. Abra o Video Studio e selecione o modelo

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

3. Adicione Scene Reference Images (opcional)

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

5. Escreva seu prompt

6. Configure as definições

7. Gere

Storyboarding multi-shot

Dicas de prompting

Estruture seu prompt

Mantenha prompts entre 50–150 palavras

Use linguagem de câmera simples

Use vocabulário consistente

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

Preços do Kling O3

Uso da API Kling O3

Python

Node.js

cURL

Schema do element

Solução de problemas do Kling O3

Grok Imagine Reference to Video

Como funciona

Configurações

Guia passo a passo (Video Studio)

1. Selecione o modelo

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

3. Escreva seu prompt

4. Configure as definições e gere

Preços do Grok Imagine R2V

Uso da API Grok Imagine R2V

Python

Node.js

cURL

Parâmetros da API

Solução de problemas do Grok Imagine R2V