techhorizonlabs/perfil-de-canal-youtube

Perfil de canal do YouTube

scripts/channel_profile.py lê dados públicos de canal através da YouTube Data API v3 e imprime um relatório em Markdown, ou JSON com --json. Ele usa apenas a API oficial. Nunca carrega páginas web do YouTube e não grava nada em disco.

Antes de executar

1. O humano precisa de um projeto no Google Cloud com a YouTube Data API v3 ativada e uma chave de API, restrita a essa API.
2. A chave fica na variável de ambiente YOUTUBE_API_KEY. Nunca a coloque em um prompt, arquivo ou chat, e nunca a imprima. Se não estiver definida, pare e peça para o humano defini-la. Não procure chaves em nenhum outro lugar.
3. Instale a única dependência: pip install -r scripts/requirements.txt (requests).

Executar

python3 scripts/channel_profile.py @handle
python3 scripts/channel_profile.py https://www.youtube.com/@handle --videos 100
python3 scripts/channel_profile.py UCxxxxxxxxxxxxxxxxxxxxxx --json

Opções: --videos N (uploads recentes a ler, padrão 50, máximo 500), --json, --no-search, --cpm-low e --cpm-high (padrão 0,25 e 4,00).

Como encontra o canal

• Um ID de canal ou uma URL /channel/UC...: channels.list com id.
• Um @handle ou URL /@handle: channels.list com forHandle.
• Uma URL /user/: forUsername. Uma URL /c/ é tentada como um handle.
• Se nada corresponder, ele recorre a search.list para a melhor correspondência e informa isso no relatório. Verifique o título e o ID antes de confiar. --no-search desativa a alternativa.
• Links de vídeo, links de playlist e endereços que não são do YouTube são recusados. Peça o link do canal.

Cota

Chamada	Custo
channels.list	1 unidade
playlistItems.list	1 unidade por 50 uploads
videos.list	1 unidade por 50 vídeos
search.list (apenas alternativa)	1 chamada de seu próprio balde

A execução padrão custa 3 unidades do padrão diário de 10.000 unidades. Desde 1º de junho de 2026, search.list tem seu próprio balde de 100 chamadas por dia. Antes disso, uma pesquisa custava 100 unidades da cota principal, então guias mais antigos dirão 100. Chamadas com falha ainda consomem cota. A cota é redefinida à meia-noite, horário do Pacífico. Cada relatório termina com a cota usada.

O que ele relata

Do YouTube, conforme retornado:

• Assinantes, arredondados para baixo pelo YouTube para três algarismos significativos. Se o proprietário ocultar a contagem, o relatório diz "Oculto" e não dá palpite.
• Visualizações totais do canal e a contagem pública de vídeos.
• Visualizações, curtidas e comentários de cada vídeo recente.

Derivado pelo script, marcado com *:

• Cadência: mediana de dias entre os últimos N uploads, uploads por mês ((N - 1) intervalos / dias abrangidos x 30,44) e dias desde o último upload.
• Mediana e média de visualizações dos vídeos recentes. Transmissões ao vivo e futuras são excluídas.
• Tendência: mediana de visualizações dos últimos 10 uploads em comparação com os 10 anteriores. Vídeos mais novos tiveram menos tempo para acumular visualizações.
• Engajamento: (curtidas + comentários) / visualizações por vídeo, depois a mediana. Vídeos com curtidas ocultas são excluídos. Vídeos com comentários desativados contam 0 comentários.
• Shorts contra formato longo, por duração. Esta é uma heurística: 180 segundos ou menos conta como Short, porque a API não tem uma flag de Shorts.
• 5 principais vídeos recentes por visualizações.
• Visualizações mensais estimadas: a soma das visualizações atuais em vídeos publicados nos últimos 30 dias. Isso exclui visualizações de catálogo antigo. Se a amostra não atingir 30 dias, o relatório informa e pede um --videos maior. Essa verificação assume que a playlist de uploads lista os mais recentes primeiro, como geralmente faz.

A política III.E.4.h da API do YouTube permite figuras derivadas apenas ao lado dos totais do YouTube, com uma nota clara de que não são do YouTube. O relatório faz ambas as coisas. Mantenha essa nota sempre que citar um número marcado com asterisco.

Método de ganhos

baixo  = visualizações mensais estimadas / 1.000 x US$ 0,25
alto = visualizações mensais estimadas / 1.000 x US$ 4,00

US$ 0,25 a US$ 4,00 é a faixa de CPM padrão publicada pelo Social Blade (socialblade.com/youtube/calculator). O relatório imprime a fórmula com os números reais. É apenas receita de anúncios. Exclui patrocínios, membrosias, compras e renda de afiliados, e financiamento de fãs. O RPM real varia por nicho, país do público e formato. A receita de Shorts é agrupada em termos diferentes. Um canal fora do Programa de Parcerias do YouTube não ganha receita de anúncios. Sempre chame de faixa estimada, nunca de renda.

Erros

Saída	Significado	O que fazer
0	Relatório impresso
2	Entrada inválida, chave ausente ou canal não encontrado	Corrija a entrada, ou peça ao humano a chave ou o link correto
3	Cota esgotada	Pare. Informe ao humano que ela é redefinida à meia-noite, horário do Pacífico. Não tente novamente em loop nem troque de chaves
4	Outro erro de API, como chave inválida ou API não ativada	Mostre a mensagem ao humano
5	Erro de rede	Tente novamente uma vez, depois informe

Erros imprimem a cota usada antes da falha. Toda mensagem e relatório são limpos da chave antes de serem impressos.

Regras

• Apenas API oficial. Não faça scraping de páginas do YouTube para preencher lacunas. Relate a lacuna.
• Não armazene nada em cache além da execução. Não salve respostas brutas da API. Se o humano mantiver o relatório, as estatísticas da API não podem ser armazenadas por mais de 30 dias (política III.E.4.b).
• Apenas dados públicos. Dados demográficos do público não são públicos: veja a skill creator-audience.

Verificado em 5 de novembro de 2026 conforme a referência da YouTube Data API, página de cota, histórico de revisões e políticas de desenvolvedor. Os testes do script são executados offline contra fixtures. Ele não foi executado contra a API ativa aqui.