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 {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 de 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 de uma URL
z-ai vision --prompt "Resuma o que acontece neste vídeo" --image "https://example.com/video.mp4"
# Nota: Use a flag --image para URLs de vídeo também
z-ai vision -p "Descreva os eventos principais" -i "https://example.com/presentation.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 "./recording.mp4"
# Salvar a resposta em um arquivo
z-ai vision -p "Forneça um resumo detalhado" -i "./meeting.mp4" -o summary.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 principais" \
-i "./event.mp4" \
--thinking \
-o analysis.json
# Detecção de ação
z-ai vision \
-p "Identifique todas as ações realizadas pelas pessoas neste vídeo" \
-i "./sports.mp4" \
--thinking
Saída em Streaming
# Transmitir a análise de 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 para 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ídeos
- 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 em múltiplas voltas sobre vídeos
- Pipelines complexos de processamento de vídeo
- Aplicações de produção com tratamento de erros
- Integração customizada com lógica de processamento de vídeo
- Processamento em lote de vídeos com fluxos de trabalho customizados
Abordagem Recomendada
Para melhor desempenho e confiabilidade com vídeos locais, considere:
- Fazer upload de vídeos para um CDN e usar URLs
- Para vídeos mais curtos, converter quadros-chave em imagens para análise mais rápida
- Para vídeos longos, considere 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 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;
}
// Exemplos de uso
const summary = await analyzeVideo(
'https://example.com/presentation.mp4',
'Resuma os pontos principais apresentados neste vídeo'
);
const actionDetection = await analyzeVideo(
'https://example.com/sports.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 understandVideoScenes(videoUrl) {
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. Pessoas ou personagens principais e seus papéis
4. Ações ou eventos importantes em ordem cronológica
5. Descrição do cenário e ambiente
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: videoUrl } }
]
}
],
thinking: { type: 'enabled' } // Habilitar para análise detalhada
});
return response.choices[0]?.message?.content;
}
// Uso
const sceneAnalysis = await understandVideoScenes(
'https://example.com/documentary.mp4'
);
Detecção de Movimento e Ação
import ZAI from 'z-ai-web-dev-sdk';
async function detectActions(videoUrl, specificAction = null) {
const zai = await ZAI.create();
const prompt = specificAction
? `Identifique todas as instâncias de "${specificAction}" 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 realiza e quando ocorrem.';
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',
'correndo'
);
const allActions = await detectActions(
'https://example.com/activity.mp4'
);
Extração de Linha do Tempo de Eventos
import ZAI from 'z-ai-web-dev-sdk';
async function extractTimeline(videoUrl) {
const zai = await ZAI.create();
const prompt = `Crie uma linha do tempo detalhada dos eventos neste vídeo:
- Identifique momentos e transições principais
- Anote o tempo aproximado (início, meio, fim ou carimbos de tempo específicos, se visíveis)
- Descreva o que acontece em cada ponto principal
- Identifique quaisquer relações de causa e efeito entre os 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: videoUrl } }
]
}
],
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 classifyVideo(videoUrl) {
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. Sub-categoria ou gênero
3. Público-alvo
4. Estilo de conteúdo (profissional, casual, documental, 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: videoUrl } }
]
}
],
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 de Vídeo em Múltiplas Voltas
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',
'Qual é o tópico principal desta palestra?'
);
const followup1 = await conversation.askFollowUp(
'Você pode explicar os conceitos principais mencionados?'
);
const followup2 = await conversation.askFollowUp(
'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 assessVideoQuality(videoUrl) {
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 o áudio estiver presente) - 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 é clara?) - Avalie de 1 a 10
6. Ritmo (muito rápido, muito lento, adequado)
7. Problemas técnicos (artefatos, desfoque, sincronização 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 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;
}
Moderação de Conteúdo de Vídeo
import ZAI from 'z-ai-web-dev-sdk';
async function moderateVideo(videoUrl) {
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 à 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 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;
}
Geração de Transcrição Visual
import ZAI from 'z-ai-web-dev-sdk';
async function generateVisualTranscript(videoUrl) {
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 começo...", "Então...", "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álise de Vídeo Esportivo
import ZAI from 'z-ai-web-dev-sdk';
async function analyzeSportsVideo(videoUrl, sport = null) {
const zai = await ZAI.create();
const prompt = sport
? `Analise este vídeo de ${sport} em detalhe:
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 quaisquer pontuações ou eventos significativos
4. Descreva os movimentos dos jogadores e estratégias
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: videoUrl } }
]
}
],
thinking: { type: 'disabled' }
});
return response.choices[0]?.message?.content;
}
Considerações sobre Desempenho
- Tamanho e Duração do Vídeo: Arquivos maiores e vídeos mais longos podem levar mais tempo para processar. Considere amostrar quadros para vídeos longos.
- Tamanho do Arquivo: Certifique-se de que os arquivos de vídeo estejam acessíveis e dentro dos limites de tamanho. Para arquivos grandes, considere fazer upload para um CDN.
- Velocidade da Rede: A transmissão de vídeos grandes pode ser impactada pela largura de banda da rede.
- Processamento no Servidor: O processamento de vídeo ocorre no servidor. Para melhor desempenho, use vídeos de alta qualidade com resolução adequada.
Tratamento de Erros
Erros Comuns
- Falha de Rede: Ao usar URLs, pode ocorrer interrupção da rede. Recarregue ou tente novamente mais tarde.
- Arquivo Não Suportado: Certifique-se de que o formato do arquivo de vídeo seja suportado (MP4, AVI, MOV, etc.).
- Arquivo Muito Grande: Arquivos que excedem os limites de tamanho podem falhar ao processar. Reduza o tamanho ou use URLs.
- Sem Conteúdo de Vídeo: Certifique-se de que o vídeo contenha dados visuais. Arquivos vazios ou corrompidos podem causar erros.
Exemplo com Tratamento de Erros
import ZAI from 'z-ai-web-dev-sdk';
async function analyzeVideoWithRetry(videoUrl, prompt, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
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;
} catch (error) {
console.warn(`Tentativa ${attempt} falhou:`, error.message);
if (attempt === maxRetries) {
throw new Error(`Falha após ${maxRetries} tentativas: ${error.message}`);
}
// Esperar antes de tentar novamente
await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
}
}
}
// Uso
const content = await analyzeVideoWithRetry(
'https://example.com/video.mp4',
'Descreva o conteúdo principal deste vídeo'
);
Resumo e Melhores Práticas
- Use URLs para Vídeos: Faça upload de vídeos para URLs ou CDNs acessíveis antes da análise para melhor desempenho.
- Escolha os Prompt Adequadamente: Prompts específicos e detalhados produzem melhores resultados.
- Habilite Pensamento para Tarefas Complexas: Use
thinking: { type: 'enabled' }para análise profunda de cenas, detecção de ações e extração de linha do tempo. - Desabilite Pensamento para Tarefas Rápidas: Use
thinking: { type: 'disabled' }para classificações e tarefas simples. - Stream para Análises Longas: Use streaming para vídeos longos para obter respostas mais rapidamente.
- Lide com Limites de Tamanho de Arquivo: Considere reduzir vídeos ou converter para formatos eficientes.
- Salve e Reutilize Respostas: Armazene respostas em cache para análise repetida evitar processamento desnecessário.
Referência de API do SDK
createVision
Cria uma conclusão de bate-papo com capacidades de análise de vídeo.
Parâmetros:
messages: Array de mensagens com conteúdo de texto e/ou URL de vídeothinking: Configuração de raciocínio (habilitado/desabilitado)
Formato de Mensagem para Vídeos:
{
role: 'user',
content: [
{ type: 'text', text: 'Sua pergunta ou instrução' },
{ type: 'video_url', video_url: { url: 'https://exemplo.com/video.mp4' } }
]
}
Observação: Vídeos passados via URL são processados diretamente. Para vídeos locais, certifique-se de que sejam acessíveis via URL ou caminho de arquivo.
Notas Finais
A compreensão de vídeo depende de modelos de IA poderosos otimizados para conteúdo de vídeo. A precisão pode variar com base na complexidade do vídeo, duração e qualidade. Para resultados ideais, garanta boa iluminação, movimento claro e duração de vídeo razoável.