Transcrição do YouTube

Visão Geral

Busca transcrições, resultados de pesquisa e dados de playlists/canais do YouTube via a API REST getyoutubetranscript.com, para que um agente possa resumir, citar, pesquisar ou analisar o conteúdo falado real de um vídeo sem que o usuário precise copiar e colar manualmente. Sem yt-dlp e sem necessidade de chave de API do Google.

• source_repo: tubeagentkit/youtube-transcript-skills
• source_type: community

Quando Usar Esta Habilidade

• Use quando o usuário quiser a transcrição de um vídeo do YouTube buscada, resumida, citada ou analisada.
• Use quando o usuário quiser pesquisar no YouTube (globalmente ou dentro de um canal pelo identificador).
• Use quando o usuário quiser que um identificador de canal seja resolvido para um ID de canal, ou quiser informações e histórico de uploads de um canal.
• Use quando o usuário quiser os vídeos em uma playlist do YouTube.

Como Funciona

Etapa 1: Obter uma chave de API

Cada chamada precisa de uma chave de API: a variável de ambiente YOUTUBE_TRANSCRIPT_API_KEY, ou uma que o usuário já forneceu. Se nenhuma existir, a habilidade pode cadastrar o usuário para uma conta gratuita (100 créditos, sem cartão necessário) através de um fluxo de duas etapas de e-mail + código de verificação contra a API - somente após o usuário ter dado consentimento explícito e um endereço de e-mail para usar.

Etapa 2: Chamar a API

URL base: https://getyoutubetranscript.com/api/v1. Envie a chave como Authorization: Bearer <API_KEY> ou x-api-key: <API_KEY>.

• GET /transcript?v=<VIDEO_ID_OR_URL>&language=en - buscar uma transcrição.
• GET /search?q=<query>&type=video|channel - pesquisar no YouTube.
• GET /resolve?handle=@name - resolver um identificador de canal para um ID de canal (grátis).
• GET /channel/latest?channel=@name - informações do canal e vídeos mais recentes (grátis).
• GET /channel/videos?channel=@name - histórico completo de uploads de um canal (paginado).
• GET /channel/search?channel=@name&q=<query> - pesquisar dentro de um canal (paginado).
• GET /playlist?list=<playlist ID or URL> - vídeos de playlist (paginado).

Etapa 3: Lidar com erros e paginação

Todo erro é JSON com um code estável (por exemplo, TRANSCRIPT_NOT_FOUND, PAYMENT_REQUIRED, RATE_LIMITED) e um status HTTP correspondente - repasse o campo message para o usuário em vez de adivinhar uma correção. Endpoints paginados retornam um data.continuation_token opaco; passe-o de volta literalmente como continuation para obter a próxima página, null significa que não há mais páginas.

Exemplos

Exemplo 1: Resumir um vídeo

curl -s "https://getyoutubetranscript.com/api/v1/transcript?v=jNQXAC9IVRw&language=en" \
  -H "Authorization: Bearer $YOUTUBE_TRANSCRIPT_API_KEY"

Exemplo 2: Navegar pelos uploads de um canal

curl -s "https://getyoutubetranscript.com/api/v1/channel/videos?channel=@mkbhd" \
  -H "Authorization: Bearer $YOUTUBE_TRANSCRIPT_API_KEY"

Melhores Práticas

• Reutilize uma YOUTUBE_TRANSCRIPT_API_KEY existente antes de oferecer a criação de uma nova conta.
• Peça consentimento explícito antes de enviar um endereço de e-mail para qualquer lugar durante o cadastro.
• Não tente novamente uma resposta 402 PAYMENT_REQUIRED - direcione o usuário para recarregar em vez disso.
• Não bombardeie uma resposta 429 RATE_LIMITED em um loop de retentativas - recue.

Limitações

• O endpoint de transcrição retorna o texto falado completo como uma única string; não há detalhamento de timestamp por linha.
• Esta habilidade não substitui a validação específica do ambiente, testes ou revisão de especialistas.
• Pare e peça esclarecimentos se os inputs necessários, permissões ou limites de segurança estiverem faltando.

Notas de Segurança e Proteção

• Esta habilidade faz apenas requisições HTTPS de saída para endpoints getyoutubetranscript.com, mais - durante a configuração inicial - um endereço de e-mail que o usuário fornece explicitamente. Ela não executa nenhum outro comando de shell e não instala nada.
• Nunca persista uma chave de API recém-emitida em um perfil de shell ou outro arquivo sem a confirmação explícita do usuário primeiro.

Armadilhas Comuns

• Problema: Assumir que a resposta da transcrição inclui timestamps. Solução: Informe ao usuário que os timestamps não estão disponíveis neste endpoint em vez de inventá-los.

Habilidades Relacionadas

• @youtube-full - uma habilidade alternativa de transcrição/pesquisa/canal/playlist do YouTube baseada em uma API upstream diferente.