Communitygithub.com

ARYAN2302/liquid_researcher

Implemente capacidades especializadas de compreensão de vídeo usando o z-ai-web-dev-sdk. Use esta skill quando precisar analisar conteúdo de vídeo, entender movimento e sequências temporais, extrair informações de quadros de vídeo, descrever cenas de vídeo ou realizar análise de vídeo baseada em IA. Otimizado para MP4, AVI, MOV e outros formatos de vídeo comuns.

O que é liquid_researcher?

Esta skill fornece funcionalidades especializadas de compreensão de vídeo para agentes de IA, permitindo analisar, descrever e extrair informações de conteúdo de vídeo, incluindo movimento, sequências temporais e mudanças de cena. Suporta múltiplas plataformas, incluindo ferramentas de linha de comando 'z-ai vision' para tarefas rápidas (resumos, descrições, automação) e o SDK 'z-ai-web-dev-sdk' para implementações mais complexas, como conversas em múltiplas voltas sobre vídeos, pipelines de processamento e aplicações de produção. A skill é otimizada para formatos de vídeo comuns como MP4, AVI, MOV e WebM, e usa o parâmetro 'video_url' no SDK para passar conteúdo de vídeo. É particularmente útil para desenvolvedores que precisam construir aplicações de IA capazes de analisar vídeos de forma inteligente, desde a detecção de ações e extração de linhas do tempo até moderação de conteúdo e classificação.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ARYAN2302/liquid_researcher/tree/HEAD/skills/video-understand

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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:

  1. Fazer upload de vídeos para um CDN e usar URLs
  2. Para vídeos mais curtos, converter quadros-chave em imagens para análise mais rápida
  3. 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

  1. Falha de Rede: Ao usar URLs, pode ocorrer interrupção da rede. Recarregue ou tente novamente mais tarde.
  2. Arquivo Não Suportado: Certifique-se de que o formato do arquivo de vídeo seja suportado (MP4, AVI, MOV, etc.).
  3. Arquivo Muito Grande: Arquivos que excedem os limites de tamanho podem falhar ao processar. Reduza o tamanho ou use URLs.
  4. 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

  1. Use URLs para Vídeos: Faça upload de vídeos para URLs ou CDNs acessíveis antes da análise para melhor desempenho.
  2. Escolha os Prompt Adequadamente: Prompts específicos e detalhados produzem melhores resultados.
  3. 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.
  4. Desabilite Pensamento para Tarefas Rápidas: Use thinking: { type: 'disabled' } para classificações e tarefas simples.
  5. Stream para Análises Longas: Use streaming para vídeos longos para obter respostas mais rapidamente.
  6. Lide com Limites de Tamanho de Arquivo: Considere reduzir vídeos ou converter para formatos eficientes.
  7. 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ídeo
  • thinking: 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.

Individual skills in this repo

This repo contains 8 individual skills — each has its own dedicated page.

ARYAN2302/liquid_researcher

Generate a single-file Chinese atelier-style portfolio website (horizontal-row list + hover-reveal thumb interaction, art lishu typography "Alimama DaoLiTi" via CDN, light/dark theme, hash-routed detail pages). Takes a natural-language description of the studio (name, director, discipline, works) and outputs ONE working .html file. Runs in BOTH Claude Code (writes to ~/Desktop) and GLM / online chat (outputs HTML inline). Trigger phrases include "做个中式工作室作品集", "做个隶书作品集", "lishu-portfolio-gen ...", "做个白屋风格的作品集", or when user drags this skill folder into chat asking for an atelier-style site.

ARYAN2302/liquid_researcher

Chinese-market SaaS pricing page template — soft sky-blue glass-morphism, 4-tier card grid with one elevated "recommended" tier, monthly/annual toggle, FAQ accordion, ¥ pricing with Inter numerals, careful CJK linebreaking, ICP filing footer.

ARYAN2302/liquid_researcher

Premium calm-tech SaaS landing template — bilingual (CN/EN) literary voice over a dark forest-night palette with warm gold accent, Cormorant + Noto Serif SC, Three.js procedural forest hero, station-based scrolling narrative, custom cursor. Built for ambient-AI / creative-tool / philosophical SaaS, not loud commercial launch.

ARYAN2302/liquid_researcher

Pro-camera HUD mockup template — full-viewport black canvas wrapping a real video with monospace overlays (corner brackets, top status bar, side AF/exposure columns, bottom timecode + aperture/shutter/ISO row, vertical 8-filter wheel, animated reticle). For cinematographer portfolios, camera-app demos, LUT pack previews, filter-look auditions. NOT a TikTok/Reels mockup, NOT a storyboard, NOT a shot list, NOT a script document. The chrome wraps real footage — never a div placeholder.

ARYAN2302/liquid_researcher

Premium pre-launch waitlist page template — dark charcoal canvas with subtle vignette, drifting portrait video-thumbnail cards, fade-up cascades, glass nav, live-updating join counter, single email form with success/error states. Built for creative-tool / AI / niche-SaaS invite-only launches with hushed exclusive tone, not loud growth-marketing.

ARYAN2302/liquid_researcher

Route design-related HTML artifact tasks to the right artifact skill, reference, design system generation, or export skill.

ARYAN2302/liquid_researcher

Implement text-to-speech (TTS) capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to convert text into natural-sounding speech, create audio content, build voice-enabled applications, or generate spoken audio files. Supports multiple voices, adjustable speed, and various audio formats.

ARYAN2302/liquid_researcher

Implement AI-powered video generation capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to generate videos from text prompts or images, create video content programmatically, or build applications that produce video outputs. Supports asynchronous task management with status polling and result retrieval.

Habilidades Relacionadas