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 |
@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) |
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 |
- 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
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.
@Element1 and @Element2 enter the cafe in @Image1 from opposite sides.
@Element1 waves and walks toward @Element2, who is sitting at a corner table.
| 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]
@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 |
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.
@ 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.
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 |
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 |
