Skill de Compreensão de Vídeo
Esta skill fornece funcionalidades especializadas de compreensão de vídeo usando o pacote z-ai-web-dev-sdk, permitindo que modelos de IA analisem, descrevam e extraiam informações de conteúdo de vídeo, incluindo movimento, sequências temporais e mudanças de cena.
Caminho da Skill
Localização da Skill: {project_path}/skills/video-understand
esta skill está localizada no caminho acima no seu projeto.
Scripts de Referência: Scripts de teste de exemplo estão disponíveis no diretório {Localização da Skill}/scripts/ para testes rápidos e referência. Veja {Localização da Skill}/scripts/video-understand.ts para um exemplo funcional.
Visão Geral
A Compreensão de Vídeo foca especificamente na análise de conteúdo de vídeo, fornecendo capacidades para:
- Compreensão e descrição de cenas de vídeo
- Detecção de ação e movimento
- Análise de sequência temporal
- Detecção de eventos em vídeos
- Sumarização de conteúdo de vídeo
- Detecção de mudanças de cena
- Rastreamento de pessoas e objetos entre quadros
- Análise de conteúdo audiovisual (quando aplicável)
IMPORTANTE: z-ai-web-dev-sdk DEVE ser usado apenas em código backend. Nunca o use em código do lado do cliente.
Pré-requisitos
O pacote z-ai-web-dev-sdk já está instalado. Importe-o conforme mostrado nos exemplos abaixo.
Uso via CLI (Para Tarefas Simples)
Para tarefas rápidas de análise de vídeo, você pode usar a CLI z-ai em vez de escrever código. Isso é ideal para descrições simples de vídeo, testes ou automação.
Análise Básica de Vídeo
# Analisar um vídeo a partir de uma URL
z-ai vision --prompt "Resuma o que acontece neste vídeo" --image "https://exemplo.com/video.mp4"
# Nota: Use o sinalizador --image também para URLs de vídeo
z-ai vision -p "Descreva os eventos principais" -i "https://exemplo.com/apresentacao.mp4"
Analisar Vídeos Locais
# Analisar um arquivo de vídeo local
z-ai vision -p "Quais atividades são mostradas neste vídeo?" -i "./gravacao.mp4"
# Salvar resposta em arquivo
z-ai vision -p "Forneça um resumo detalhado" -i "./reuniao.mp4" -o sumario.json
Análise Avançada de Vídeo
# Compreensão complexa de cena com pensamento
z-ai vision \
-p "Analise este vídeo e identifique: 1) Eventos principais, 2) Pessoas e suas ações, 3) Linha do tempo dos momentos chave" \
-i "./evento.mp4" \
--thinking \
-o analise.json
# Detecção de ação
z-ai vision \
-p "Identifique todas as ações realizadas por pessoas neste vídeo" \
-i "./esportes.mp4" \
--thinking
Saída em Stream
# Transmitir a análise do vídeo
z-ai vision -p "Descreva o conteúdo deste vídeo" -i "./video.mp4" --stream
Parâmetros da CLI
--prompt, -p <texto>: Obrigatório - Pergunta ou instrução sobre o vídeo--image, -i <URL ou caminho>: Opcional - URL do vídeo ou caminho do arquivo local (apesar do nome, funciona também para vídeos)--thinking, -t: Opcional - Habilita raciocínio em cadeia de pensamento para análises complexas (padrão: desabilitado)--output, -o <caminho>: Opcional - Caminho do arquivo de saída (formato JSON)--stream: Opcional - Transmite a resposta em tempo real
Formatos de Vídeo Suportados
- MP4 (.mp4) - Formato mais amplamente suportado
- AVI (.avi) - Audio Video Interleave
- MOV (.mov) - Formato QuickTime
- WebM (.webm) - Formato otimizado para web
- MKV (.mkv) - Formato Matroska
- FLV (.flv) - Formato Flash Video
Quando Usar CLI vs SDK
Use CLI para:
- Resumos rápidos de vídeo
- Análises de vídeo pontuais
- Testar capacidades de compreensão de vídeo
- Scripts de automação simples
- Gerar descrições de vídeo
Use SDK para:
- Conversas em múltiplas etapas sobre vídeos
- Pipelines complexos de processamento de vídeo
- Aplicações em produção com tratamento de erros
- Integração personalizada com lógica de processamento de vídeo
- Processamento em lote de vídeos com fluxos de trabalho personalizados
Abordagem Recomendada
Para melhor desempenho e confiabilidade com vídeos locais, considere:
- Fazer upload de vídeos para uma CDN e usar URLs
- Para vídeos mais curtos, converter quadros-chave em imagens para análise mais rápida
- Para vídeos longos, considerar dividir em partes ou amostrar em intervalos
Implementação Básica de Compreensão de Vídeo
Análise de Vídeo Único
import ZAI from 'z-ai-web-dev-sdk';
async function analisarVideo(urlVideo, 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: urlVideo
}
}
]
}
],
thinking: { type: 'disabled' }
});
return response.choices[0]?.message?.content;
}
// Exemplos de uso
const sumario = await analisarVideo(
'https://exemplo.com/apresentacao.mp4',
'Resuma os pontos principais apresentados neste vídeo'
);
const deteccaoAcao = await analisarVideo(
'https://exemplo.com/esportes.mp4',
'Identifique e descreva todas as ações atléticas realizadas neste vídeo'
);
Compreensão de Cenas de Vídeo
import ZAI from 'z-ai-web-dev-sdk';
async function entenderCenasVideo(urlVideo) {
const zai = await ZAI.create();
const prompt = `Analise este vídeo e forneça:
1. Resumo geral do conteúdo do vídeo
2. Principais cenas ou segmentos (com carimbos de tempo aproximados, se possível)
3. Principais pessoas ou personagens e seus papéis
4. Ações ou eventos importantes em ordem cronológica
5. Descrição do ambiente e cenário
6. Humor ou tom geral`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: urlVideo } }
]
}
],
thinking: { type: 'enabled' } // Habilita para análise detalhada
});
return response.choices[0]?.message?.content;
}
// Uso
const analiseCena = await entenderCenasVideo(
'https://exemplo.com/documentario.mp4'
);
Detecção de Movimento e Ação
import ZAI from 'z-ai-web-dev-sdk';
async function detectarAcoes(urlVideo, acaoEspecifica = null) {
const zai = await ZAI.create();
const prompt = acaoEspecifica
? `Identifique todas as instâncias de "${acaoEspecifica}" neste vídeo. Para cada instância, descreva quando ocorre e forneça detalhes sobre como é executada.`
: 'Identifique e descreva todas as ações e movimentos significativos neste vídeo. Inclua quem os está realizando e quando ocorrem.';
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: urlVideo } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}
// Uso
const acoesCorrida = await detectarAcoes(
'https://exemplo.com/esportes.mp4',
'correndo'
);
const todasAcoes = await detectarAcoes(
'https://exemplo.com/atividade.mp4'
);
Extração de Linha do Tempo de Eventos
import ZAI from 'z-ai-web-dev-sdk';
async function extrairLinhaTempo(urlVideo) {
const zai = await ZAI.create();
const prompt = `Crie uma linha do tempo detalhada dos eventos neste vídeo:
- Identifique momentos e transições chave
- Observe o tempo aproximado (início, meio, fim ou carimbos de tempo específicos, se visíveis)
- Descreva o que acontece em cada ponto chave
- Identifique quaisquer relações de causa e efeito entre eventos
Formate como uma lista cronológica.`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: urlVideo } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}
Classificação de Conteúdo de Vídeo
import ZAI from 'z-ai-web-dev-sdk';
async function classificarVideo(urlVideo) {
const zai = await ZAI.create();
const prompt = `Classifique o conteúdo deste vídeo:
1. Categoria principal (por exemplo, educacional, entretenimento, esportes, notícias, tutorial)
2. Subcategoria ou gênero
3. Público-alvo
4. Estilo de conteúdo (profissional, casual, documentário, etc.)
5. Temas ou tópicos principais
6. Tags sugeridas (10-15 palavras-chave)
Formate sua resposta como JSON estruturado.`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: urlVideo } }
]
}
],
thinking: { type: 'disabled' }
});
const content = response.choices[0]?.message?.content;
try {
return JSON.parse(content);
} catch (e) {
return { rawResponse: content };
}
}
Casos de Uso Avançados
Conversa em Múltiplas Etapas sobre Vídeo
import ZAI from 'z-ai-web-dev-sdk';
class ConversaVideo {
constructor() {
this.messages = [];
}
async initialize() {
this.zai = await ZAI.create();
}
async carregarVideo(urlVideo, perguntaInicial) {
this.messages.push({
role: 'user',
content: [
{ type: 'text', text: perguntaInicial },
{ type: 'video_url', video_url: { url: urlVideo } }
]
});
return this.obterResposta();
}
async fazerPerguntaSegumento(pergunta) {
this.messages.push({
role: 'user',
content: [
{ type: 'text', text: pergunta }
]
});
return this.obterResposta();
}
async obterResposta() {
const response = await this.zai.chat.completions.createVision({
messages: this.messages,
thinking: { type: 'disabled' }
});
const mensagemAssistente = response.choices[0]?.message?.content;
this.messages.push({
role: 'assistant',
content: mensagemAssistente
});
return mensagemAssistente;
}
}
// Uso
const conversa = new ConversaVideo();
await conversa.initialize();
const inicial = await conversa.carregarVideo(
'https://exemplo.com/palestra.mp4',
'Qual é o tópico principal desta palestra?'
);
const seguimento1 = await conversa.fazerPerguntaSegumento(
'Você pode explicar os conceitos principais mencionados?'
);
const seguimento2 = await conversa.fazerPerguntaSegumento(
'Que exemplos foram usados para ilustrar esses conceitos?'
);
Avaliação de Qualidade de Vídeo
import ZAI from 'z-ai-web-dev-sdk';
async function avaliarQualidadeVideo(urlVideo) {
const zai = await ZAI.create();
const prompt = `Avalie a qualidade deste vídeo:
1. Qualidade visual (resolução, clareza, iluminação) - Classifique 1-10
2. Qualidade de áudio (se houver áudio) - Classifique 1-10
3. Trabalho de câmera (estabilidade, enquadramento, composição) - Classifique 1-10
4. Valor de produção (edição, transições, efeitos) - Classifique 1-10
5. Clareza do conteúdo (a mensagem está clara?) - Classifique 1-10
6. Ritmo (muito rápido, muito lento, adequado)
7. Problemas técnicos (artefatos, desfoque, sincronia de áudio, etc.)
8. Classificação geral - 1-10
9. Recomendações específicas para melhoria
Forneça feedback detalhado para cada critério.`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: urlVideo } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}
Moderação de Conteúdo de Vídeo
import ZAI from 'z-ai-web-dev-sdk';
async function moderarVideo(urlVideo) {
const zai = await ZAI.create();
const prompt = `Revise este vídeo para moderação de conteúdo:
1. Verifique se há conteúdo inapropriado ou sensível
2. Identifique quaisquer preocupações potenciais de segurança
3. Observe qualquer conteúdo que possa violar diretrizes comuns da comunidade
4. Avalie a adequação à faixa etária
5. Identifique qualquer material protegido por direitos autorais visível (logotipos, marcas, música)
6. Classificação geral de segurança: Seguro / Cuidado / Revisão Necessária
Forneça exemplos específicos para quaisquer preocupações identificadas.`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: urlVideo } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}
Geração de Transcrição Visual (Descrição Visual)
import ZAI from 'z-ai-web-dev-sdk';
async function gerarTranscricaoVisual(urlVideo) {
const zai = await ZAI.create();
const prompt = `Gere uma transcrição visual detalhada deste vídeo:
- Descreva o que está acontecendo em cada cena
- Observe qualquer texto que apareça na tela
- Descreva elementos visuais importantes
- Mencione quaisquer mudanças de cena ou transições
- Inclua descrições das ações e expressões das pessoas
Formate como uma narrativa baseada em tempo (por exemplo, "No início...", "Então...", "Finalmente...").`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: urlVideo } }
]
}
],
thinking: { type: 'disabled' }
});
return response.choices[0]?.message?.content;
}
Análise de Vídeo Esportivo
import ZAI from 'z-ai-web-dev-sdk';
async function analisarVideoEsportivo(urlVideo, esporte = null) {
const zai = await ZAI.create();
const prompt = esporte
? `Analise este vídeo de ${esporte} em detalhes:
1. Identifique jogadores e suas posições
2. Descreva jogadas e estratégias principais
3. Observe eventos de pontuação ou momentos importantes
4. Avalie o desempenho dos jogadores
5. Identifique quaisquer violações de regras ou faltas
6. Descreva o ritmo e o fluxo do jogo`
: `Analise este vídeo esportivo:
1. Identifique o esporte sendo praticado
2. Descreva as ações e jogadas principais
3. Observe qualquer pontuação ou eventos significativos
4. Descreva movimentos e estratégias dos jogadores
5. Avaliação geral do jogo ou partida`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: urlVideo } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}