> ## 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 vídeos de IA con personajes, escenas y control multi-toma en la API de Venice usando los modelos Kling O3 y Grok Imagine R2V.

Reference to Video te permite fijar la apariencia de personajes, objetos y escenas para que tus vídeos generados por IA se mantengan visualmente consistentes. En lugar de esperar que el modelo interprete tu prompt correctamente, proporcionas anclajes visuales — imágenes de referencia que le dicen al modelo exactamente cómo se ve tu sujeto.

Esta función está disponible en los modelos **Kling O3** y **Grok Imagine R2V** en [Venice Video Studio](https://venice.ai/video). Cada familia de modelos usa un enfoque diferente para las imágenes de referencia — consulta las secciones específicas del modelo a continuación.

## Cuándo usar Reference to Video

Usa Reference to Video cuando necesites:

* **Consistencia de personaje** — la misma persona o personaje en varias tomas
* **Precisión del producto** — un producto real que debe verse idéntico al original
* **Continuidad de escena** — un entorno o fondo específico entre generaciones
* **Escenas multi-personaje** — varios personajes distintos interactuando sin mezclarse

Para text-to-video o image-to-video simples donde la consistencia no es crítica, los modelos estándar funcionan bien sin referencias.

## Modelos disponibles

| Modelo                    | Enfoque                        | Mejor para                                                         |
| ------------------------- | ------------------------------ | ------------------------------------------------------------------ |
| **Kling O3 Pro R2V**      | Elementos + imágenes de escena | Escenas multi-personaje complejas con control preciso de identidad |
| **Kling O3 Standard R2V** | Elementos + imágenes de escena | Iteración más rápida en escenas basadas en elementos               |
| **Grok Imagine R2V**      | Imágenes de referencia planas  | Generación rápida basada en referencias con hasta 7 imágenes       |

**Kling O3** usa un enfoque estructurado con Elementos (anclas de identidad de personaje con imágenes frontal + de referencia) e Imágenes de Escena. **Grok Imagine R2V** toma un enfoque más simple — subes imágenes de referencia directamente y las referencias en tu prompt con `@Image1`, `@Image2`, etc.

***

## Kling O3 Reference to Video

### Conceptos básicos

Kling O3 Reference to Video usa tres tipos de entrada visual que trabajan juntas:

| Entrada                              | Obligatorio                   | Propósito                                  | Cómo referenciar en el prompt  |
| ------------------------------------ | ----------------------------- | ------------------------------------------ | ------------------------------ |
| **Elements**                         | Al menos una entrada visual\* | Fija la identidad de un personaje u objeto | `@Element1`, `@Element2`, etc. |
| **Imágenes de referencia de escena** | Al menos una entrada visual\* | Establece el entorno, estilo y ambiente    | `@Image1`, `@Image2`, etc.     |
| **Frame inicial**                    | Al menos una entrada visual\* | Controla el primer frame del vídeo         | N/A (se establece al subir)    |
| **Frame final**                      | No                            | Controla el último frame del vídeo         | N/A (se establece al subir)    |

\*Se requiere al menos uno de: frame inicial, elementos o imágenes de referencia de escena.

### Elements

Un Element es un personaje u objeto que quieres mantener visualmente estable a lo largo del vídeo. Cada elemento consta de:

* **Imagen frontal** (obligatoria por elemento) — una foto clara y frontal del sujeto. Es el ancla principal de identidad. Piénsalo como la "foto de pasaporte" de tu personaje o producto.
* **Imágenes de referencia** (1–3, opcionales) — ángulos adicionales del mismo sujeto (vista lateral, ángulo de 45 grados, espalda). Ayudan al modelo a entender al sujeto en el espacio 3D. Si no se proporcionan, la imagen frontal se usa automáticamente como referencia.

Puedes añadir hasta **7 elementos** por generación (limitado por el total combinado). Refiérete a ellos en tu prompt usando `@Element1`, `@Element2`, etc.

### Imágenes de referencia de escena

Las referencias de escena definen el "escenario" donde tiene lugar la acción. Influyen en:

* Iluminación y paleta de colores
* Detalles de arquitectura y entorno
* Estilo visual general y atmósfera

Puedes añadir hasta **4 imágenes de escena**. Refiérete a ellas como `@Image1`, `@Image2`, etc. en tu prompt.

### Limitaciones

El número total de imágenes en todos los tipos de entrada está limitado:

| Límite                                                                             | Valor                                                                  |
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Mínimo requerido**                                                               | Al menos 1 entrada visual (frame inicial, elemento o imagen de escena) |
| **Total combinado** (primer frame + último frame + elementos + imágenes de escena) | **7 máximo**                                                           |
| Elementos (sin frame inicial/final)                                                | 7 máximo                                                               |
| Elementos (con frame inicial o final)                                              | 3 máximo                                                               |
| Imágenes de referencia de escena                                                   | 4 máximo                                                               |
| Imágenes de referencia por elemento                                                | 1–3                                                                    |

**Escenarios de ejemplo:**

* 7 elementos + 0 imágenes de escena = 7 ✓ (sin frames)
* 5 elementos + 2 imágenes de escena = 7 ✓ (sin frames)
* Primer frame (1) + 3 elementos + 3 imágenes de escena = 7 ✓
* Primer frame (1) + último frame (1) + 3 elementos + 2 imágenes de escena = 7 ✓
* Primer frame (1) + 4 elementos = ✗ (máx. 3 elementos con frame)
* Primer frame (1) + último frame (1) + 4 elementos = ✗ (máx. 3 elementos con frames)

<Note>
  Cada elemento requiere una **imagen frontal**. Si no proporcionas imágenes de referencia para un elemento, la imagen frontal se usa automáticamente como referencia.
</Note>

### Modo multi-toma

El modo multi-toma te permite dividir una sola generación en varias escenas, cada una con su propio prompt y duración. Los elementos y las referencias de escena se mantienen en todas las tomas, manteniendo la consistencia. La duración total entre todas las tomas no puede exceder **15 segundos**.

***

### Guía paso a paso (Video Studio)

#### 1. Abre Video Studio y selecciona el modelo

Ve a [venice.ai/video](https://venice.ai/video). En el Model Browser de la izquierda, selecciona uno de los modelos **Kling O3 Reference to Video**:

* **Kling O3 Pro R2V** — mayor calidad, tiempo de generación más largo (\~6 min)
* **Kling O3 Standard R2V** — más rápido, más rentable para iteración

#### 2. Añade entradas visuales (al menos una obligatoria)

Debes proporcionar **al menos una entrada visual** para generar un vídeo: un frame inicial, un elemento o una imagen de referencia de escena. En el Input Panel verás la sección **Elements**. Haz clic en **Add Element** para crear un elemento para personajes u objetos que quieras mantener visualmente consistentes.

Para cada elemento:

1. Haz clic en el tile **Frontal** para subir una imagen clara y frontal de tu personaje u objeto
2. Opcionalmente haz clic en **Add** bajo **Reference Images** para subir ángulos adicionales (1–3)

Repite para personajes u objetos adicionales (hasta 7 elementos en total, o 3 si usas frames inicial/final).

<Warning>
  El total combinado de primer frame, último frame, elementos e imágenes de escena no puede exceder **7**. Consulta [Limitaciones](#limitations) para detalles.
</Warning>

<Tip>
  **Mejores imágenes de referencia:** usa fotos bien iluminadas con un fondo limpio. Proporciona vistas de frente, lateral y de 45 grados para el bloqueo de identidad más fuerte. Asegúrate de que todas las imágenes de referencia compartan el mismo estilo visual (no mezcles fotorrealista y anime).
</Tip>

#### 3. Añade imágenes de referencia de escena (opcional)

Debajo de la sección Elements verás **Scene Reference Images**. Sube imágenes que definan el entorno que quieres — una ubicación específica, configuración de iluminación o estilo artístico.

Estas se etiquetan automáticamente como `@Image1`, `@Image2`, etc.

#### 4. Sube un frame inicial (opcional)

Si quieres controlar el primer frame exacto de tu vídeo, cambia al tipo de entrada **Image** y sube un frame inicial. También puedes opcionalmente establecer un frame final.

#### 5. Escribe tu prompt

En el campo de prompt, describe la acción que quieres mientras haces referencia a tus elementos e imágenes de escena usando las etiquetas `@`:

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

Para **escenas multi-personaje**:

```
@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 los ajustes

Abre **Video Settings** para ajustar:

| Ajuste        | Opciones        | Predeterminado |
| ------------- | --------------- | -------------- |
| Duración      | 3s – 15s        | 5s             |
| Aspect Ratio  | 16:9, 9:16, 1:1 | 16:9           |
| Generar audio | On/Off          | Off            |

<Note>
  La generación de audio añade efectos de sonido nativos, diálogo y audio ambiental sincronizados con el vídeo. Aumenta el coste aproximadamente un 25 %.
</Note>

#### 7. Genera

Haz clic en **Generate Video**. Kling O3 normalmente tarda 4–6 minutos según el nivel del modelo y la duración. Puedes encolar varias generaciones y explorar los resultados en la Video Gallery.

***

### Storyboard multi-toma

Para secuencias narrativas, usa el modo multi-toma para definir escenas separadas dentro de una sola generación.

1. En el área de prompt, haz clic en **Add Shot** para crear tomas adicionales
2. Escribe un prompt separado para cada toma
3. Establece la duración de cada toma (3–15s cada una, total ≤ 15s)

Los elementos y referencias de escena persisten en todas las tomas automáticamente:

```
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 duración total multi-toma no puede exceder 15 segundos. Por ejemplo, tres tomas de 5 segundos = 15s máximo.
</Warning>

***

### Consejos de prompting

#### Estructura tu prompt

Sigue este patrón para resultados fiables:

```
[sujeto con etiqueta @Element] + [acción] + [entorno con etiqueta @Image] + [movimiento de cámara] + [iluminación/estilo]
```

**Ejemplo:**

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

#### Mantén los prompts entre 50–150 palabras

Los prompts más cortos carecen de detalle. Los prompts más largos introducen contradicciones. Apunta al punto óptimo.

#### Usa lenguaje de cámara simple

El modelo responde mejor a direcciones de cámara sencillas:

| 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 vocabulario consistente

Si describes un personaje con "una chaqueta roja" en un prompt, no cambies a "abrigo carmesí" en el siguiente. El modelo trata palabras diferentes como intenciones diferentes.

#### Coloca las instrucciones de cámara al principio

Pon la dirección de la cámara cerca del principio del prompt para resultados más fiables:

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

***

### Precios de Kling O3

Los modelos Kling O3 Reference to Video usan precios basados en duración:

| Modelo                | Por segundo (sin audio) | Por segundo (con audio) |
| --------------------- | ----------------------- | ----------------------- |
| Kling O3 Pro R2V      | \$0.112                 | \$0.140                 |
| Kling O3 Standard R2V | \$0.112                 | \$0.140                 |

**Ejemplo:** un vídeo de 10 segundos con audio = 10 × $0.14 = **$1.40\*\*

Usa la [API de cotización de vídeo](https://docs.venice.ai/api-reference/endpoint/video/quote) para el precio exacto antes de generar.

***

### Uso de la API de Kling O3

Kling O3 Reference to Video también está disponible vía la API de Venice. Consulta la [API de cola de vídeo](https://docs.venice.ai/api-reference/endpoint/video/queue) para detalles 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 de elemento

Cada elemento del array `elements` acepta:

| Campo                  | Tipo      | Obligatorio | Descripción                                                                               |
| ---------------------- | --------- | ----------- | ----------------------------------------------------------------------------------------- |
| `frontal_image_url`    | string    | **Sí**      | URL de imagen frontal clara                                                               |
| `reference_image_urls` | string\[] | No          | URLs de ángulos adicionales (1–3). Si se omite, la imagen frontal se usa como referencia. |

<Note>
  La API también admite `video_url` para elementos basados en vídeo, pero esto no está disponible actualmente en la UI de Video Studio.
</Note>

***

### Resolución de problemas de Kling O3

| Problema                                            | Causa probable                                           | Solución                                                                                             |
| --------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Botón Generate desactivado                          | No se proporcionaron entradas visuales                   | Añade al menos una entrada visual: frame inicial, elemento o imagen de referencia de escena          |
| Error "Number of images exceeds the limit"          | Demasiadas entradas combinadas                           | El total de primer frame + último frame + elementos + imágenes de escena debe ser ≤ 7                |
| La cara del personaje cambia entre tomas            | Imagen frontal diferente o ausente                       | Usa la misma imagen frontal de forma consistente, mantén la descripción idéntica                     |
| El movimiento de cámara parece aleatorio            | Instrucciones de cámara múltiples o conflictivas         | Usa una única instrucción de cámara, ponla al principio del prompt                                   |
| El estilo cambia entre generaciones                 | Referencias de escena inconsistentes o estilos mezclados | Reutiliza las mismas imágenes de escena, mantén las palabras clave de estilo consistentes            |
| Los elementos se mezclan en escenas multi-personaje | Instrucciones espaciales vagas                           | Sé explícito sobre la posición de cada elemento: "primer plano izquierda", "entrando por la derecha" |
| El fondo se ve distorsionado                        | Imagen de referencia de escena desordenada o compleja    | Usa imágenes de referencia de escena limpias y de alta calidad                                       |
| El movimiento se ve antinatural                     | Demasiadas acciones en un prompt                         | Simplifica la acción, usa duración más corta, una acción por toma                                    |

<Tip>
  Prueba con un clip de 3–5 segundos antes de comprometerte con duraciones más largas. Los clips más cortos mantienen mejor consistencia y te permiten iterar más rápido.
</Tip>

***

## Grok Imagine Reference to Video

Grok Imagine R2V toma un enfoque más simple que Kling O3. En lugar de Elements estructurados con separación de imagen frontal/referencia, subes **imágenes de referencia planas** y las refieres directamente en tu prompt usando `@Image1`, `@Image2`, etc. El modelo incorpora esos sujetos al vídeo generado.

### Cómo funciona

1. Sube **1–7 imágenes de referencia** — fotos de personajes, objetos o escenas que quieras en el vídeo
2. Escribe un prompt que describa el vídeo, usando `@Image1`, `@Image2`, etc. para referenciar imágenes específicas
3. El modelo genera un vídeo incorporando esas referencias

Si no incluyes etiquetas `@Image` en tu prompt, todas las imágenes subidas se referencian automáticamente.

### Ajustes

| Ajuste       | Opciones                            | Predeterminado |
| ------------ | ----------------------------------- | -------------- |
| Aspect Ratio | 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16 | 16:9           |
| Resolución   | 480p, 720p                          | 480p           |
| Duración     | 5s, 8s, 10s                         | 8s             |

<Note>
  Grok Imagine R2V no admite generación de audio, modo multi-toma ni Elements. Para esas funciones, usa Kling O3 R2V.
</Note>

### Guía paso a paso (Video Studio)

#### 1. Selecciona el modelo

Ve a [venice.ai/video](https://venice.ai/video). En el Model Browser, selecciona **Grok Imagine R2V**.

#### 2. Sube imágenes de referencia

Haz clic en **References** en la barra de herramientas de entrada (o usa el menú +) para abrir el panel de imágenes de referencia. Sube 1–7 imágenes de los personajes, objetos o escenas que quieras en el vídeo.

Cada imagen se etiqueta automáticamente como `@Image1`, `@Image2`, etc. en el orden en que las subes (de izquierda a derecha).

#### 3. Escribe tu prompt

Describe el vídeo que quieres. Usa etiquetas `@Image` para referenciar imágenes específicas:

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

Escribe `@` en el campo de prompt para ver un menú de autocompletado de las referencias de imagen disponibles.

<Tip>
  Si omites las etiquetas `@Image` por completo, el backend antepone automáticamente referencias a todas las imágenes subidas. Esto es útil cuando quieres que se usen todas las imágenes sin especificar cuál es cuál.
</Tip>

#### 4. Configura los ajustes y genera

Abre **Video Settings** para ajustar aspect ratio, resolución y duración. Haz clic en **Generate Video**.

### Precios de Grok Imagine R2V

Grok Imagine R2V usa precios basados en duración y resolución:

| Resolución | Por segundo |
| ---------- | ----------- |
| 480p       | \~\$0.063   |
| 720p       | \~\$0.088   |

**Ejemplo:** un vídeo de 8 segundos a 480p = 8 × $0.063 = **~$0.50\*\*

<Note>
  Grok Imagine cobra una tarifa de moderación de contenido por los vídeos generados, incluso si el vídeo es rechazado. Esto se refleja en el coste de créditos mostrado antes de generar.
</Note>

### Uso de la API de 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 de la API

| Campo                | Tipo      | Obligatorio | Descripción                                                     |
| -------------------- | --------- | ----------- | --------------------------------------------------------------- |
| `model`              | string    | **Sí**      | Debe ser `grok-imagine-reference-to-video`                      |
| `prompt`             | string    | **Sí**      | Prompt de texto con referencias opcionales `@Image1`, `@Image2` |
| `referenceImageUrls` | string\[] | **Sí**      | 1–7 URLs de imagen o data URLs                                  |
| `duration`           | string    | No          | `"5"`, `"8"` (predeterminado) o `"10"`                          |
| `aspect_ratio`       | string    | No          | p. ej., `"16:9"` (predeterminado), `"9:16"`, `"1:1"`            |
| `resolution`         | string    | No          | `"480p"` (predeterminado) o `"720p"`                            |

<Note>
  Grok Imagine R2V no usa los campos `elements`, `image_urls` ni `imageUrl`. Todas las imágenes de referencia se pasan vía `referenceImageUrls`.
</Note>

### Resolución de problemas de Grok Imagine R2V

| Problema                                          | Causa probable                                         | Solución                                                                                                                        |
| ------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| Botón Generate desactivado                        | No se subieron imágenes de referencia                  | Sube al menos 1 imagen de referencia                                                                                            |
| Error "At least one reference image is required"  | `referenceImageUrls` está vacío o ausente              | Proporciona al menos una URL de imagen en `referenceImageUrls`                                                                  |
| Imagen incorrecta asociada a la etiqueta `@Image` | El orden de las imágenes no coincide con las etiquetas | `@Image1` corresponde a la primera imagen en tu orden de subida (de izquierda a derecha). Reordena las subidas si es necesario. |
| El sujeto no aparece en el vídeo                  | Demasiadas referencias sin etiquetas explícitas        | Usa etiquetas `@Image` en tu prompt para ser explícito sobre qué imágenes usar                                                  |
| Salida de baja calidad                            | Usando resolución 480p                                 | Prueba 720p para mayor calidad (cuesta más)                                                                                     |
| El vídeo es demasiado corto                       | La duración predeterminada es 8s                       | Establece duración en `"10"` para vídeos más largos                                                                             |