Skill de Compreensão de Vídeo
Esta skill fornece funcionalidade especializada 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 em seu projeto.
Scripts de Referência: Scripts de teste de exemplo estão disponíveis no diretório {Skill Location}/scripts/ para testes rápidos e referência. Veja {Skill Location}/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 client-side.
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 URL
z-ai vision --prompt "Resuma o que acontece neste vídeo" --image "https://exemplo.com/video.mp4"
# Nota: Use o flag --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 resumo.json
Análise Avançada de Vídeo
# Compreensão de cena complexa 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 este conteúdo de 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 encadeado para análise complexa (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álise de vídeo pontual
- Testar capacidades de compreensão de vídeo
- Scripts de automação simples
- Gerar descrições de vídeo
Use SDK para:
- Conversas de múltiplas voltas sobre vídeos
- Pipelines complexos de processamento de vídeo
- Aplicações de produção com tratamento de erros
- Integração personalizada com lógica de processamento de vídeo
- Processamento de vídeo em lote 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 chunking ou amostragem 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 resposta = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{
type: 'text',
text: prompt
},
{
type: 'video_url',
video_url: {
url: urlVideo
}
}
]
}
],
thinking: { type: 'disabled' }
});
return resposta.choices[0]?.message?.content;
}
// Exemplos de uso
const resumo = await analisarVideo(
'https://exemplo.com/apresentacao.mp4',
'Resuma os pontos-chave 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 Cena 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 timestamps aproximados, se possível)
3. Pessoas ou personagens principais 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 resposta = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: urlVideo } }
]
}
],
thinking: { type: 'enabled' } // Habilitar para análise detalhada
});
return resposta.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 é realizada.`
: 'Identifique e descreva todas as ações e movimentos significativos neste vídeo. Inclua quem os está realizando e quando ocorrem.';
const resposta = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: urlVideo } }
]
}
],
thinking: { type: 'enabled' }
});
return resposta.choices[0]?.message?.content;
}
// Uso
const acoesCorrer = await detectarAcoes(
'https://exemplo.com/esportes.mp4',
'correr'
);
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-chave e transições
- Observe o tempo aproximado (início, meio, fim ou timestamps 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 resposta = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: urlVideo } }
]
}
],
thinking: { type: 'enabled' }
});
return resposta.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 este conteúdo de vídeo:
1. Categoria principal (ex.: 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 resposta = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: urlVideo } }
]
}
],
thinking: { type: 'disabled' }
});
const conteudo = resposta.choices[0]?.message?.content;
try {
return JSON.parse(conteudo);
} catch (e) {
return { rawResponse: conteudo };
}
}
Casos de Uso Avançados
Conversa de Múltiplas Voltas 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 fazerPerguntaAcompanhamento(pergunta) {
this.messages.push({
role: 'user',
content: [
{ type: 'text', text: pergunta }
]
});
return this.obterResposta();
}
async obterResposta() {
const resposta = await this.zai.chat.completions.createVision({
messages: this.messages,
thinking: { type: 'disabled' }
});
const mensagemAssistente = resposta.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/aula.mp4',
'Qual é o tópico principal desta aula?'
);
const acompanhamento1 = await conversa.fazerPerguntaAcompanhamento(
'Você pode explicar os conceitos-chave mencionados?'
);
const acompanhamento2 = await conversa.fazerPerguntaAcompanhamento(
'Quais 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) - Avalie de 1 a 10
2. Qualidade de áudio (se houver áudio) - Avalie de 1 a 10
3. Trabalho de câmera (estabilidade, enquadramento, composição) - Avalie de 1 a 10
4. Valor de produção (edição, transições, efeitos) - Avalie de 1 a 10
5. Clareza do conteúdo (a mensagem está clara?) - Avalie de 1 a 10
6. Ritmo (muito rápido, muito lento, adequado)
7. Problemas técnicos (artefatos, desfoque, sincronia de áudio, etc.)
8. Avaliação geral - 1 a 10
9. Recomendações específicas para melhoria
Forneça feedback detalhado para cada critério.`;
const resposta = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: urlVideo } }
]
}
],
thinking: { type: 'enabled' }
});
return resposta.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 inadequado 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 à idade
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 resposta = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: urlVideo } }
]
}
],
thinking: { type: 'enabled' }
});
return resposta.choices[0]?.message?.content;
}
Geração de Transcrição Visual de Vídeo
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 no tempo (ex.: "No início...", "Então...", "Finalmente...").`;
const resposta = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: urlVideo } }
]
}
],
thinking: { type: 'disabled' }
});
return resposta.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 os 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 de esporte:
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 resposta = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: urlVideo } }
]
}
],
thinking: { type: 'enabled' }
});
return resposta.choices[0]?.message?.content;
}
...
[truncado para tradução]