techhorizonlabs/creator-audience

Público do criador

O YouTube não publica dados demográficos do público. A API de Dados usada por youtube-channel-profile não possui nenhum. Existem duas fontes honestas: a própria análise do proprietário do canal, compartilhada com seu consentimento, ou uma estimativa paga de terceiros que o humano aprova. Qualquer outra coisa é um palpite. Diga isso.

A regra do consentimento

1. Os dados do proprietário vêm do proprietário. Eles escolhem o que compartilhar, para quais datas e quem vê. Obtenha isso por escrito (um e-mail ou mensagem) antes de pedir acesso.
2. O proprietário faz login com sua própria conta. Nunca peça sua senha ou um código de login, e nunca digite um para eles.
3. Gastos precisam de um sim. Pergunte ao humano antes de cada consulta paga e informe seu custo.
4. Nunca infira idade, gênero ou localização a partir de nomes, rostos, vozes, comentários ou miniaturas.
5. Mantenha apenas para o trabalho. Mostre apenas ao proprietário e às pessoas que ele aprovou (política do YouTube III.E.3.b). Exclua dentro de 7 dias de uma solicitação (III.E.4.g). Se mantiver, reavalie o consentimento do proprietário a cada 30 dias (III.E.4.b).

Rota 1: o proprietário compartilha do YouTube Studio (comece aqui)

Isso não requer trabalho de API. Adequado para um briefing pontual.

Opção A, exportação: peça ao proprietário para abrir o YouTube Studio, ir em Analytics e depois na aba Público. Ele seleciona um intervalo de datas (os últimos 90 dias é um bom padrão) e compartilha uma captura de tela ou exportação de idade, gênero e principais países.

Opção B, acesso somente leitura: o proprietário abre o YouTube Studio e vai em Configurações, depois Permissões e depois Convidar. Ele insere o e-mail da conta Google do humano e escolhe o papel de Visualizador (Limitado). Esse papel pode ver análises, mas não receitas. Os convites expiram após 30 dias. Quando o trabalho terminar, o proprietário remove o acesso na mesma tela. Contas de canal de marca devem primeiro mover para permissões de canal.

Rota 2: a API YouTube Analytics (trabalhos repetidos ou maiores)

Use quando o proprietário, ou sua equipe, for executá-la, ou para um engajamento contínuo com consentimento por escrito.

1. No Google Cloud, crie um projeto. Ative a API YouTube Analytics e a API YouTube Data v3.
2. Configure a tela de consentimento OAuth: tipo de usuário Externo, status de publicação Teste. Adicione a conta Google do proprietário como usuário de teste.
3. Crie um ID de cliente OAuth do tipo Aplicativo de desktop e baixe o arquivo do cliente. Trate-o como um segredo.
4. Solicite apenas estes escopos:
   • https://www.googleapis.com/auth/yt-analytics.readonly
   • https://www.googleapis.com/auth/youtube.readonly (a referência reports.query agora também exige isso)
   • Adicione yt-analytics-monetary.readonly apenas se o proprietário concordar em compartilhar receitas.
5. Execute o login na máquina onde o proprietário faz login pessoalmente. Por exemplo:

# pip install google-auth-oauthlib requests
from google_auth_oauthlib.flow import InstalledAppFlow
import requests
ESCOPOS = ["https://www.googleapis.com/auth/yt-analytics.readonly",
          "https://www.googleapis.com/auth/youtube.readonly"]
credenciais = InstalledAppFlow.from_client_secrets_file("client_secret.json", ESCOPOS).run_local_server(port=0)
base = "https://youtubeanalytics.googleapis.com/v2/reports"
comum = {"ids": "channel==MINE", "startDate": "2026-08-01", "endDate": "2026-10-31"}
autenticacao = {"Authorization": f"Bearer {credenciais.token}"}
idade_genero = requests.get(base, headers=autenticacao, params={**comum,
    "metrics": "viewerPercentage", "dimensions": "ageGroup,gender"}).json()
paises = requests.get(base, headers=autenticacao, params={**comum,
    "metrics": "views,estimatedMinutesWatched", "dimensions": "country",
    "sort": "-views", "maxResults": 10}).json()

6. O proprietário escolhe o canal certo quando o Google perguntar. channel==MINE significa o canal com o qual ele fez login.
7. Leia columnHeaders e rows. viewerPercentage cobre apenas espectadores que estavam logados. Quando não há dados, o YouTube omite rows. Relate isso como "não disponível", nunca como zero.
8. Mantenha o token apenas na memória. Depois, revogue-o: o proprietário pode fazer isso em myaccount.google.com/permissions. Os tokens de atualização de um aplicativo em Teste também expiram após 7 dias.

Rota 3: uma estimativa paga (Influencers Club MCP)

O Influencers Club estima a demografia do público para canais públicos do YouTube. É um modelo de terceiros, não dados do YouTube. Cada consulta gasta créditos.

1. Execute check_credits (grátis) e anote o saldo.
2. Informe ao humano a ferramenta e seu custo e aguarde um sim. Custos do README do servidor, verificado em 5 de novembro de 2026: enrich_by_handle_analytics custa 0,8 créditos e retorna dados demográficos do público. enrich_by_handle custa 1 crédito; em servidores mais antigos, passe include_audience_data como verdadeiro para a seção de público. enrich_by_handle_raw custa 0,03 créditos e não possui dados de público. Leia a própria descrição da ferramenta primeiro, pois as versões diferem.
3. Faça uma chamada para um único canal, com platform definido como youtube e handle definido como o identificador ou ID do canal.
4. Se qualquer chamada retornar um erro de limite ou crédito, pare. Não tente novamente e informe quantas consultas foram feitas.
5. Não use get_audience_locations ou get_audience_interests para isso. Eles são listas gratuitas de valores de filtro, não o público do criador.

Rotule o resultado como "estimado pelo Influencers Club", forneça a data da consulta e nunca misture com números do proprietário sem dizer qual é qual.

O que escrever no briefing

• A fonte de cada número: YouTube Analytics do proprietário com seu intervalo de datas, exportação do Studio do proprietário ou uma estimativa de terceiros.
• Participações de idade e gênero para espectadores logados e os principais países por visualizações.
• Se não houver consentimento e nenhum gasto aprovado, escreva "Demografia do público: não disponível sem a análise do proprietário ou uma estimativa paga." Essa é uma resposta completa.

Verificado em 5 de novembro de 2026 contra a referência da API YouTube Analytics, páginas de métricas e autorização, ajuda do YouTube sobre permissões de canal e o README e limites de uso do Influencers Club MCP.