Communitygithub.com

Yrzhe/claude-skills

Wrapper completo da YouTube Data API v3 — pesquise vídeos, obtenha detalhes de vídeos/canais/playlists, comentários, baixe legendas e muito mais. Suporta filtragem e ordenação por data, visualizações, avaliações e outros critérios.

O que é claude-skills?

Esta skill fornece um wrapper completo para a YouTube Data API v3, projetado para ser usado com agentes de IA como Claude Code, Cursor e Codex. Ela capacita o agente a realizar todas as principais operações da API: desde pesquisar vídeos com filtros avançados (por data, duração, definição, legendas, transmissão ao vivo, região) até obter detalhes de vídeos individuais, informações de canais, playlists, itens de playlists, comentários e legendas. A skill também suporta paginação para grandes conjuntos de dados e múltiplos formatos de saída (JSON, CSV, simples). A configuração é feita via variável de ambiente YOUTUBE_API_KEY, e a skill inclui orientações sobre limites de cota da API, tratamento de erros e dicas de otimização. Operações que exigem OAuth (como upload ou gerenciamento de playlists) são claramente sinalizadas.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Yrzhe/claude-skills/tree/HEAD/plugins/youtube-data-api/skills/youtube-data-api

Perguntar na sua IA favorita

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

Documentação

Skill da YouTube Data API v3

Wrapper completo baseado na documentação oficial da YouTube Data API v3.

Configuração

Configuração da Chave de API

# Opção 1: Variável de ambiente (recomendado)
export YOUTUBE_API_KEY="SUA_CHAVE_API_AQUI"

# Opção 2: Editar arquivo de configuração diretamente
# Edite ~/.claude/skills/youtube-data-api/scripts/config.py

Obtendo uma Chave de API

  1. Acesse o Google Cloud Console
  2. Crie um novo projeto ou selecione um existente
  3. Habilite a YouTube Data API v3
  4. Crie credenciais → Chave de API
  5. (Opcional) Restrinja a Chave de API apenas para a YouTube Data API

Limites de Cota

Tipo de OperaçãoCusto de Cota (unidades)
Operações de leitura (list)1
Requisições de pesquisa100
Operações de escrita (insert/update/delete)50
Upload de vídeo1600

Cota diária padrão: 10.000 unidades


Funcionalidades Principais

1. Pesquisar Vídeos (Search)

Custo de cota: 100 unidades/requisição

# Pesquisa básica
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Tutorial Python" \
    --max-results 25

# Filtrar por tempo (última semana)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "machine learning" \
    --published-after "7d" \
    --type video

# Ordenar por contagem de visualizações
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "React hooks" \
    --order viewCount \
    --type video

# Apenas vídeos HD
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "4K natureza" \
    --video-definition high \
    --type video

# Vídeos com legendas
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "palestra TED" \
    --video-caption closedCaption \
    --type video

# Vídeos ao vivo
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "games" \
    --event-type live \
    --type video

# Filtrar por região
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "notícias" \
    --region-code BR \
    --relevance-language pt

# Filtrar por duração do vídeo
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "documentário" \
    --video-duration long \
    --type video

Referência de Parâmetros de Pesquisa

ParâmetroDescriçãoValores
--query, -qPalavras-chave da pesquisaSuporta operadores booleanos (python AND tutorial)
--typeTipo de recursovideo, channel, playlist
--max-resultsQuantidade de resultados1-50, padrão 25
--orderOrdem de classificaçãorelevance(padrão), date, rating, viewCount, title
--published-afterPublicado após1d, 7d, 30d, 1y ou formato ISO 8601
--published-beforePublicado antesMesmo que acima
--region-codeCódigo da regiãoISO 3166-1 (ex.: BR, US, JP)
--relevance-languageIdiomaISO 639-1 (ex.: pt, en, ja)
--video-durationDuração do vídeoshort(<4min), medium(4-20min), long(>20min)
--video-definitionDefiniçãohigh(HD), standard(SD)
--video-captionLegendasclosedCaption(tem legendas), none(sem legendas)
--video-dimensionDimensão2d, 3d
--event-typeStatus ao vivolive(transmitindo), completed(encerrado), upcoming(agendado)
--channel-idLimitar a canalID do canal
--safe-searchPesquisa seguranone, moderate, strict

2. Obter Detalhes do Vídeo (Videos)

Custo de cota: 1 unidade/requisição

# Obter detalhes de um único vídeo
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --id "dQw4w9WgXcQ" \
    --parts snippet,statistics,contentDetails

# Obter múltiplos vídeos (em lote)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --id "dQw4w9WgXcQ,jNQXAC9IVRw,9bZkp7q19f0" \
    --parts snippet,statistics

# Obter vídeos em alta
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --chart mostPopular \
    --region-code BR \
    --max-results 50

# Obter em alta por categoria
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --chart mostPopular \
    --video-category-id 10 \
    --region-code JP

Referência de Partes do Vídeo

ParteContém
snippetTítulo, descrição, miniaturas, informações do canal, hora de publicação, tags
statisticsContagem de visualizações, contagem de likes, contagem de comentários
contentDetailsDuração, definição, informações de legenda, restrições regionais
statusStatus de upload, privacidade, licença
playerHTML do player incorporado
topicDetailsIDs de tópicos relacionados
recordingDetailsLocal de gravação, data
liveStreamingDetailsInformações ao vivo (hora de início/término, contagem de espectadores)

Referência de IDs de Categoria de Vídeo

IDCategoriaIDCategoria
1Filme & Animação20Games
2Automóveis & Veículos22Pessoas & Blogs
10Música23Comédia
15Animais de Estimação & Animais24Entretenimento
17Esportes25Notícias & Política
19Viagem & Eventos26Como Fazer & Estilo
27Educação28Ciência & Tecnologia

3. Obter Informações do Canal (Channels)

Custo de cota: 1 unidade/requisição

# Obter por ID do canal
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py channel \
    --id "UC_x5XG1OV2P6uZZ5FSM9Ttw" \
    --parts snippet,statistics,contentDetails

# Obter por nome de usuário
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py channel \
    --for-username "GoogleDevelopers" \
    --parts snippet,statistics

# Obter por handle (@nome_do_usuário)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py channel \
    --for-handle "@Google" \
    --parts snippet,statistics,brandingSettings

Referência de Partes do Canal

ParteContém
snippetNome do canal, descrição, miniaturas, país
statisticsContagem de inscritos, contagem de vídeos, total de visualizações
contentDetailsPlaylists relacionadas (uploads, likes, etc.)
brandingSettingsBanner do canal, palavras-chave, idioma padrão
topicDetailsTópicos do canal
statusStatus do canal (permissão de upload de vídeo longo, etc.)

4. Obter Playlists (Playlists)

Custo de cota: 1 unidade/requisição

# Obter playlist por ID
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist \
    --id "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" \
    --parts snippet,contentDetails

# Obter todas as playlists de um canal
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist \
    --channel-id "UC_x5XG1OV2P6uZZ5FSM9Ttw" \
    --max-results 50

5. Obter Vídeos da Playlist (PlaylistItems)

Custo de cota: 1 unidade/requisição

# Obter todos os vídeos de uma playlist
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist-items \
    --playlist-id "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" \
    --max-results 50

# Recuperação paginada
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist-items \
    --playlist-id "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" \
    --page-token "NEXT_PAGE_TOKEN"

6. Obter Comentários (Comments & CommentThreads)

Custo de cota: 1 unidade/requisição

# Obter todos os comentários de um vídeo (nível superior)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py comments \
    --video-id "dQw4w9WgXcQ" \
    --max-results 100 \
    --order relevance

# Obter comentários de um canal
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py comments \
    --channel-id "UC_x5XG1OV2P6uZZ5FSM9Ttw" \
    --max-results 50

# Obter respostas a um comentário
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py comment-replies \
    --parent-id "COMMENT_ID" \
    --max-results 50

Opções de Ordenação de Comentários

OrdenaçãoDescrição
relevancePor relevância (padrão)
timePor data (mais recentes primeiro)

7. Obter Legendas (Captions)

Custo de cota: 1 unidade/requisição (listar), 50 unidades (baixar)

# Listar todas as faixas de legenda de um vídeo
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py captions \
    --video-id "dQw4w9WgXcQ" \
    --list

# Baixar legendas (requer OAuth)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py captions \
    --video-id "dQw4w9WgXcQ" \
    --download \
    --caption-id "CAPTION_ID" \
    --format srt

Nota: O download de legendas requer autorização do proprietário do vídeo (OAuth). Para vídeos públicos, use yt-dlp para obter legendas geradas automaticamente.

Usando yt-dlp para Legendas (Alternativa)

# Instalar yt-dlp
pip install yt-dlp

# Listar legendas disponíveis
yt-dlp --list-subs "https://www.youtube.com/watch?v=VIDEO_ID"

# Baixar legendas (pular vídeo)
yt-dlp --write-sub --write-auto-sub --sub-lang pt,en --skip-download \
    "https://www.youtube.com/watch?v=VIDEO_ID"

# Baixar e converter para formato SRT
yt-dlp --write-sub --write-auto-sub --sub-lang pt --sub-format srt --skip-download \
    "https://www.youtube.com/watch?v=VIDEO_ID"

8. Obter Categorias de Vídeo (VideoCategories)

Custo de cota: 1 unidade/requisição

# Obter categorias de vídeo para uma região
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py categories \
    --region-code BR

# Obter categorias para a China
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py categories \
    --region-code CN

9. Obter Regiões e Idiomas Suportados

Custo de cota: 1 unidade/requisição

# Obter lista de regiões suportadas
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py regions

# Obter lista de idiomas suportados
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py languages

Exemplos de Casos de Uso Comuns

Cenário 1: Obter Vídeos em Alta sobre um Tópico da Última Semana

# Pesquisar vídeos sobre "IA" dos últimos 7 dias, ordenados por visualizações
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "IA inteligência artificial" \
    --published-after "7d" \
    --order viewCount \
    --type video \
    --max-results 50 \
    --output ia_trending.json

# Obter estatísticas detalhadas para esses vídeos
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --ids-from ia_trending.json \
    --parts snippet,statistics,contentDetails \
    --output ia_trending_details.json

Cenário 2: Analisar Todos os Vídeos de um Canal

# 1. Obter informações do canal
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py channel \
    --for-handle "@GoogleDevelopers" \
    --parts snippet,statistics,contentDetails \
    --output canal_info.json

# 2. Obter ID da playlist de uploads (de contentDetails.relatedPlaylists.uploads)

# 3. Obter todos os vídeos enviados
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist-items \
    --playlist-id "UPLOADS_PLAYLIST_ID" \
    --max-results 50 \
    --all-pages \
    --output videos_canal.json

Cenário 3: Obter Vídeos com Legendas

# 1. Pesquisar vídeos
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "palestra TED motivação" \
    --video-caption closedCaption \
    --type video \
    --max-results 10 \
    --output ted_videos.json

# 2. Baixar legendas usando yt-dlp
for video_id in $(jq -r '.items[].id.videoId' ted_videos.json); do
    yt-dlp --write-sub --write-auto-sub --sub-lang pt --skip-download \
        "https://www.youtube.com/watch?v=$video_id" \
        -o "legendas/%(id)s.%(ext)s"
done

Cenário 4: Analisar Comentários de Vídeos

# Obter todos os comentários de um vídeo
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py comments \
    --video-id "VIDEO_ID" \
    --max-results 100 \
    --all-pages \
    --output comentarios.json

# Os dados do comentário incluem:
# - Nome do autor
# - Texto do comentário
# - Contagem de likes
# - Hora da publicação
# - Contagem de respostas

Formatos de Saída

Todos os comandos usam saída JSON por padrão. Salve em arquivo com o parâmetro --output.

# Saída para arquivo
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" \
    --output resultados.json

# Formato CSV (dados tabulares)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" \
    --format csv \
    --output resultados.csv

# Saída simples (apenas títulos e IDs)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" \
    --format simple

Paginação

Para grandes conjuntos de dados, a API usa pageToken para paginação:

# Buscar automaticamente todas as páginas
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" \
    --all-pages \
    --max-total 500 \
    --output todos_resultados.json

# Paginação manual
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" \
    --page-token "NEXT_PAGE_TOKEN"

Tratamento de Erros

Códigos de Erro Comuns

CódigoDescriçãoSolução
400Requisição inválidaVerifique o formato dos parâmetros
401Não autorizadoVerifique a chave de API
403Cota excedida ou permissões insuficientesVerifique a cota ou solicite aumento
404Recurso não encontradoVerifique se o ID está correto
429Muitas requisiçõesReduza a frequência das requisições

Dicas de Otimização de Cota

  1. Use o parâmetro fields para solicitar apenas os campos necessários
  2. Faça requisições em lote usando listas de IDs separadas por vírgula
  3. Armazene resultados em cache para evitar requisições duplicadas
  4. Use ETags para verificar se o recurso foi atualizado
# Obter apenas os campos necessários (reduz o tamanho da resposta)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --id "VIDEO_ID" \
    --fields "items(id,snippet(title,channelTitle),statistics(viewCount))"

Operações que Exigem OAuth

As seguintes operações exigem autorização do usuário (apenas a chave de API não é suficiente):

  • Fazer upload de vídeos
  • Atualizar metadados de vídeos
  • Excluir vídeos
  • Gerenciar playlists
  • Publicar/excluir comentários
  • Avaliar vídeos
  • Gerenciar legendas (upload, atualização, exclusão)

Script de Autenticação OAuth

# Iniciar fluxo de autenticação OAuth
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py auth \
    --client-secrets caminho/para/client_secret.json \
    --scopes https://www.googleapis.com/auth/youtube.upload,https://www.googleapis.com/auth/youtube.force-ssl

# Usar token armazenado para operações OAuth
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --id "VIDEO_ID" \
    --rating like \
    --oauth

Guia de Instalação e Uso

Instalação

  1. Clone este repositório para ~/.claude/skills/youtube-data-api/
  2. Instale as dependências: pip install -r requirements.txt
  3. Configure sua chave de API (veja a seção de configuração acima)

Estrutura de Arquivos

~/.claude/skills/youtube-data-api/
├── scripts/
│   └── youtube_api.py    # Script principal da API
├── SKILL.md              # Este arquivo de documentação
└── requirements.txt      # Dependências Python

Dependências

  • requests
  • python-dotenv (opcional, para carregar chave de API de arquivo .env)

Notas Importantes

  1. Limites de cota: O plano gratuito tem 10.000 unidades/dia. Use o parâmetro --fields para reduzir o uso de cota.
  2. Conta de serviço: Não é compatível com YouTube Data API. Use OAuth 2.0 para operações que exigem autenticação.
  3. Conformidade com termos de serviço: Siga os Termos de Serviço do YouTube. Não use para raspagem em massa não autorizada.
  4. YouTube Data API v3: Para mudanças na API, consulte a documentação oficial.

Licença

Este projeto é licenciado sob a licença MIT — consulte o arquivo LICENSE para mais detalhes.

Habilidades Relacionadas