Los analistas de contenido, investigadores de experiencia de usuario (UX) y especialistas en inteligencia de mercado se enfrentan habitualmente a extensas horas de material audiovisual: sesiones de usabilidad con usuarios, grupos focales, ponencias académicas, llamadas de resultados corporativos y seminarios sectoriales. Tradicionalmente, extraer un registro estructurado de eventos requería un flujo de trabajo fragmentado: transcribir el audio mediante reconocimiento automático del habla (ASR), programar scripts de visión por computadora para detectar transiciones de diapositivas y sincronizar manualmente los códigos de tiempo.
La capacidad de comprensión multimodal nativa de video de Google Gemini transforma por completo este proceso. Gracias a ventanas de contexto masivas (de 1 millón de tokens o más) y una sincronización nativa de imagen y sonido, los modelos Gemini (como Gemini 3.8 Flash, Gemini 3.7 Flash y Gemini 2.5 Pro) procesan archivos de video directamente. Los analistas pueden consultar horas de metraje mediante lenguaje natural, contrastar declaraciones habladas con demostraciones visuales en pantalla y extraer registros cronológicos precisos con marcas de tiempo en formato MM:SS.
Esta guía detalla cómo diseñar un flujo de trabajo profesional utilizando la Files API de Gemini, elegir entre el modo estático y el modo agéntico, aplicar esquemas JSON estrictos y reducir drásticamente los costes de análisis reiterativo mediante el almacenamiento en caché de contexto (Context Caching).
1. Selección del modo de procesamiento: Estático vs. Agéntico
Gemini ofrece dos modos de ejecución para video. Elegir el adecuado es determinante para optimizar el consumo de tokens, la velocidad de respuesta y la precisión analítica.
| Dimensión | Procesamiento estático (Predeterminado) | Comprensión agéntica de video (Agentic Mode) |
|---|---|---|
| Mecanismo | Muestrea fotogramas a intervalos fijos (por defecto 1 FPS) y audio a 1Kbps, cargando todo el contenido en el contexto en una única pasada | Utiliza un bucle interactivo Think-Act-Observe; el modelo inspecciona la línea de tiempo y carga transcripciones, audio o fotogramas bajo demanda |
| Consumo de tokens | ~100 tokens/segundo en baja resolución; ~300 tokens/segundo en alta resolución | Hasta un 88% menos de tokens de entrada en videos largos; el razonamiento computa como tokens de pensamiento y los recursos cargados como tokens de herramienta |
| Tiempo hasta el primer token (TTFT) | Inmediato en clips cortos (<5 minutos) | Ligera latencia inicial debido a los pasos de planificación y llamadas internas a herramientas |
| Escenarios ideales | Auditorías visuales continuas cuadro por cuadro, clips cortos, secuencias rápidas donde cada segundo cuenta | Grabaciones largas (15 a 180 minutos), búsqueda de temas concretos, creación de capítulos y resúmenes de eventos |
| Modelos compatibles | Toda la familia de modelos Gemini | Gemini 3.8 Flash, Gemini 3.7 Flash, 3.6 Flash, 3.5 Flash Lite |
Cuándo utilizar el modo agéntico
Para grabaciones de más de 15 minutos, el modo agéntico ("processing": "agentic") es la opción óptima. En lugar de transferir decenas de miles de fotogramas estáticos al contexto, el modelo examina primero la transcripción de audio para identificar los segmentos relevantes y solo descarga fotogramas de alta resolución cuando necesita verificar evidencia visual (por ejemplo, comprobar un clic en la interfaz o un diagrama en una pizarra). Esto reduce el coste de tokens de entrada hasta en un 66% y mejora la precisión de las respuestas en torno a un 7%.
Cuándo optar por el modo estático
Si la investigación exige un escrutinio visual ininterrumpido sin intervención verbal —como el seguimiento de la mirada, microexpresiones faciales o interacciones sutiles con la interfaz no comentadas en voz alta—, el modo estático garantiza una cobertura temporal exhaustiva. Además, es posible ajustar la frecuencia de muestreo (por ejemplo, fps: 0.5 para capturar un fotograma cada dos segundos), lo que permite analizar hasta 3 horas continuas dentro del límite de 1 millón de tokens.
2. Ingesta de grabaciones extensas mediante la Files API
El envío de video en línea (en base64 dentro de la petición) queda reservado para archivos pequeños de menos de 20MB (o 100MB según el endpoint). Para grabaciones de investigación extensas, se debe utilizar siempre la Files API, que admite archivos de hasta 20GB en planes de pago (2GB en nivel gratuito) y soporta formatos estándar como MP4, MOV, MPEG, WEBM y AVI.
La ingesta consta de dos fases:
- Carga reanudable: Envío del archivo audiovisual al almacenamiento gestionado de Gemini.
- Sondeo de estado: Espera a que el servidor complete la transcodificación y la indexación temporal, momento en el que el estado cambia de
PROCESSINGaACTIVE.
Los archivos permanecen disponibles en el proyecto durante 48 horas sin coste adicional de almacenamiento, permitiendo formular múltiples consultas analíticas sucesivas durante la jornada de trabajo.
3. Ingeniería de prompts y esquemas JSON estructurados
Para integrar las respuestas del modelo en bases de datos o informes analíticos sin fricción, las instrucciones deben imponer pautas temporales y formatos estrictos:
- Formato explícito de marcas de tiempo: Gemini procesa de forma nativa el formato
MM:SS(oHH:MM:SSpara videos de varias horas). Solicite explícitamente marcas de tiempo de inicio y final para cada evento detectado. - Triangulación multimodal: Instruya al modelo para que corrobore las afirmaciones de voz con las evidencias visuales. Por ejemplo: «Verifica si la frustración expresada por el usuario en el minuto 14:20 coincide con un mensaje de error visible en pantalla».
- Imposición de esquemas JSON: Configure
response_mime_type: "application/json"junto con un esquema Pydantic para requerir campos comotimestamp_start,timestamp_end,event_type,summary,visual_evidenceyverbal_quote, eliminando cualquier introducción conversacional innecesaria. - Posición del texto en la petición: Al construir el array de contenidos, coloque siempre el prompt textual después del objeto de video.
4. Implementación práctica completa en Python
El siguiente script en Python ilustra cómo un investigador puede subir una sesión de prueba de usuario de 60 minutos, activar el modo agéntico con ejecución asíncrona en segundo plano (background=True) y obtener un resumen de eventos estructurado:
import time
from google import genai
from google.genai import types
from pydantic import BaseModel, Field
# 1. Inicializar el cliente
client = genai.Client()
# 2. Subir el archivo de video mediante Files API
print("Subiendo grabación de video...")
video_file = client.files.upload(
file="user_research_session_04.mp4",
config={"mime_type": "video/mp4"}
)
# 3. Esperar a que finalice el procesamiento en el servidor
while video_file.state.name == "PROCESSING":
print("El servidor está procesando e indexando el video. Reintentando en 5 segundos...")
time.sleep(5)
video_file = client.files.get(name=video_file.name)
if video_file.state.name == "FAILED":
raise RuntimeError("Error al procesar el archivo de video en el servidor.")
print(f"Video listo en el URI: {video_file.uri}")
# 4. Definir el esquema estructurado de salida
class VideoEvent(BaseModel):
timestamp_start: str = Field(description="Hora de inicio del evento en formato MM:SS")
timestamp_end: str = Field(description="Hora de finalización del evento en formato MM:SS")
event_type: str = Field(description="Categoría: Punto de dolor, Solicitud de función, Error o Discusión")
summary: str = Field(description="Descripción concisa de lo sucedido")
visual_evidence: str = Field(description="Acciones visuales observadas en la pantalla")
verbal_quote: str = Field(description="Declaración verbal textual relevante")
class ResearchSummary(BaseModel):
video_overview: str = Field(description="Resumen ejecutivo de la sesión")
events: list[VideoEvent] = Field(description="Lista cronológica de eventos con marcas de tiempo")
# 5. Ejecutar análisis en modo agéntico con ejecución en segundo plano
# background=True evita caídas de conexión por tiempo de espera en razonamientos profundos
prompt_text = """
Analiza esta grabación de entrevista a usuarios.
Identifica todos los puntos de fricción con la interfaz, sugerencias de mejora y momentos de decisión.
Contrasta las declaraciones orales con las acciones observadas en pantalla.
Devuelve una lista cronológica de eventos con marcas de tiempo exactas en formato MM:SS.
"""
print("Enviando petición de análisis agéntico...")
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=[
{
"type": "video",
"uri": video_file.uri,
"mime_type": video_file.mime_type,
"processing": "agentic" # Habilita la exploración dinámica de la línea de tiempo
},
{
"type": "text",
"text": prompt_text
}
],
response_mime_type="application/json",
response_schema=ResearchSummary,
background=True # Tarea asíncrona en el servidor
)
# 6. Sondear el estado de la tarea en segundo plano
while interaction.status == "in_progress":
print("El modelo está explorando la línea de tiempo y sintetizando la evidencia...")
time.sleep(5)
interaction = client.interactions.get(interaction.id)
print("\n--- Resultados del análisis ---")
print(interaction.output_text)
5. Escalado de consultas cualitativas con Context Caching
En investigación cualitativa, rara vez se realiza una única pregunta por grabación. Habitualmente se requiere extraer el orden del día, evaluar menciones a competidores, analizar la curva emocional del participante y registrar fallos de flujo en consultas independientes.
Repetir la subida y el procesamiento completo de un video de 90 minutos para cada pregunta multiplicaría los costes y los tiempos de espera. La función Context Caching de Gemini resuelve esta limitación:
- Reducción sustancial de costes: Los tokens de entrada almacenados en caché tienen un precio muy inferior (habitualmente entre un 10% y un 20% de la tarifa estándar).
- Respuesta acelerada: Los datos audiovisuales ya están precargados en memoria, lo que reduce de inmediato el tiempo de generación del primer token.
- Implementación: A través de la API
generateContent, el analista crea un objeto de caché con un tiempo de vida definido (TTL, por ejemplo, 2 horas). Las consultas posteriores únicamente hacen referencia acachedContents/<cache-id>, permitiendo a todo el equipo lanzar decenas de preguntas cualitativas sobre la misma grabación con una inversión mínima.
6. Recomendaciones prácticas y prevención de errores
- Prevención de tiempos de espera de red: En videos de más de 15 minutos, el análisis exhaustivo puede prolongarse varios minutos. Las peticiones HTTP sincrónicas corren el riesgo de interrumpirse por cortes de puerta de enlace o caducidad de credenciales (provocando errores como
401 Unauthorized). En la Interactions API, use siemprebackground=True; en la API generateContent, recurra al streaming (stream=True). - Comprobación de la actividad agéntica: Al examinar el objeto de respuesta en modo agéntico, revise
interaction.steps. La presencia de llamadasprocessing_callyprocessing_resultacredita que el modelo inspeccionó de forma activa tramos temporales concretos en lugar de inferir a partir de una visión estática global. - Ajuste de la resolución del medio: Si es crítico leer caracteres pequeños en diapositivas, líneas de código o tablas complejas, configure
media_resolution: "high". Si el objetivo es seguir el hilo de una conversación o una presentación estándar, la resolución baja predeterminada (66 tokens por fotograma) ofrece la mayor velocidad con el menor consumo de tokens. - Tolerancia temporal en marcas de tiempo: Es habitual que la voz de un interlocutor anticipe o retrase levemente la acción en pantalla. Solicitar un intervalo de tiempo (
timestamp_startytimestamp_end) en lugar de un segundo aislado incrementa notablemente la precisión al cortar o revisar el metraje en editores de video.