Habilidad de Comprensión de Video
Esta habilidad proporciona funcionalidad especializada de comprensión de video utilizando el paquete z-ai-web-dev-sdk, permitiendo a los modelos de IA analizar, describir y extraer información de contenido de video, incluyendo movimiento, secuencias temporales y cambios de escena.
Ruta de la Habilidad
Ubicación de la Habilidad: {project_path}/skills/video-understand
esta habilidad se encuentra en la ruta anterior en tu proyecto.
Scripts de Referencia: Hay scripts de prueba de ejemplo disponibles en el directorio {Skill Location}/scripts/ para pruebas rápidas y referencia. Consulta {Skill Location}/scripts/video-understand.ts para un ejemplo funcional.
Resumen
La Comprensión de Video se enfoca específicamente en el análisis de contenido de video, proporcionando capacidades para:
- Comprensión y descripción de escenas de video
- Detección de acciones y movimientos
- Análisis de secuencias temporales
- Detección de eventos en videos
- Resumen de contenido de video
- Detección de cambios de escena
- Seguimiento de personas y objetos a través de fotogramas
- Análisis de contenido audiovisual (cuando sea aplicable)
IMPORTANTE: z-ai-web-dev-sdk DEBE usarse solo en código backend. Nunca lo uses en código del lado del cliente.
Prerrequisitos
El paquete z-ai-web-dev-sdk ya está instalado. Impórtalo como se muestra en los ejemplos a continuación.
Uso de CLI (Para Tareas Simples)
Para tareas rápidas de análisis de video, puedes usar la CLI de z-ai en lugar de escribir código. Esto es ideal para descripciones de video simples, pruebas o automatización.
Análisis de Video Básico
# Analizar un video desde una URL
z-ai vision --prompt "Resume lo que sucede en este video" --image "https://example.com/video.mp4"
# Nota: Usa la bandera --image también para URLs de video
z-ai vision -p "Describe los eventos clave" -i "https://example.com/presentation.mp4"
Analizar Videos Locales
# Analizar un archivo de video local
z-ai vision -p "¿Qué actividades se muestran en este video?" -i "./recording.mp4"
# Guardar respuesta en un archivo
z-ai vision -p "Proporciona un resumen detallado" -i "./meeting.mp4" -o summary.json
Análisis de Video Avanzado
# Comprensión de escenas complejas con razonamiento
z-ai vision \
-p "Analiza este video e identifica: 1) Eventos principales, 2) Personas y sus acciones, 3) Línea de tiempo de momentos clave" \
-i "./event.mp4" \
--thinking \
-o analysis.json
# Detección de acciones
z-ai vision \
-p "Identifica todas las acciones realizadas por personas en este video" \
-i "./sports.mp4" \
--thinking
Salida en Streaming
# Transmitir el análisis de video
z-ai vision -p "Describe el contenido de este video" -i "./video.mp4" --stream
Parámetros de CLI
--prompt, -p <texto>: Requerido - Pregunta o instrucción sobre el video--image, -i <URL o ruta>: Opcional - URL del video o ruta del archivo local (a pesar del nombre, también funciona para videos)--thinking, -t: Opcional - Habilita el razonamiento encadenado para análisis complejos (deshabilitado por defecto)--output, -o <ruta>: Opcional - Ruta del archivo de salida (formato JSON)--stream: Opcional - Transmite la respuesta en tiempo real
Formatos de Video Soportados
- MP4 (.mp4) - Formato más ampliamente soportado
- AVI (.avi) - Audio Video Interleave
- MOV (.mov) - Formato QuickTime
- WebM (.webm) - Formato optimizado para web
- MKV (.mkv) - Formato Matroska
- FLV (.flv) - Formato Flash Video
Cuándo Usar CLI vs SDK
Usa CLI para:
- Resúmenes de video rápidos
- Análisis de video puntual
- Pruebas de capacidades de comprensión de video
- Scripts de automatización simples
- Generación de descripciones de video
Usa SDK para:
- Conversaciones de múltiples turnos sobre videos
- Canalizaciones complejas de procesamiento de video
- Aplicaciones de producción con manejo de errores
- Integración personalizada con lógica de procesamiento de video
- Procesamiento por lotes de video con flujos de trabajo personalizados
Enfoque Recomendado
Para un mejor rendimiento y fiabilidad con videos locales, considera:
- Subir videos a un CDN y usar URLs
- Para videos más cortos, convertir fotogramas clave a imágenes para un análisis más rápido
- Para videos largos, considerar fragmentar o muestrear en intervalos
Implementación Básica de Comprensión de Video
Análisis de Video Individual
import ZAI from 'z-ai-web-dev-sdk';
async function analyzeVideo(videoUrl, prompt) {
const zai = await ZAI.create();
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{
type: 'text',
text: prompt
},
{
type: 'video_url',
video_url: {
url: videoUrl
}
}
]
}
],
thinking: { type: 'disabled' }
});
return response.choices[0]?.message?.content;
}
// Ejemplos de uso
const summary = await analyzeVideo(
'https://example.com/presentation.mp4',
'Resume los puntos clave presentados en este video'
);
const actionDetection = await analyzeVideo(
'https://example.com/sports.mp4',
'Identifica y describe todas las acciones atléticas realizadas en este video'
);
Comprensión de Escenas de Video
import ZAI from 'z-ai-web-dev-sdk';
async function understandVideoScenes(videoUrl) {
const zai = await ZAI.create();
const prompt = `Analiza este video y proporciona:
1. Resumen general del contenido del video
2. Escenas o segmentos principales (con marcas de tiempo aproximadas si es posible)
3. Personas o personajes clave y sus roles
4. Acciones o eventos importantes en orden cronológico
5. Descripción del entorno y escenario
6. Estado de ánimo o tono general`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'enabled' } // Habilitar para análisis detallado
});
return response.choices[0]?.message?.content;
}
// Uso
const sceneAnalysis = await understandVideoScenes(
'https://example.com/documentary.mp4'
);
Detección de Movimiento y Acciones
import ZAI from 'z-ai-web-dev-sdk';
async function detectActions(videoUrl, specificAction = null) {
const zai = await ZAI.create();
const prompt = specificAction
? `Identifica todas las instancias de "${specificAction}" en este video. Para cada instancia, describe cuándo ocurre y proporciona detalles sobre cómo se realiza.`
: 'Identifica y describe todas las acciones y movimientos significativos en este video. Incluye quién los realiza y cuándo ocurren.';
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}
// Uso
const runningActions = await detectActions(
'https://example.com/sports.mp4',
'corriendo'
);
const allActions = await detectActions(
'https://example.com/activity.mp4'
);
Extracción de Línea de Tiempo de Eventos
import ZAI from 'z-ai-web-dev-sdk';
async function extractTimeline(videoUrl) {
const zai = await ZAI.create();
const prompt = `Crea una línea de tiempo detallada de los eventos en este video:
- Identifica momentos clave y transiciones
- Anota el tiempo aproximado (inicio, medio, final o marcas de tiempo específicas si son visibles)
- Describe lo que sucede en cada punto clave
- Identifica relaciones de causa y efecto entre eventos
Formatea como una lista cronológica.`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}
Clasificación de Contenido de Video
import ZAI from 'z-ai-web-dev-sdk';
async function classifyVideo(videoUrl) {
const zai = await ZAI.create();
const prompt = `Clasifica este contenido de video:
1. Categoría principal (por ejemplo, educativo, entretenimiento, deportes, noticias, tutorial)
2. Subcategoría o género
3. Audiencia objetivo
4. Estilo de contenido (profesional, casual, documental, etc.)
5. Temas o tópicos clave
6. Etiquetas sugeridas (10-15 palabras clave)
Formatea tu respuesta como JSON estructurado.`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'disabled' }
});
const content = response.choices[0]?.message?.content;
try {
return JSON.parse(content);
} catch (e) {
return { rawResponse: content };
}
}
Casos de Uso Avanzados
Conversación de Video de Múltiples Turnos
import ZAI from 'z-ai-web-dev-sdk';
class VideoConversation {
constructor() {
this.messages = [];
}
async initialize() {
this.zai = await ZAI.create();
}
async loadVideo(videoUrl, initialQuestion) {
this.messages.push({
role: 'user',
content: [
{ type: 'text', text: initialQuestion },
{ type: 'video_url', video_url: { url: videoUrl } }
]
});
return this.getResponse();
}
async askFollowUp(question) {
this.messages.push({
role: 'user',
content: [
{ type: 'text', text: question }
]
});
return this.getResponse();
}
async getResponse() {
const response = await this.zai.chat.completions.createVision({
messages: this.messages,
thinking: { type: 'disabled' }
});
const assistantMessage = response.choices[0]?.message?.content;
this.messages.push({
role: 'assistant',
content: assistantMessage
});
return assistantMessage;
}
}
// Uso
const conversation = new VideoConversation();
await conversation.initialize();
const initial = await conversation.loadVideo(
'https://example.com/lecture.mp4',
'¿Cuál es el tema principal de esta conferencia?'
);
const followup1 = await conversation.askFollowUp(
'¿Puedes explicar los conceptos clave mencionados?'
);
const followup2 = await conversation.askFollowUp(
'¿Qué ejemplos se usaron para ilustrar estos conceptos?'
);
Evaluación de Calidad de Video
import ZAI from 'z-ai-web-dev-sdk';
async function assessVideoQuality(videoUrl) {
const zai = await ZAI.create();
const prompt = `Evalúa la calidad de este video:
1. Calidad visual (resolución, claridad, iluminación) - Puntúa 1-10
2. Calidad de audio (si hay audio presente) - Puntúa 1-10
3. Trabajo de cámara (estabilidad, encuadre, composición) - Puntúa 1-10
4. Valor de producción (edición, transiciones, efectos) - Puntúa 1-10
5. Claridad del contenido (¿el mensaje es claro?) - Puntúa 1-10
6. Ritmo (demasiado rápido, demasiado lento, adecuado)
7. Problemas técnicos (artefactos, desenfoque, sincronía de audio, etc.)
8. Calificación general - 1-10
9. Recomendaciones específicas para mejorar
Proporciona retroalimentación detallada para cada criterio.`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}
Moderación de Contenido de Video
import ZAI from 'z-ai-web-dev-sdk';
async function moderateVideo(videoUrl) {
const zai = await ZAI.create();
const prompt = `Revisa este video para moderación de contenido:
1. Verifica si hay contenido inapropiado o sensible
2. Identifica posibles problemas de seguridad
3. Nota cualquier contenido que pueda violar las pautas comunes de la comunidad
4. Evalúa la adecuación por edad
5. Identifica cualquier material protegido por derechos de autor visible (logotipos, marcas, música)
6. Calificación general de seguridad: Seguro / Precaución / Revisión requerida
Proporciona ejemplos específicos para cualquier preocupación identificada.`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}
Generación de Transcripción de Video (Descripción Visual)
import ZAI from 'z-ai-web-dev-sdk';
async function generateVisualTranscript(videoUrl) {
const zai = await ZAI.create();
const prompt = `Genera una transcripción visual detallada de este video:
- Describe lo que sucede en cada escena
- Nota cualquier texto que aparezca en pantalla
- Describe elementos visuales importantes
- Menciona cualquier cambio de escena o transición
- Incluye descripciones de las acciones y expresiones de las personas
Formatea como una narrativa basada en el tiempo (por ejemplo, "Al principio...", "Luego...", "Finalmente...").`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'disabled' }
});
return response.choices[0]?.message?.content;
}
Análisis de Video Deportivo
import ZAI from 'z-ai-web-dev-sdk';
async function analyzeSportsVideo(videoUrl, sport = null) {
const zai = await ZAI.create();
const prompt = sport
? `Analiza este video de ${sport} en detalle:
1. Identifica a los jugadores y sus posiciones
2. Describe jugadas y estrategias clave
3. Anota eventos de puntuación o momentos importantes
4. Evalúa el rendimiento de los jugadores
5. Identifica cualquier violación de reglas o faltas
6. Describe el ritmo y flujo del juego`
: `Analiza este video deportivo:
1. Identifica el deporte que se está jugando
2. Describe las acciones y jugadas clave
3. Anota cualquier puntuación o evento significativo
4. Describe los movimientos y estrategias de los jugadores
5. Evaluación general del juego o partido`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
conte
...
[truncado para traducción]