Como obter uma chave API do YouTube (YouTube Data API v3) e fazer sua primeira requisição

Uma chave de API do YouTube é a credencial que permite ao seu código ler dados públicos do YouTube: detalhes de vídeos, estatísticas de canais, resultados de pesquisa, conteúdos de playlists. A documentação do Google afirma claramente: “Uma solicitação que não fornece um token OAuth 2.0 deve enviar uma chave de API. A chave identifica seu projeto e fornece acesso à API, cota e relatórios.” Sem chave, sem dados.

Este guia levará você de um projeto vazio do Google Cloud a uma solicitação funcionando em cerca de quinze minutos. Você habilitará a YouTube Data API v3, criará uma chave, a protegerá, chamará a API usando curl e Python, e então armazenará a chave no Apidog e salvará a chamada como um teste repetível. Se você quiser ter uma visão geral primeiro, nossa visão geral da YouTube Data API cobre o que a API expõe; esta postagem é a parte prática.

O que você precisa antes de começar

• Uma conta Google. Isso é suficiente para abrir o Cloud Console e criar um projeto.
• curl (vem com macOS e a maioria das distribuições Linux) e Python 3 com o pacote requests para os exemplos de código.
• Apidog se você quiser a chave armazenada como um segredo e a solicitação salva como um teste. O plano gratuito cobre tudo aqui.

Passo 1: crie um projeto Google Cloud

Abra o Google Cloud Console e faça login. Use o seletor de projetos no topo da página para criar um novo projeto, por exemplo youtube-integration. Cada chave de API, cota e relatório de uso que você verá mais tarde está associado a este projeto, então mantenha um projeto por aplicativo em vez de compartilhar uma chave entre ferramentas não relacionadas. Se o aplicativo já tiver um projeto, use-o.

Passo 2: habilite a YouTube Data API v3

As APIs vêm desativadas por padrão em um novo projeto. No console, vá para APIs e Serviços, abra a Biblioteca de APIs, procure por “YouTube Data API v3” e habilite-a. O guia de primeiros passos do Google descreve a mesma verificação de outra forma: visite a página de APIs Habilitadas e ative a API se ela não estiver listada.

Pule esta etapa e sua primeira solicitação falhará com um erro 403, indicando que a API não foi usada no projeto ou está desativada. É o motivo mais comum para uma chave recém-criada “não funcionar”.

Passo 3: crie a chave de API

Vá para APIs e Serviços, depois Credenciais. Clique em Criar credenciais e escolha Chave de API. O console gera a chave imediatamente e a mostra em uma caixa de diálogo; copie-a para um local seguro.

Trate a chave como uma senha. Não a cole em um repositório Git, um chat do Slack ou um pacote JavaScript do lado do cliente. Se ela já escapou para um commit, nosso guia sobre como encontrar e corrigir chaves de API expostas aborda a limpeza.

Passo 4: restrinja a chave

A própria documentação do Google afirma: “Chaves de API irrestritas são inseguras.” Logo após a criação, clique em Restringir chave. Você terá dois controles independentes, documentados no guia de chaves de API do Cloud:

• Restrições de aplicativo decidem quem pode apresentar a chave. Escolha uma: sites (HTTP referrers, com suporte limitado a curingas), endereços IP (IPv4, IPv6 ou intervalos CIDR), aplicativos Android (nome do pacote mais impressão digital do certificado SHA-1) ou aplicativos iOS (IDs de bundle). Um serviço de backend deve usar endereços IP. Um widget apenas para navegador deve usar referrers.
• Restrições de API decidem quais APIs a chave pode chamar. Escolha “Restringir chave” e selecione apenas a YouTube Data API v3. Se a chave vazar, o invasor terá acesso apenas à cota do YouTube e nada mais.

Salve e aguarde alguns minutos para que a alteração entre em vigor antes de testar. Mais dois hábitos do mesmo guia: gire as chaves periodicamente para limitar os danos de uma chave comprometida e exclua as chaves antigas assim que todos os chamadores tiverem migrado para a substituta. Uma observação para o próximo passo: se você restringir por IP ao seu servidor, o curl do seu laptop será bloqueado, então teste a partir do host permitido ou crie uma chave de desenvolvimento separada.

Passo 5: faça sua primeira solicitação com curl e Python

Todo endpoint se baseia em https://www.googleapis.com/youtube/v3/. Passe a chave como o parâmetro de consulta key, que é como os próprios exemplos do Google fazem, ou em um cabeçalho x-goog-api-key, o que a mantém fora de URLs e logs de acesso. Ambos funcionam na API ao vivo.

Comece com videos.list, a chamada útil mais barata: ela retorna detalhes para um ou mais IDs de vídeo e custa 1 unidade de cota. O ID abaixo é o que o Google usa em sua documentação.

export YOUTUBE_API_KEY="AIza...your-key..."

curl -s "https://www.googleapis.com/youtube/v3/videos?part=snippet,statistics&id=7lCDEYXw3mM" \
  -H "x-goog-api-key: $YOUTUBE_API_KEY"

Uma resposta resumida se parece com isto:

{
  "kind": "youtube#videoListResponse",
  "items": [
    {
      "id": "7lCDEYXw3mM",
      "snippet": { "title": "...", "channelTitle": "...", "publishedAt": "..." },
      "statistics": { "viewCount": "...", "likeCount": "..." }
    }
  ]
}

O parâmetro part é obrigatório e controla quais seções são retornadas; snippet, statistics, contentDetails e status são os que você mais usará.

Agora uma busca, que é a chamada que a maioria das pessoas procura. Em Python com requests:

import os
import requests

API_KEY = os.environ["YOUTUBE_API_KEY"]
BASE = "https://www.googleapis.com/youtube/v3"

resp = requests.get(
    f"{BASE}/search",
    params={"part": "snippet", "q": "api testing", "type": "video", "maxResults": 10},
    headers={"x-goog-api-key": API_KEY},
    timeout=10,
)

if resp.status_code != 200:
    err = resp.json()["error"]
    raise SystemExit(f"{err['code']} {err['errors'][0]['reason']}: {err['message']}")

for item in resp.json()["items"]:
    print(item["id"]["videoId"], item["snippet"]["title"])

Para search.list, part deve ser snippet, maxResults o padrão é 5 e aceita de 0 a 50, e type o padrão é video,channel,playlist, então defina-o como video se você quiser apenas vídeos. Os resultados da pesquisa contêm videoId dentro de id, não no nível superior, razão pela qual o loop acima lê item["id"]["videoId"].

Passo 6: armazene a chave e execute a solicitação no Apidog

Uma variável de shell funciona para um único script. Não funciona para uma equipe e não oferece uma verificação salva e repetível. Aqui está a mesma solicitação no Apidog, com a chave mantida fora da nuvem.

1. Crie um ambiente. Adicione um ambiente chamado YouTube com duas variáveis: base_url definido como https://www.googleapis.com/youtube/v3, e youtube_api_key. Para a chave, deixe o valor compartilhado como um placeholder e cole a chave real no campo de valor local. Valores locais permanecem no cache do seu cliente e nunca sincronizam com a equipe; a configuração completa está em nosso guia sobre ambientes e variáveis secretas no Apidog.
2. Construa a solicitação. Nova solicitação, GET {{base_url}}/videos, parâmetros de consulta part=snippet,statistics e id=7lCDEYXw3mM, e um cabeçalho x-goog-api-key definido como {{youtube_api_key}}. Selecione o ambiente YouTube e envie. Você deverá ver o mesmo JSON da chamada curl.
3. Transforme-a em um teste. Nos pós-processadores da solicitação, adicione asserções: status é igual a 200, e $.items[0].id é igual a 7lCDEYXw3mM. Salve a solicitação e adicione-a a um cenário de teste. A verificação agora é executada sob demanda, em um agendamento ou em CI através do Apidog CLI, onde --env-var "youtube_api_key=$YOUTUBE_API_KEY" injeta a chave em tempo de execução em vez de armazená-la.

O retorno vem na primeira vez que a chave é rotacionada ou uma restrição é alterada: execute novamente um cenário e você saberá em segundos se todas as chamadas do YouTube ainda funcionam. Baixe o Apidog para acompanhar; é gratuito para equipes de até quatro pessoas.

Cota e limites

A YouTube Data API não cobra em dólares; ela cobra em unidades de cota, e os números vêm da página da calculadora de cota do Google. Todo projeto que habilita a API recebe esta alocação padrão:

Dentro do pool compartilhado de 10.000 unidades, métodos de listagem como videos.list, channels.list, playlistItems.list e commentThreads.list custam 1 unidade cada. Escritas custam mais: videos.update e videos.delete são 50 unidades, e captions.insert é 400. Quatro regras da mesma página moldam como você deve projetar em torno disso:

• As cotas são redefinidas à meia-noite (Horário do Pacífico).
• Cada solicitação, incluindo uma inválida, custa pelo menos 1 unidade. Um loop que tenta novamente uma chamada ruim gasta cota em vão.
• Cada página adicional de um resultado paginado custa o mesmo que a primeira página.
• A alocação padrão está “sujeita a alterações”. Verifique a página, e não um tutorial, antes de planejar a capacidade.

Guias mais antigos precificavam uma busca em 100 unidades do pool de 10.000. A página atual coloca search.list em seu próprio balde, então o limite ainda é de 100 buscas por dia, mas as buscas não consomem mais a cota de suas outras chamadas.

Se isso não for suficiente, a página de auditorias de cota e conformidade direciona você para o Formulário de Extensão de Auditoria e Cota dos Serviços da API do YouTube. Antes de preenchê-lo, armazene as respostas em cache, solicite apenas os valores de part de que precisa e agrupe os IDs em uma única chamada videos.list (o parâmetro id aceita uma lista separada por vírgulas). O uso é exibido na página Cotas no Cloud Console.

Erros comuns e como corrigi-los

A referência de erros do Google lista os códigos de razão da própria API. As duas primeiras linhas abaixo vêm do envio de solicitações reais para a API ao vivo com uma chave inválida e sem chave.

Mais uma da prática: se uma restrição de aplicativo não corresponder ao chamador, você receberá um erro 403 que informa o referrer ou IP bloqueado. Corrija a restrição ou chame a partir do host permitido. E observe que threads de fóruns mais antigos chamam o erro de chave inválida de keyInvalid; a API ao vivo retorna badRequest com um detalhe API_KEY_INVALID, então corresponda à mensagem ou ao detalhe, e não à string de razão legada.

Perguntas Frequentes

Uma chave de API do YouTube é gratuita?

Sim. Criar uma chave não custa nada, e a documentação precifica a API em unidades de cota, não em dinheiro. A alocação padrão acima é o que você recebe sem pedir nada.

Quando preciso de OAuth em vez de uma chave de API?

Uma chave de API identifica seu projeto e desbloqueia dados públicos. No momento em que você toca em dados privados de usuários, ou insere, atualiza ou exclui algo, o Google exige um token OAuth 2.0 do usuário que possui esses dados. Avaliar um vídeo, listar suas próprias assinaturas ou usar o filtro mine=true caem no lado do OAuth. Nossa comparação entre chaves de API e tokens de portador explica por que as duas credenciais respondem a perguntas diferentes.

Um agente de IA pode usar minha chave de API do YouTube?

Sim, desde que o agente seja executado onde as restrições da chave permitem. Um servidor YouTube MCP é uma maneira de entregar dados de vídeo a um assistente de codificação; forneça-lhe uma chave restrita à Data API e à máquina em que ele é executado, e mantenha-a fora do próprio prompt.

O que devo fazer se a chave vazar?

Exclua-a na página de Credenciais e crie uma substituta. Em seguida, corrija a origem: mova a chave para um valor local no Apidog ou para um armazenamento de segredos, e escaneie o repositório para que a chave antiga não continue no histórico.

Próximo passo

Agora você tem um projeto, uma API habilitada, uma chave restrita e uma solicitação que funciona com curl, Python e Apidog. Conecte o cenário salvo ao CI e deixe a página de Cotas informar quando é hora de otimizar.