Generación de vídeo con Veo 3.1 API: fotogramas, referencias, 4K y sondeo

Veo 3.1 ingresó a la API de Gemini, admite texto, imágenes y videos existentes como entrada y genera videos con audio de forma nativa. En lugar de una interfaz normal que devuelve MP4 sincrónicamente, primero crea una operación de larga duración, luego sondea el estado y descarga los resultados. Este artículo organiza el código según este modelo asincrónico, al tiempo que explica las limitaciones entre el primer y el último fotograma, imágenes de referencia, extensiones de vídeo, resolución y duración.

Elija primero Veo 3.1, Fast o Lite

Actualmente ofrece oficialmente las rutas Veo 3.1, Veo 3.1 Fast y Veo 3.1 Lite. La versión estándar es adecuada para imágenes consistentes, tomas complejas y experimentos de alta calidad. La versión rápida es más adecuada para la vista previa interactiva y la detección por lotes de palabras clave. Lite está orientado a un menor costo y una producción más rápida, pero es posible que el conjunto de funciones no sea el mismo que el de la resolución más alta. Es posible que el modelo aún esté en versión preliminar y que el sistema de producción deba bloquear la ID del modelo y aceptar los cambios en los campos de la interfaz. No escriba simplemente “Veo 3.1” en la consola, el código debe usar el nombre completo del modelo que figura actualmente en la documentación oficial.

Las combinaciones de parámetros son más importantes que los parámetros individuales

Veo 3.1 está disponible en 4, 6 u 8 segundos. Normalmente se requieren 8 segundos cuando se utilizan extensiones de vídeo o de referencia de 1080p, 4K. La relación de aspecto admite 16:9 y 9:16. Actualmente, la extensión de vídeo solo produce 720p. Se genera un vídeo por solicitud. La velocidad de fotogramas es de 24 fps. seed mejora la similitud pero no garantiza una certeza total. Verificar la matriz de parámetros antes de enviar puede reducir la cantidad de minutos que se deben esperar antes de recibir una falla.

Prepare la clave API y el entorno Python

Cree un proyecto en Google AI Studio con una clave API de Gemini. La clave solo contiene variables de entorno:

1

$env:GEMINI_API_KEY = Read-Host "Gemini API key"

Cree un entorno virtual independiente:

1
2
3
4

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install google-genai pillow

Verifique la versión del paquete:

1

python -m pip show google-genai

Cuando la API de vista previa cambia, la información de la versión es más valiosa para la resolución de problemas que “todavía se ejecutó ayer”.

Primera solicitud de video generada por texto

La siguiente estructura se basa en la interfaz actual del SDK oficial. El ID del modelo debe verificarse con el documento antes de la ejecución:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

import os
import time
from pathlib import Path

from google import genai
from google.genai import types

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt=(
        "A quiet railway platform at dawn, light fog, "
        "slow dolly movement, realistic ambient sound, no text"
    ),
    config=types.GenerateVideosConfig(
        aspect_ratio="16:9",
        resolution="720p",
        duration_seconds=4,
    ),
)

while not operation.done:
    print("waiting", operation.name)
    time.sleep(10)
    operation = client.operations.get(operation)

video = operation.response.generated_videos[0].video
client.files.download(file=video)
video.save("veo-output.mp4")
print(Path("veo-output.mp4").resolve())

El campo SDK puede actualizarse con vista previa. Si el atributo no existe, primero consulte el ejemplo oficial correspondiente a la versión instalada.

Por qué el intervalo de sondeo no debería ser demasiado corto

Generar un video lleva más tiempo que una respuesta de texto. Sondear cada segundo no hará que el video se complete antes, pero solo aumentará la probabilidad de solicitudes de API y limitación. El ejemplo oficial de REST utiliza un intervalo de 10 segundos, que es un punto de partida razonable. Las tareas de producción pueden utilizar un retroceso exponencial, pero establezca el intervalo máximo y el tiempo de espera total. Guarde el nombre de la operación en la base de datos y podrá continuar consultando después de reiniciar el proceso. No deje simplemente el objeto de operación en la memoria.

Guarde el estado de la tarea en lugar de bloquear una solicitud HTTP

Después de que la aplicación web recibe la solicitud de generación, primero devuelve su propio ID de trabajo. El trabajador en segundo plano envía la operación Veo y guarda el mapeo:

1
2
3
4
5
6
7

{
  "job_id": "video_20260728_001",
  "operation_name": "operations/example",
  "status": "running",
  "model": "veo-3.1-generate-preview",
  "created_at": "2026-07-28T12:00:00Z"
}

El front-end consulta su propio punto final de trabajo sin exponer directamente la clave Gemini o los datos de operación completos. Después de que el trabajador falle, lea operation_name y continúe sondeando.

El vídeo de generación de imágenes utiliza el primer fotograma

El primer fotograma determina la composición del vídeo. Elija imágenes con sujetos claros, bordes intactos y sin marcas de agua ni texto innecesario.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

from PIL import Image

first_frame = Image.open("first-frame.png")

operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt="The camera slowly moves closer while leaves sway in the wind",
    image=first_frame,
    config=types.GenerateVideosConfig(
        aspect_ratio="16:9",
        resolution="720p",
        duration_seconds=8,
    ),
)

Cuando la relación de aspecto de la imagen es demasiado diferente de la salida, el modelo necesita recortar o rellenar los bordes. Procesar primero el lienzo localmente a 16:9 o 9:16 normalmente dará como resultado resultados más controlables.

El primer cuadro más el último cuadro se utilizan para la transición de interpolación

Veo 3.1 admite la especificación de pantallas de inicio y finalización. El último fotograma no es una imagen de referencia independiente, sino la imagen a la que eventualmente pasará el vídeo.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

first_frame = Image.open("start.png")
last_frame = Image.open("end.png")

operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt="A smooth cinematic transition from morning to night",
    image=first_frame,
    config=types.GenerateVideosConfig(
        last_frame=last_frame,
        aspect_ratio="16:9",
        resolution="1080p",
        duration_seconds=8,
    ),
)

Cuando la diferencia en las posiciones de los sujetos en las dos imágenes es demasiado grande, el modelo puede deformarse para completar la transición. Alinear primero el ángulo de la cámara, la escala del sujeto y la línea del horizonte es más efectivo que agregar palabras clave.

Imagen de referencia utilizada para mantener el carácter o el producto

Veo 3.1 puede utilizar hasta tres imágenes de referencia de activos. Las imágenes de referencia son excelentes para brindar diferentes perspectivas sobre el mismo personaje, producto o estilo. Si la ropa, los colores y las proporciones de las tres imágenes entran en conflicto entre sí, se reducirá la coherencia. Cuando utilice imágenes de productos, mantenga el contorno completo y evite utilizar el texto de la marca como textura de fondo. Las imágenes de referencia, las solicitudes de 1080p o 4K están sujetas al límite oficial de 8 segundos. La compatibilidad del modelo Lite con el tipo de imagen de referencia correspondiente estará sujeta a la tabla de parámetros actual.

4K no significa cambiar el parámetro 720p a una cadena

4K requiere una ruta Veo 3.1 estándar con un requisito de duración de 8 segundos. Aumenta el tiempo de compilación, el tamaño de descarga y los recursos de posprocesamiento. Primero verifique el metraje en Rápido o 720p, luego genere 4K al pasar palabras clave.

1
2
3
4
5

config = types.GenerateVideosConfig(
    aspect_ratio="16:9",
    resolution="4k",
    duration_seconds=8,
)

La disponibilidad de 4K vertical en los modelos y regiones actuales debe estar sujeta a solicitud de devolución y formulario oficial. No verifique la combinación de parámetros por primera vez antes del envío del lote.

Deje que las palabras clave describan tanto la imagen como el sonido

Veo 3.1 genera audio de forma nativa y las palabras breves pueden describir sonidos ambientales, diálogos y estados de ánimo musicales. Las palabras clave incluyen al menos sujeto, acción, escena, lente, luz y sonido.

1
2
3
4
5

A close-up of a ceramic cup on a wooden table.
Steam rises slowly while rain hits the window behind it.
The camera performs a gentle clockwise orbit.
Warm indoor light, shallow depth of field.
Audio: soft rain, distant thunder, no speech, no music.

“Cinemática” no sustituye el movimiento de la cámara ni las instrucciones de composición. Cuando no se necesita texto, escriba claramente no text, pero aún debe verificar la película terminada.

La extensión de video solo puede usar videos generados por Veo

La entrada extendida es el objeto Video en el resultado generado previamente, no una carga MP4 arbitraria. La extensión utiliza el último segundo, o aproximadamente 24 fotogramas, para continuar la acción. Cuando no hay sonido en el último segundo del vídeo original, la voz normalmente no puede continuar de forma natural. Coloque las acciones y sonidos que desea continuar al final y luego solicite el siguiente párrafo. Actualmente, la salida extendida solo admite 720p. Múltiples expansiones acumularán deriva visual y de audio, y los largometrajes deben gestionar las tomas en el software de edición.

El núcleo de la solicitud REST es el nombre de operación

. Cuando no utilice el SDK, puede llamar a predictLongRunning.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

curl -s \
  "https://generativelanguage.googleapis.com/v1beta/models/veo-3.1-generate-preview:predictLongRunning" \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "instances": [{
      "prompt": "A calm ocean at sunrise, slow aerial shot, natural waves"
    }],
    "parameters": {
      "aspectRatio": "16:9",
      "resolution": "720p",
      "durationSeconds": 4,
      "sampleCount": 1
    }
  }'

name en la respuesta se utiliza para consultas posteriores. No coloque claves API en parámetros de consulta de URL o JavaScript de front-end.

Operación REST de sondeo

1
2
3

curl -s \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  "https://generativelanguage.googleapis.com/v1beta/${OPERATION_NAME}"

Continúe esperando cuando done sea false. Después de que done sea true, verifique si es response o error. No asuma que completarlo es un éxito garantizado. Guarde la estructura de error completa y solicite el ID para evitar mostrar simplemente “Error de compilación”.

La URL de descarga aún requiere la clave API

La respuesta de finalización proporciona el URI del vídeo generado. Utilice -L para seguir la redirección:

1
2
3
4

curl -L \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -o veo-result.mp4 \
  "${VIDEO_URI}"

Verifique el tipo de archivo y la duración después de la descarga:

1
2
3

ffprobe -v error \
  -show_entries format=duration,size \
  -of json veo-result.mp4

No utilice simplemente la extensión del archivo para determinar si la descarga se realizó correctamente; el JSON incorrecto también puede guardarse como .mp4.

Establezca la clave idempotente

para la tarea de compilación Después de que el cliente agote el tiempo de espera, no vuelva a enviar la misma palabra de aviso inmediatamente. Primero verifique si su tabla de trabajos ya tiene una operación. Genere claves idempotentes con ID de usuario, hash de material, parámetros e ID de solicitud comercial. Solo se permite crear una operación ascendente para la misma clave. Esto evita que un clic genere dos videos facturables.

El control de costos comienza con la generación de dos etapas

La primera etapa utilizó Rápido, 720p y 4 segundos para seleccionar las palabras clave. La segunda etapa solo mejora las composiciones seleccionadas a 8 segundos, 1080p o 4K. Registre el modelo, resolución, duración, funcionamiento y tamaño del archivo final. Calcule el costo basándose en una producción exitosa, no solo en el precio unitario API único. Las fallas en la moderación de contenido, las fallas de parámetros y las cancelaciones de usuarios también se tienen en cuenta en el presupuesto.

Errores de parámetros comunes

4K con 4 segundos violaría el requisito de duración. Las solicitudes de vídeo extendido de 1080p violan el límite de resolución extendida. Se rechazarán las imágenes de referencia que superen las tres. El primer y último fotograma solo proporcionan el último fotograma y la interpolación no se puede formar sin el primer fotograma. Si el ID del modelo de vista previa caduca, se devolverá que el modelo no existe. Los límites de generación de caracteres también pueden variar según la región y el modo de entrada.

401, 403 y 429 se procesan por separado

401 primero verifica si la clave ha ingresado al proceso actual. 403 Comprueba los permisos del proyecto, las regiones, el acceso al modelo y las políticas organizativas. 429 Comprueba las solicitudes por minuto, la simultaneidad y las cuotas del proyecto. No vuelva a intentarlo con el retroceso infinito 403. Los errores de cuota se deben poner en cola o se debe solicitar al usuario que vuelva a intentarlo más tarde.

Realice una verificación de la calidad de los medios después de descargar

Verifique el formato del contenedor, la duración, la resolución, la velocidad de fotogramas y la pista de audio.

1
2
3
4

ffprobe -v error \
  -show_streams \
  -show_format \
  -of json veo-result.mp4 > veo-result.json

Luego extraiga el primer fotograma, el fotograma medio y el último fotograma:

1
2
3

ffmpeg -i veo-result.mp4 \
  -vf "select='eq(n,0)+eq(n,96)+eq(n,191)'" \
  -vsync 0 frame-%02d.png

El número de fotograma debe ajustarse según la duración real y los fps.

Los derechos de seguridad y contenido no se pueden dejar en manos de los parámetros

Confirme los derechos de uso antes de cargar imágenes de personas, marcas y productos. No genere material destinado a engañar, acosar o suplantar. Las imágenes originales, las palabras clave y los vídeos generados pueden contener información personal. Establezca el período de retención para archivos temporales y no almacene imágenes en base64 en registros. Los productos orientados al usuario también requieren rutas de moderación, generación de informes y eliminación de contenido. Todas las imágenes y videos generados estarán sujetos a las marcas de agua y políticas de la plataforma.

Aceptación de la tarea antes de conectarse

• El nombre de la operación se puede conservar.
• El trabajador puede continuar sondeando después de reiniciar.
• La descarga sigue la redirección y lleva la autenticación.
• Las combinaciones de parámetros de 720p, 1080p y 4K se probaron por separado.
• El número de primeros y últimos fotogramas e imágenes de referencia alcanza el límite.
• Las solicitudes repetidas no se facturarán nuevamente.
• ffprobe puede confirmar transmisiones de audio y video.
• La tarea fallida conserva la estructura del error sin guardar la clave.
• Los usuarios pueden eliminar materiales y resultados generados.

Las dificultades de ingeniería de la API de Veo 3.1 se encuentran principalmente en tareas asincrónicas, matriz de parámetros y gestión de resultados. Primero ejecute el proceso de 720p de 4 segundos y luego agregue el primer y último fotograma, las imágenes de referencia y 4K. Será más fácil localizar el problema que enviar todos los parámetros avanzados a la vez.

Información oficial

• Google: Generando vídeos usando Veo 3.1
• Google: descripción del modelo Veo 3.1