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
- Acesse o Google Cloud Console
- Crie um novo projeto ou selecione um existente
- Habilite a YouTube Data API v3
- Crie credenciais → Chave de API
- (Opcional) Restrinja a Chave de API apenas para a YouTube Data API
Limites de Cota
| Tipo de Operação | Custo de Cota (unidades) |
|---|---|
| Operações de leitura (list) | 1 |
| Requisições de pesquisa | 100 |
| Operações de escrita (insert/update/delete) | 50 |
| Upload de vídeo | 1600 |
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âmetro | Descrição | Valores |
|---|---|---|
--query, -q | Palavras-chave da pesquisa | Suporta operadores booleanos (python AND tutorial) |
--type | Tipo de recurso | video, channel, playlist |
--max-results | Quantidade de resultados | 1-50, padrão 25 |
--order | Ordem de classificação | relevance(padrão), date, rating, viewCount, title |
--published-after | Publicado após | 1d, 7d, 30d, 1y ou formato ISO 8601 |
--published-before | Publicado antes | Mesmo que acima |
--region-code | Código da região | ISO 3166-1 (ex.: BR, US, JP) |
--relevance-language | Idioma | ISO 639-1 (ex.: pt, en, ja) |
--video-duration | Duração do vídeo | short(<4min), medium(4-20min), long(>20min) |
--video-definition | Definição | high(HD), standard(SD) |
--video-caption | Legendas | closedCaption(tem legendas), none(sem legendas) |
--video-dimension | Dimensão | 2d, 3d |
--event-type | Status ao vivo | live(transmitindo), completed(encerrado), upcoming(agendado) |
--channel-id | Limitar a canal | ID do canal |
--safe-search | Pesquisa segura | none, 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
| Parte | Contém |
|---|---|
snippet | Título, descrição, miniaturas, informações do canal, hora de publicação, tags |
statistics | Contagem de visualizações, contagem de likes, contagem de comentários |
contentDetails | Duração, definição, informações de legenda, restrições regionais |
status | Status de upload, privacidade, licença |
player | HTML do player incorporado |
topicDetails | IDs de tópicos relacionados |
recordingDetails | Local de gravação, data |
liveStreamingDetails | Informações ao vivo (hora de início/término, contagem de espectadores) |
Referência de IDs de Categoria de Vídeo
| ID | Categoria | ID | Categoria |
|---|---|---|---|
| 1 | Filme & Animação | 20 | Games |
| 2 | Automóveis & Veículos | 22 | Pessoas & Blogs |
| 10 | Música | 23 | Comédia |
| 15 | Animais de Estimação & Animais | 24 | Entretenimento |
| 17 | Esportes | 25 | Notícias & Política |
| 19 | Viagem & Eventos | 26 | Como Fazer & Estilo |
| 27 | Educação | 28 | Ciê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
| Parte | Contém |
|---|---|
snippet | Nome do canal, descrição, miniaturas, país |
statistics | Contagem de inscritos, contagem de vídeos, total de visualizações |
contentDetails | Playlists relacionadas (uploads, likes, etc.) |
brandingSettings | Banner do canal, palavras-chave, idioma padrão |
topicDetails | Tópicos do canal |
status | Status 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ção | Descrição |
|---|---|
relevance | Por relevância (padrão) |
time | Por 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ódigo | Descrição | Solução |
|---|---|---|
| 400 | Requisição inválida | Verifique o formato dos parâmetros |
| 401 | Não autorizado | Verifique a chave de API |
| 403 | Cota excedida ou permissões insuficientes | Verifique a cota ou solicite aumento |
| 404 | Recurso não encontrado | Verifique se o ID está correto |
| 429 | Muitas requisições | Reduza a frequência das requisições |
Dicas de Otimização de Cota
- Use o parâmetro
fieldspara solicitar apenas os campos necessários - Faça requisições em lote usando listas de IDs separadas por vírgula
- Armazene resultados em cache para evitar requisições duplicadas
- 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
- Clone este repositório para
~/.claude/skills/youtube-data-api/ - Instale as dependências:
pip install -r requirements.txt - 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
- Limites de cota: O plano gratuito tem 10.000 unidades/dia. Use o parâmetro
--fieldspara reduzir o uso de cota. - Conta de serviço: Não é compatível com YouTube Data API. Use OAuth 2.0 para operações que exigem autenticação.
- Conformidade com termos de serviço: Siga os Termos de Serviço do YouTube. Não use para raspagem em massa não autorizada.
- 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.