O que Transcrições e Pesquisa no YouTube faz?
Vídeo é uma fonte primária que a maioria dos agentes de pesquisa não consegue ler. Esta habilidade transforma qualquer vídeo, canal ou consulta de pesquisa do YouTube em texto que você pode citar, com timestamps.
Tudo roda através de uma única API REST. Sem yt-dlp, sem navegador headless, sem binários para instalar.
Configuração
A API precisa de uma chave no ambiente. Adicione uma linha ao .env do FrontierAgent:
echo 'TRANSCRIPT_API_KEY=sk_sua_chave_aqui' >> .env
Obtenha uma chave em https://transcriptapi.com. O nível gratuito oferece 100 créditos e não pede cartão de crédito.
O FrontierAgent carrega .env na inicialização e comandos shell herdam as variáveis, então $TRANSCRIPT_API_KEY
resolve dentro de cada comando abaixo.
Se a variável estiver vazia, pare e informe o usuário para adicioná-la. Não adivinhe uma chave e não imprima o valor de volta para o usuário.
Toda requisição precisa de ambos os cabeçalhos
Authorization: Bearer $TRANSCRIPT_API_KEY e um User-Agent real. Um User-Agent ausente ou padrão
resulta em um bloqueio Cloudflare 403, código de erro 1010.
Obter uma transcrição
Um crédito. video_url aceita uma URL completa do YouTube ou um ID de vídeo de 11 caracteres.
curl -sS -G "https://transcriptapi.com/api/v2/youtube/transcript" \
--data-urlencode "video_url=$VIDEO" \
--data-urlencode "format=text" \
--data-urlencode "send_metadata=true" \
-H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
-H "User-Agent: FrontierAgent/1.0"
Defina format=json quando precisar dos valores start e duration por segmento, por exemplo para
citar um timestamp. A estrutura JSON é
{"video_id": "...", "language": "en", "transcript": [{"text": "...", "start": 18.0, "duration": 3.5}]}.
Pesquisar vídeos ou canais
Um crédito. type é video ou channel, limit varia de 1 a 50.
curl -sS -G "https://transcriptapi.com/api/v2/youtube/search" \
--data-urlencode "q=$CONSULTA" \
--data-urlencode "type=video" \
--data-urlencode "limit=20" \
-H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
-H "User-Agent: FrontierAgent/1.0"
Resolver um handle de canal
Grátis, sem crédito. Aceita um @handle, uma URL de canal ou um ID UC....
curl -sS -G "https://transcriptapi.com/api/v2/youtube/channel/resolve" \
--data-urlencode "input=@TED" \
-H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
-H "User-Agent: FrontierAgent/1.0"
Os outros endpoints de canal aceitam o mesmo valor channel diretamente, então raramente é necessário
resolver primeiro.
Script auxiliar
scripts/transcript.sh encapsula a chamada de transcrição e falha ruidosamente quando a chave está ausente.
bash plugins/skills/youtube-transcripts/scripts/transcript.sh "https://www.youtube.com/watch?v=nm1TxQj9IsQ"
Quando uma chamada falha
| Status | O que significa | O que fazer |
|---|---|---|
| 401 | A chave está errada ou ausente | Peça ao usuário para verificar TRANSCRIPT_API_KEY no .env |
| 403 | Cloudflare bloqueou a requisição | Você omitiu o cabeçalho User-Agent. Adicione-o e tente novamente |
| 404 | O vídeo não tem legendas | Diga isso claramente. Não invente uma transcrição |
| 422 | O ID ou URL do vídeo está malformado | Releia o ID do link do usuário |
| 429 | Créditos esgotados ou limite de taxa atingido | Relate. Não tente novamente em loop |
Uma transcrição longa pode exceder o orçamento de saída da ferramenta. Peça format=text, escreva o corpo em um
arquivo com > outputs/transcript.txt, então leia as partes que você precisa.
Trabalhando com o que retorna
Cite a transcrição em vez de parafrasear quando a redação exata carrega a afirmação. Legendas automáticas carregam erros de reconhecimento, então trate um termo técnico estranho como suspeito e verifique-o contra o título ou descrição do vídeo antes de construir um argumento baseado nele.