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

> Genera video AI coerenti con elementi di personaggi, riferimenti di scena e controllo multi-shot sull'API Venice usando i modelli Kling O3 e Grok Imagine R2V.

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](https://venice.ai/video). 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)

<Note>
  Ogni element richiede una **frontal image**. Se non fornisci reference image per un element, l'immagine frontale viene usata automaticamente come riferimento.
</Note>

### 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](https://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:

1. Clicca sulla tile **Frontal** per caricare un'immagine chiara e frontale del tuo personaggio o oggetto
2. 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).

<Warning>
  Il totale combinato di first frame, last frame, element e scene image non può superare **7**. Vedi [Limitazioni](#limitazioni) per i dettagli.
</Warning>

<Tip>
  **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).
</Tip>

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

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

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

1. Nell'area del prompt, clicca su **Add Shot** per creare shot aggiuntivi
2. Scrivi un prompt separato per ogni shot
3. 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.
```

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

***

### 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](https://docs.venice.ai/api-reference/endpoint/video/quote) 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](https://docs.venice.ai/api-reference/endpoint/video/queue) per i dettagli completi.

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

<Note>
  L'API supporta anche `video_url` per element basati su video, ma questo non è attualmente disponibile nella UI del Video Studio.
</Note>

***

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

<Tip>
  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.
</Tip>

***

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

1. Carica **1–7 immagini di riferimento** — foto di personaggi, oggetti o scene che vuoi nel video
2. Scrivi un prompt che descrive il video, usando `@Image1`, `@Image2`, ecc. per richiamare immagini specifiche
3. 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      |

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

### Guida passo-passo (Video Studio)

#### 1. Seleziona il modello

Vai su [venice.ai/video](https://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.

<Tip>
  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.
</Tip>

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

<Note>
  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.
</Note>

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

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

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

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