Reference to Video Guide | Venice API Docs

Reference to Video ti permette di bloccare l’aspetto di personaggi, oggetti e scene in modo che i tuoi video generati con AI rimangano visivamente consistenti. Invece di sperare che il modello interpreti correttamente il tuo prompt, fornisci ancore visive — immagini di riferimento che dicono al modello esattamente come appare il tuo soggetto. Questa funzionalità è disponibile sui modelli Kling O3 e Grok Imagine R2V nel Venice Video Studio. Ogni famiglia di modelli usa un approccio diverso alle immagini di riferimento — consulta le sezioni specifiche del modello qui sotto.

Quando usare Reference to Video

Usa Reference to Video quando ti serve:

Consistenza dei personaggi — la stessa persona o personaggio in più inquadrature
Accuratezza del prodotto — un prodotto reale che deve apparire identico all’originale
Continuità della scena — un ambiente o sfondo specifico tra le generazioni
Scene multi-personaggio — più personaggi distinti che interagiscono senza fondersi

Per semplice text-to-video o image-to-video in cui la consistenza non è critica, i modelli standard funzionano bene senza riferimenti.

Modelli disponibili

Modello	Approccio	Ideale per
Kling O3 Pro R2V	Elements + scene image	Scene multi-personaggio complesse con controllo preciso dell’identità
Kling O3 Standard R2V	Elements + scene image	Iterazione più rapida su scene element-based
Grok Imagine R2V	Immagini di riferimento flat	Generazione rapida basata su riferimenti con fino a 7 immagini

Kling O3 usa un approccio strutturato con Elements (ancore di identità del personaggio con immagini frontali + di riferimento) e Scene Images. Grok Imagine R2V adotta un approccio più semplice — carichi le immagini di riferimento direttamente e le richiami nel tuo prompt con @Image1, @Image2, ecc.

Kling O3 Reference to Video

Concetti chiave

Kling O3 Reference to Video usa tre tipi di input visivo che funzionano insieme:

Input	Obbligatorio	Scopo	Come richiamarlo nel prompt
Elements	Almeno un input visivo*	Blocca l’identità di un personaggio o oggetto	`@Element1`, `@Element2`, ecc.
Scene Reference Images	Almeno un input visivo*	Imposta ambiente, stile e atmosfera	`@Image1`, `@Image2`, ecc.
Start Frame	Almeno un input visivo*	Controlla il primo frame del video	N/A (impostato tramite upload)
End Frame	No	Controlla l’ultimo frame del video	N/A (impostato tramite upload)

*È richiesto almeno uno tra: start frame, elements o scene reference images.

Elements

Un Element è un personaggio o oggetto che vuoi mantenere visivamente stabile per tutto il video. Ogni element è composto da:

Frontal Image (obbligatoria per ogni element) — una foto chiara, frontale del soggetto. Questa è l’ancora di identità primaria. Pensala come la “foto del passaporto” del tuo personaggio o prodotto.
Reference Images (1–3, opzionali) — angolazioni aggiuntive dello stesso soggetto (vista laterale, angolo a 45 gradi, retro). Aiutano il modello a comprendere il soggetto nello spazio 3D. Se non fornite, l’immagine frontale viene usata automaticamente come riferimento.

Puoi aggiungere fino a 7 element per generazione (limitato dal totale combinato). Richiamali nel tuo prompt usando @Element1, @Element2, ecc.

Scene Reference Images

I riferimenti di scena definiscono il “palcoscenico” in cui si svolge l’azione. Influenzano:

Illuminazione e palette di colori
Architettura e dettagli dell’ambiente
Stile visivo complessivo e atmosfera

Puoi aggiungere fino a 4 scene image. Richiamale come @Image1, @Image2, ecc. nel tuo prompt.

Limitazioni

Il numero totale di immagini tra tutti i tipi di input è limitato:

Limite	Valore
Minimo richiesto	Almeno 1 input visivo (start frame, element o scene image)
Totale combinato (first frame + last frame + elements + scene image)	7 massimo
Elements (senza start/end frame)	7 massimo
Elements (con start o end frame)	3 massimo
Scene reference image	4 massimo
Reference image per element	1–3

Scenari di esempio:

7 element + 0 scene image = 7 ✓ (nessun frame)
5 element + 2 scene image = 7 ✓ (nessun frame)
First frame (1) + 3 element + 3 scene image = 7 ✓
First frame (1) + last frame (1) + 3 element + 2 scene image = 7 ✓
First frame (1) + 4 element = ✗ (max 3 element con frame)
First frame (1) + last frame (1) + 4 element = ✗ (max 3 element con frame)

Ogni element richiede una frontal image. Se non fornisci reference image per un element, l’immagine frontale viene usata automaticamente come riferimento.

Modalità multi-shot

Multi-shot ti permette di suddividere una singola generazione in più scene, ciascuna con il proprio prompt e durata. Gli element e i riferimenti di scena si propagano attraverso tutti gli shot, mantenendo la consistenza. La durata totale di tutti gli shot non può superare i 15 secondi.

Guida passo-passo (Video Studio)

1. Apri Video Studio e seleziona il modello

Vai su venice.ai/video. Nel Model Browser a sinistra, seleziona uno dei modelli Kling O3 Reference to Video:

Kling O3 Pro R2V — qualità più alta, tempo di generazione più lungo (~6 min)
Kling O3 Standard R2V — più veloce, più economico per l’iterazione

2. Aggiungi Visual Inputs (almeno uno obbligatorio)

Devi fornire almeno un input visivo per generare un video: uno start frame, un element o un’immagine di riferimento di scena. Nell’Input Panel, vedrai la sezione Elements. Clicca su Add Element per creare un element per personaggi o oggetti che vuoi mantenere visivamente consistenti. Per ogni element:

Clicca sulla tile Frontal per caricare un’immagine chiara e frontale del tuo personaggio o oggetto
Opzionalmente clicca su Add sotto Reference Images per caricare angolazioni aggiuntive (1–3)

Ripeti per ulteriori personaggi o oggetti (fino a 7 element in totale, o 3 se usi start/end frame).

Il totale combinato di first frame, last frame, element e scene image non può superare 7. Vedi Limitazioni per i dettagli.

Le migliori immagini di riferimento: Usa foto ben illuminate con uno sfondo pulito. Fornisci viste frontale, laterale e a 45 gradi per il blocco di identità più solido. Assicurati che tutte le immagini di riferimento condividano lo stesso stile visivo (non mischiare fotorealistico e anime).

3. Aggiungi Scene Reference Images (opzionale)

Sotto la sezione Elements, vedrai Scene Reference Images. Carica immagini che definiscono l’ambiente che vuoi — una location specifica, un’illuminazione o uno stile artistico. Queste vengono taggate automaticamente come @Image1, @Image2, ecc.

4. Carica uno Start Frame (opzionale)

Se vuoi controllare il primo frame esatto del tuo video, passa al tipo di input Image e carica uno start frame. Puoi anche impostare opzionalmente un end frame.

5. Scrivi il tuo prompt

Nel campo prompt, descrivi l’azione che vuoi richiamando i tuoi element e scene image usando i tag @:

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

Per scene multi-personaggio:

@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. Configura le impostazioni

Apri Video Settings per regolare:

Impostazione	Opzioni	Default
Durata	3s – 15s	5s
Aspect Ratio	16:9, 9:16, 1:1	16:9
Generate Audio	On/Off	Off

La generazione audio aggiunge effetti sonori, dialoghi e audio ambientale nativi sincronizzati con il video. Aumenta il costo di ~25%.

7. Genera

Clicca su Generate Video. Kling O3 richiede tipicamente 4–6 minuti a seconda del tier del modello e della durata. Puoi mettere in coda più generazioni e sfogliare i risultati nella Video Gallery.

Storyboarding multi-shot

Per sequenze narrative, usa la modalità multi-shot per definire scene separate all’interno di una singola generazione.

Nell’area del prompt, clicca su Add Shot per creare shot aggiuntivi
Scrivi un prompt separato per ogni shot
Imposta la durata per ogni shot (3–15s ciascuno, totale ≤ 15s)

Element e riferimenti di scena persistono automaticamente attraverso tutti gli shot:

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.

La durata totale multi-shot non può superare i 15 secondi. Per esempio, tre shot da 5 secondi = 15s massimo.

Consigli per il prompting

Struttura il tuo prompt

Segui questo schema per risultati affidabili:

[soggetto con tag @Element] + [azione] + [ambiente con tag @Image] + [movimento di camera] + [illuminazione/stile]

Esempio:

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

Mantieni i prompt tra 50 e 150 parole

I prompt più brevi mancano di dettagli. I prompt più lunghi introducono contraddizioni. Punta al punto ottimale.

Usa un linguaggio di camera semplice

Il modello risponde meglio a direzioni di camera semplici:

Usa	Evita
`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`

Usa un vocabolario consistente

Se descrivi un personaggio che indossa “a red jacket” in un prompt, non passare a “crimson coat” in quello successivo. Il modello tratta parole diverse come intent diversi.

Posiziona le istruzioni di camera all’inizio

Metti la direzione di camera vicino all’inizio del prompt per risultati più affidabili:

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

Prezzi Kling O3

I modelli Kling O3 Reference to Video usano prezzi basati sulla durata:

Modello	Per secondo (senza audio)	Per secondo (con audio)
Kling O3 Pro R2V	$0,112	$0,140
Kling O3 Standard R2V	$0,112	$0,140

Esempio: Un video di 10 secondi con audio = 10 ×

0,14 = **

1,40** Usa la Video Quote API per il prezzo esatto prima della generazione.

Utilizzo dell’API Kling O3

Kling O3 Reference to Video è disponibile anche tramite l’API Venice. Consulta la Video Queue API per i dettagli completi.

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 degli element

Ogni element nell’array elements accetta:

Campo	Tipo	Obbligatorio	Descrizione
`frontal_image_url`	string	Sì	URL dell’immagine chiara e frontale
`reference_image_urls`	string[]	No	URL di angolazioni aggiuntive (1–3). Se omesso, l’immagine frontale viene usata come riferimento.

L’API supporta anche video_url per element basati su video, ma questo non è attualmente disponibile nella UI del Video Studio.

Troubleshooting Kling O3

Problema	Causa probabile	Soluzione
Il pulsante Generate è disabilitato	Nessun input visivo fornito	Aggiungi almeno un input visivo: start frame, element o scene reference image
Errore “Number of images exceeds the limit”	Troppi input combinati	Il totale di first frame + last frame + element + scene image deve essere ≤ 7
Il volto del personaggio cambia tra gli shot	Frontal image diversa o mancante	Usa la stessa frontal image in modo consistente, mantieni la descrizione identica
Il movimento di camera sembra casuale	Istruzioni di camera multiple o contraddittorie	Usa una sola istruzione di camera, posizionala all’inizio del prompt
Lo stile cambia tra le generazioni	Riferimenti di scena incoerenti o stili misti	Riutilizza le stesse scene image, mantieni consistenti le keyword di stile
Gli element si fondono in scene multi-personaggio	Istruzioni spaziali vaghe	Sii esplicito sulla posizione di ogni element: “foreground left”, “entering from right”
Lo sfondo appare distorto	Scene reference image disordinata o complessa	Usa scene reference image pulite e di alta qualità
Il movimento appare innaturale	Troppe azioni in un solo prompt	Semplifica l’azione, usa una durata più breve, una azione per shot

Testa con una clip di 3–5 secondi prima di impegnarti su durate più lunghe. Le clip più brevi mantengono una migliore consistenza e ti permettono di iterare più velocemente.

Grok Imagine Reference to Video

Grok Imagine R2V adotta un approccio più semplice rispetto a Kling O3. Invece di Elements strutturati con separazione tra immagini frontali e di riferimento, carichi immagini di riferimento flat e le richiami direttamente nel tuo prompt usando @Image1, @Image2, ecc. Il modello incorpora quei soggetti nel video generato.

Come funziona

Carica 1–7 immagini di riferimento — foto di personaggi, oggetti o scene che vuoi nel video
Scrivi un prompt che descrive il video, usando @Image1, @Image2, ecc. per richiamare immagini specifiche
Il modello genera un video che incorpora quei riferimenti

Se non includi tag @Image nel tuo prompt, tutte le immagini caricate vengono richiamate automaticamente.

Impostazioni

Impostazione	Opzioni	Default
Aspect Ratio	16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16	16:9
Risoluzione	480p, 720p	480p
Durata	5s, 8s, 10s	8s

Grok Imagine R2V non supporta la generazione audio, la modalità multi-shot o gli Elements. Per quelle funzionalità, usa Kling O3 R2V.

Guida passo-passo (Video Studio)

1. Seleziona il modello

Vai su venice.ai/video. Nel Model Browser, seleziona Grok Imagine R2V.

2. Carica le immagini di riferimento

Clicca su References nella toolbar di input (o usa il menu +) per aprire il pannello delle immagini di riferimento. Carica 1–7 immagini di personaggi, oggetti o scene che vuoi nel video. Ogni immagine viene taggata automaticamente come @Image1, @Image2, ecc. nell’ordine in cui le carichi (da sinistra a destra).

3. Scrivi il tuo prompt

Descrivi il video che vuoi. Usa i tag @Image per richiamare immagini specifiche:

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

Digita @ nel campo prompt per vedere un menu di autocomplete dei riferimenti di immagine disponibili.

Se ometti del tutto i tag @Image, il backend prepende automaticamente i riferimenti a tutte le immagini caricate. Questo è utile quando vuoi che tutte le immagini siano usate senza specificare quale sia quale.

4. Configura le impostazioni e genera

Apri Video Settings per regolare aspect ratio, risoluzione e durata. Clicca su Generate Video.

Prezzi Grok Imagine R2V

Grok Imagine R2V usa prezzi basati su durata e risoluzione:

Risoluzione	Per secondo
480p	~$0,063
720p	~$0,088

Esempio: Un video di 8 secondi a 480p = 8 ×

0,063 = **~

0,50**

Grok Imagine addebita una commissione di moderazione dei contenuti per i video generati, anche se il video viene rifiutato. Questo si riflette nel costo in credito mostrato prima della generazione.

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

Parametri API

Campo	Tipo	Obbligatorio	Descrizione
`model`	string	Sì	Deve essere `grok-imagine-reference-to-video`
`prompt`	string	Sì	Prompt testuale con riferimenti opzionali `@Image1`, `@Image2`
`referenceImageUrls`	string[]	Sì	1–7 URL di immagini o data URL
`duration`	string	No	`"5"`, `"8"` (default) o `"10"`
`aspect_ratio`	string	No	es. `"16:9"` (default), `"9:16"`, `"1:1"`
`resolution`	string	No	`"480p"` (default) o `"720p"`

Grok Imagine R2V non usa i campi elements, image_urls o imageUrl. Tutte le immagini di riferimento vengono passate tramite referenceImageUrls.

Troubleshooting Grok Imagine R2V

Problema	Causa probabile	Soluzione
Il pulsante Generate è disabilitato	Nessuna immagine di riferimento caricata	Carica almeno 1 immagine di riferimento
Errore “At least one reference image is required”	`referenceImageUrls` è vuoto o mancante	Fornisci almeno un URL di immagine in `referenceImageUrls`
Immagine sbagliata associata al tag `@Image`	L’ordine delle immagini non corrisponde ai tag	`@Image1` corrisponde alla prima immagine nel tuo ordine di upload (da sinistra a destra). Riordina gli upload se necessario.
Il soggetto non appare nel video	Troppi riferimenti senza tag espliciti	Usa i tag `@Image` nel tuo prompt per essere esplicito su quali immagini usare
Output di bassa qualità	Uso della risoluzione 480p	Prova 720p per qualità più alta (costa di più)
Video troppo corto	La durata di default è 8s	Imposta la durata su `"10"` per video più lunghi

​Quando usare Reference to Video

​Modelli disponibili

​Kling O3 Reference to Video

​Concetti chiave

​Elements

​Scene Reference Images

​Limitazioni

​Modalità multi-shot

​Guida passo-passo (Video Studio)

​1. Apri Video Studio e seleziona il modello

​2. Aggiungi Visual Inputs (almeno uno obbligatorio)

​3. Aggiungi Scene Reference Images (opzionale)

​4. Carica uno Start Frame (opzionale)

​5. Scrivi il tuo prompt

​6. Configura le impostazioni

​7. Genera

​Storyboarding multi-shot

​Consigli per il prompting

​Struttura il tuo prompt

​Mantieni i prompt tra 50 e 150 parole

​Usa un linguaggio di camera semplice

​Usa un vocabolario consistente

​Posiziona le istruzioni di camera all’inizio

​Prezzi Kling O3

​Utilizzo dell’API Kling O3

​Python

​Node.js

​cURL

​Schema degli element

​Troubleshooting Kling O3

​Grok Imagine Reference to Video

​Come funziona

​Impostazioni

​Guida passo-passo (Video Studio)

​1. Seleziona il modello

​2. Carica le immagini di riferimento

​3. Scrivi il tuo prompt

​4. Configura le impostazioni e genera

​Prezzi Grok Imagine R2V

​Utilizzo dell’API Grok Imagine R2V

​Python

​Node.js

​cURL

​Parametri API

​Troubleshooting Grok Imagine R2V

Quando usare Reference to Video

Modelli disponibili

Kling O3 Reference to Video

Concetti chiave

Elements

Scene Reference Images

Limitazioni

Modalità multi-shot

Guida passo-passo (Video Studio)

1. Apri Video Studio e seleziona il modello

2. Aggiungi Visual Inputs (almeno uno obbligatorio)

3. Aggiungi Scene Reference Images (opzionale)

4. Carica uno Start Frame (opzionale)

5. Scrivi il tuo prompt

6. Configura le impostazioni

7. Genera

Storyboarding multi-shot

Consigli per il prompting

Struttura il tuo prompt

Mantieni i prompt tra 50 e 150 parole

Usa un linguaggio di camera semplice

Usa un vocabolario consistente

Posiziona le istruzioni di camera all’inizio

Prezzi Kling O3

Utilizzo dell’API Kling O3

Python

Node.js

cURL

Schema degli element

Troubleshooting Kling O3

Grok Imagine Reference to Video

Come funziona

Impostazioni

Guida passo-passo (Video Studio)

1. Seleziona il modello

2. Carica le immagini di riferimento

3. Scrivi il tuo prompt

4. Configura le impostazioni e genera

Prezzi Grok Imagine R2V

Utilizzo dell’API Grok Imagine R2V

Python

Node.js

cURL

Parametri API

Troubleshooting Grok Imagine R2V