Tutorial de la API de imágenes de referencia de Veo: De los recursos a los vídeos

AI Overview

¿Cuántas imágenes de referencia puede utilizar la API de Veo?

Veo 3.1 acepta hasta tres imágenes de referencia por persona, personaje o producto. Utilice un conjunto pequeño y coherente que muestre claramente la identidad, los materiales y la forma, en lugar de tres composiciones no relacionadas entre sí.

¿Son las imágenes de referencia lo mismo que los fotogramas inicial y final?

No. referenceImages guía la coherencia del sujeto o del estilo, mientras que image establece el primer fotograma y lastFrame limita el fotograma final. Elija uno de estos modos según qué elemento deba permanecer fijo.

¿Qué modelo de Veo admite imágenes de referencia?

La documentación actual de Gemini API de Google enumera las imágenes de referencia para Veo 3.1 y Veo 3.1 Fast, pero no para Veo 3.1 Lite ni para Veo 3.0. Las generaciones basadas en imágenes de referencia utilizan una duración de ocho segundos.

¿Qué debe guardar una integración de la API?

Guarde los identificadores de los recursos de entrada, el indicador normalizado, el modelo y la configuración, el nombre de la operación, el archivo final y el resultado de la revisión. Este registro permite reproducir un intento fallido, evitando así que cada reintento se convierta en una mera conjetura.

Elija el modo de referencia antes de codificar

La tarea práctica detrás de este tutorial de la API de imágenes de referencia de Veo no consiste únicamente en enviar datos codificados en base64. Los desarrolladores deben saber qué tipo de control visual corresponde a cada plano, qué campos van asociados entre sí y cómo recuperarse cuando la salida omite un detalle del producto o se desvía del personaje.

Un nuevo concepto de conjunto de referencias creado específicamente para esta guía. El jinete, la chaqueta color azafrán, las gafas ámbar y la motocicleta cobalto proporcionan anclajes claros de continuidad; no se presenta como una referencia de rendimiento de Veo.

Comience seleccionando uno de los tres modos siguientes:

Esta diferencia es fundamental. Un retrato de personaje en referenceImages sirve como orientación, no como una promesa de que el primer fotograma renderizado reproduzca fielmente ese retrato píxel a píxel. Por el contrario, una imagen inicial image bloquea la composición inicial, pero no ofrece tres vistas independientes de la identidad. No mezcle conceptos en el indicador y luego culpe a la API por aplicar la restricción equivocada.

Según la tabla actual de Gemini API de Google, referenceImages admite hasta tres objetos VideoGenerationReferenceImage en Veo 3.1 y Veo 3.1 Fast. Veo 3.1 Lite no admite este campo. Una solicitud basada en imágenes de referencia genera un único vídeo, utiliza una duración de ocho segundos, admite formatos horizontal o vertical, y puede generar resoluciones de 720p, 1080p o 4K en las rutas completas de Veo 3.1. Una mayor resolución incrementa la latencia y el costo, por lo que debe validar el contrato del plano antes de escalar la entrega.

Para una explicación más amplia a nivel de interfaz antes de implementar el punto final, consulte la guía de flujo de Google y del flujo de trabajo de Veo.

Preparar las imágenes de referencia y el indicador

Crear un conjunto coherente de recursos

Utilice referencias que coincidan en cuanto a identidad. Un paquete útil de tres imágenes podría incluir una vista limpia del rostro y la vestimenta, una vista de la geometría del producto y un pequeño accesorio que deba conservarse. Mantenga compatibles la temperatura de color, la distorsión de la lente y las proporciones. Si una imagen muestra una motocicleta cobalto y otra muestra un chasis diferente en tono azul marino, el indicador no podrá decidir de forma fiable cuál geometría es la canónica.

Referencia de personaje: examine la forma del rostro, el contorno del corte de pelo corto, los paneles de la chaqueta y las lentes ámbar. Una referencia legible resulta más útil que un retrato impactante pero poco claro.

Referencia de producto: se observa claramente la geometría completa de las ruedas, el contorno del bastidor, los paneles cobalto, la chaqueta y las gafas bajo una luz neutra tras la lluvia.

Preprocese las imágenes antes de realizar la solicitud pagada. Confirme el tipo MIME, rechace los archivos vacíos, decodifique una vez para detectar corrupción y conserve la relación de aspecto original, salvo que su canal de procesamiento realice recortes deliberados. Almacene una suma de comprobación y un identificador interno del recurso. La codificación en base64 aumenta el tamaño de la solicitud, por lo que evite codificar repetidamente versiones maestras excesivamente grandes cuando una versión derivada correctamente dimensionada conserve todos los detalles visibles.

Redactar un indicador consciente de la preservación

Un buen indicador explica a Veo qué sucede y qué elementos deben mantenerse estables. Utilice este orden reutilizable:

Plano medio de seguimiento. El jinete de cabello plateado, vestido con una chaqueta color azafrán, conduce la motocicleta cobalto mate por una carretera costera mojada al amanecer. Presérvese su rostro, el contorno del corte de pelo corto, las gafas con visor ámbar, los paneles de la chaqueta, la geometría del cuerpo de la motocicleta, el número de ruedas y el acabado cobalto. Las salpicaduras del océano se mueven de forma natural; la cámara sigue una trayectoria paralela sin orbitar. Sonido ambiental nativo del viento, de los neumáticos y de las olas distantes; sin diálogo, sin texto ni logotipos.Nombre las referencias según sus rasgos visibles, no según los nombres de archivo. Mantenga una acción principal y un movimiento de cámara por toma de ocho segundos. Órdenes contradictorias, como «cámara fija» y «órbita rápida», generan un problema de coordinación que ninguna imagen de referencia puede resolver. La guía de indicaciones para conversión de imagen a video presenta un patrón compacto sujeto–acción–cámara–conservación que puede reutilizar.

Enviar una solicitud Veo 3.1

Crear referencias de activos en JavaScript

Con la versión actual de @google/genai (SDK), represente cada imagen preparada como un objeto que contenga imageBytes y mimeType, y luego envuélvala con referenceType: 'asset'. El SDK lee la clave de API desde su entorno; manténgala en el servidor, nunca en el cliente JavaScript.

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});
const assets = [riderImage, motorcycleImage, glassesImage].map((image) => ({
  image,
  referenceType: 'asset',
}));

let operation = await ai.models.generateVideos({
  model: 'veo-3.1-generate-preview',
  prompt,
  config: {
    referenceImages: assets,
    aspectRatio: '16:9',
    durationSeconds: 8,
    resolution: '720p',
  },
});

Los nombres de campo pueden diferir entre las superficies Gemini API y Vertex AI, así que fije la versión del SDK y valide contra la documentación oficial del punto final que realmente implemente. No copie la estructura JSON de un contenedor de terceros en un punto final de Google. Registre un manifiesto de solicitud con datos sensibles redactados, en lugar de la carga completa en base64.

Use resolución 720p para la primera fase de aceptación. Tras aprobar identidad, movimiento, cámara y audio, repita la configuración aprobada a la resolución requerida para la entrega final. Si su aplicación enruta solicitudes entre distintos proveedores, la guía sobre agregadores frente a APIs directas explica por qué un registro de trabajo normalizado es más fiable que la memoria de la interfaz de usuario específica de cada proveedor.

Consultar, descargar y almacenar la salida

La generación de videos Veo es asincrónica. La llamada inicial devuelve una operación de larga duración, no el archivo MP4 finalizado. Consulte mediante el nombre de la operación con un intervalo razonable, deténgase tras un tiempo de espera acotado y conserve el ID de la operación para que, si se reinicia un trabajador, este pueda reanudarla en lugar de enviar un trabajo duplicado.

while (!operation.done) {
  await new Promise((resolve) => setTimeout(resolve, 10_000));
  operation = await ai.operations.getVideosOperation({ operation });
}

const generated = operation.response.generatedVideos[0];
await ai.files.download({
  file: generated.video,
  downloadPath: `outputs/${jobId}.mp4`,
});

Google conserva actualmente los videos generados en sus servidores durante dos días, así que descárguelos de inmediato a un almacenamiento bajo su control. Verifique que el archivo exista, tenga una longitud distinta de cero, se decodifique correctamente como video y coincida con la duración esperada. Guarde un fotograma de portada para revisión, pero nunca considere dicho fotograma como prueba de que todo el movimiento sea correcto.

Ejemplo cinematográfico de video Veo 3.1 para inspección completa del clip

Observe el clip completo para evaluar coherencia de identidad, entorno, cámara y audio. Un archivo en movimiento revela fallos que un solo fotograma atractivo podría ocultar.

Validar coherencia y gestionar errores

Revisar con una cuadrícula de aceptación fija

Inspeccione cada resultado a velocidad normal y nuevamente alrededor del movimiento más complejo. Registre sistemáticamente «aprobado», «revisar» o «rechazar» aplicando siempre los mismos criterios:

Esta composición alternativa modifica el momento y el encuadre, pero preserva los mismos anclajes de continuidad. Use este tipo de fotograma para evaluar si la identidad del activo sobrevive a un cambio de escena.

Si todas las salidas pierden la misma característica, probablemente la jerarquía de referencias o indicaciones esté equivocada. Si los fallos varían aleatoriamente, mantenga fijas las entradas y vuelva a ejecutar antes de reescribirlo todo. Si la composición debe finalizar exactamente en una imagen diseñada, cambie a image más lastFrame, en lugar de añadir más lenguaje de conservación a referenceImages.

Salida de movimiento de producto Seedance para comparar geometría y comportamiento controlado de la cámara

Este es un modelo y tipo de toma diferentes, incluido como ejemplo real de revisión de movimiento, no como referencia de rendimiento para Veo. Aplique el mismo criterio de geometría y cámara.

Distinga claramente los errores del proveedor de los fallos creativos. Errores de autenticación, cuota agotada, MIME no válido, configuración no admitida, filtrado de seguridad, tiempo de espera agotado o clips completados pero inutilizables requieren respuestas distintas. Vuelva a intentar automáticamente únicamente errores transitorios de transporte o del servicio. Una indicación rechazada o un resultado visual deficiente deben devolverse a revisión humana, no entrar en un bucle infinito de pagos.Antes de la exportación final, confirme la frecuencia de entrega con la guía de velocidad de fotogramas para vídeos generados por IA, ya que la velocidad de fotogramas generada (24 fps) y la configuración de entrega en la plataforma están relacionadas, pero no son decisiones intercambiables.

Integrelo en un flujo de trabajo Seedance Agent

La API sin procesar de Veo es adecuada cuando un desarrollador ya gestiona el almacenamiento de activos, el control de versiones de los prompts, la supervisión de operaciones, las aprobaciones y las políticas de reintento. Seedance Agent resulta útil cuando la tarea real abarca más de una llamada: transformar un briefing en una lista de planos, asignar roles de referencia, seleccionar un modelo compatible por plano, revisar las salidas reales y volver a ejecutar únicamente los segmentos fallidos.

Para la secuencia del motociclista, un agente puede registrar el retrato, la motocicleta y las gafas una sola vez; crear un plano de seguimiento costero y un cierre en «hora azul» como trabajos independientes; mantener alineadas sus reglas de conservación; y exponer ambos clips para su aprobación. La API sigue siendo la capa de generación, mientras que el agente gestiona el estado de producción. Esto reduce las solicitudes duplicadas accidentales y evita que una edición tardía del prompt modifique silenciosamente el conjunto canónico de activos.

Mida el costo por segundo aprobado, no por solicitudes completadas. Compare Veo 3.1 con otras vías según estabilidad de identidad, finalizaciones utilizables, tiempo de revisión y número de reintentos, utilizando la comparación entre Seedance 2.5 y Veo 3.1. El objetivo no es forzar todos los planos a través de un único modelo, sino entregar una secuencia coherente con el menor número posible de revisiones evitables.

Conclusión

Una integración fiable de la API de imágenes de referencia de Veo comienza eligiendo el modo de control adecuado, preparando hasta tres referencias de activos coherentes, redactando un único prompt claro sobre movimiento y conservación, enviando una solicitud válida de Veo 3.1, persistiendo la operación de larga duración, descargando los resultados antes de que expire el período de retención y revisando el clip completo con una rúbrica fija. Mantenga los reintentos transitorios de la API separados de los reintentos creativos, y cambie a la interpolación entre el primer y el último fotograma cuando los puntos finales exactos sean más importantes que la orientación flexible de los activos; cuando el proyecto requiera planificación de planos, referencias compartidas, enrutamiento de modelos, aprobaciones y reintentos selectivos alrededor de la llamada a la API, inicie el flujo de trabajo con Seedance Agent →