Como obter uma chave de API do YouTube e usar a API de dados (2026)

Você precisa de uma chave de API do YouTube no momento em que seu aplicativo precisa ler qualquer coisa do YouTube: a duração de um vídeo, sua contagem de visualizações, os envios mais recentes de um canal. Conseguir um leva cerca de cinco minutos. Usá-lo bem demora um pouco mais, porque o YouTube mudou o funcionamento de sua cota em junho de 2026, e muitos guias ainda descrevem as regras antigas.

Neste guia vamos pegar uma chave, trancá-la e testá-la. Em seguida, usaremos o Node.js para três tarefas reais: somar a duração de uma playlist, listar os vídeos de um canal sem gastar uma pesquisa e estimar quanto um vídeo rendeu. Ao longo do caminho, abordaremos quanto custa a API do YouTube (nada), como funciona a cota de 2026 e os erros que você provavelmente encontrará.

O que você pode fazer com uma chave de API do YouTube

Uma chave de API do YouTube identifica seu projeto na API de dados do YouTube v3. Com apenas uma chave, você pode ler dados públicos:

• Detalhes do vídeo: título, duração e contagem de visualizações, curtidas e comentários
• Playlists e os vídeos nelas contidos
• Canais: nome, contagem de inscritos (a menos que esteja oculto) e envios
• Comentários públicos e resultados de pesquisa

Uma chave não é suficiente para nada que envolva a conta de alguém. O upload de vídeos, a edição de playlists ou a leitura de dados privados precisam do OAuth 2.0, onde o usuário faz login e concede acesso ao seu aplicativo.

Tarefa Chave de API OAuth 2.0 Leia vídeos públicos, playlists e dados do canal Sim Sim Pesquise no YouTube Sim Sim Envie ou edite vídeos e playlists Não Sim Ler os vídeos privados de um usuário ou seu próprio canal (mine=true) Não Sim

Como obter uma chave de API do YouTube

Você precisará de uma conta do Google. A API de dados do YouTube é gratuita, portanto não há nada pelo que pagar.

1. Crie um projeto. Vá para o Console do Google Cloudabra o seletor de projetos na parte superior da página e clique em Novo projeto. Nomeie-o com o nome do seu aplicativo e clique em Criar.
2. Ative a API de dados do YouTube v3. Com seu novo projeto selecionado, vá para APIs e serviços > Bibliotecapesquise “YouTube Data API v3”, abra-o e clique em Habilitar.
3. Crie a chave. Vá para APIs e serviços > Credenciaisclique Criar credenciais e escolha Chave de API. Copie a chave que o Google mostra para você.
4. Restrinja-o. Abra a chave na página Credenciais. Sob Restrições de APIescolher Chave restrita e marque apenas API de dados do YouTube v3. Sob Restrições de aplicaçãoescolher Endereços IP para uma chave que seu servidor usa, ou Sites para uma chave usada no navegador. Salvar.
5. Mantenha isso fora do seu código. Coloque-o em uma variável de ambiente ou em um .env arquivo listado em .gitignore. Guia do SitePoint para definindo variáveis ​​de ambiente Node.js. cobre as opções.

As restrições são mais importantes do que parecem. Uma chave é apenas uma string em um URL, e qualquer pessoa que copie uma chave irrestrita pode gastar sua cota diária para você. Com uma restrição de API, a chave é inútil para outras APIs do Google. Com restrição de aplicativo, ele só funciona no seu servidor ou site. As alterações nas restrições podem levar até cinco minutos para serem aplicadas, então não entre em pânico se uma solicitação falhar logo após você salvar.

Teste sua chave

Antes de escrever qualquer código, verifique a chave com uma única solicitação. Este pede o primeiro vídeo enviado ao YouTube e usa o fields parâmetro para reduzir a resposta para quatro valores:

curl "https://www.googleapis.com/youtube/v3/videos?part=snippet,statistics&id=jNQXAC9IVRw&fields=items(snippet(title,channelTitle,publishedAt),statistics(viewCount))&key=YOUR_API_KEY"

Se a chave funcionar, você receberá de volta:

{ "items": ( { "snippet": { "publishedAt": "2005-04-24T03:31:52Z", "title": "Me at the zoo", "channelTitle": "jawed" }, "statistics": { "viewCount": "447713984" } } ) }

Esse pedido custou 1 unidade da sua cota diária, o que nos leva à pergunta que todos fazem.

A API do YouTube é gratuita?

Sim. Não há cobrança por solicitação e nenhum plano pago. Em vez disso, você recebe uma cota diária e, desde 1º de junho de 2026, ela está dividida em grupos separados:

Balde Diária padrão Custo por chamada Procurar (search.list) 100 chamadas 1 chamada Carregamentos (videos.insert) 100 chamadas 1 chamada Todo o resto 10.000 unidades 1 unidade para a maioria das leituras, como videos.list, playlistItems.list, channels.list e commentThreads.list. Alguns métodos custam mais, como 50 para captions.list e thumbnails.set.

do Google calculadora de cotas lista o custo de cada método. As cotas são redefinidas à meia-noite, horário do Pacífico. Cada solicitação custa pelo menos 1 unidade, incluindo solicitações que falham, portanto, um loop de nova tentativa em torno de uma chamada interrompida pode consumir a cota de um dia por si só.

Se você leu guias mais antigos, a pesquisa é a grande mudança. Uma pesquisa costumava custar 100 unidades das mesmas 10.000, então 100 pesquisas esvaziavam o dia inteiro. Os uploads foram ainda piores, com cerca de 1.600 unidades cada até dezembro de 2025. Agora ambos têm seus próprios buckets, e as 10.000 unidades sobram para todo o resto.

Para lhe dar uma ideia de quanto 10.000 unidades compram, aqui está quanto custa cada exemplo neste guia:

Trabalho Chamadas Unidades Duração total de uma playlist de 52 vídeos 2 playlistItems.list + 2 videos.list 4 Os cinco vídeos mais recentes de um canal 1 channels.list + 1 playlistItems.list 2 Visualizações, curtidas e comentários de um vídeo 1 videos.list 1

Como aumentar sua cota de API do YouTube

Você não pode pagar por mais. Para ir além dos padrões, preencha o Formulário de auditoria de serviços de API e extensão de cota do YouTube, que está vinculado à página do Google sobre auditorias de cotas e conformidade. O YouTube primeiro audita seu projeto para verificar se ele segue os Termos de Serviço dos serviços da API do YouTube e, em seguida, alguém da equipe da API entra em contato com você. O Google não fornece um cronograma, então inscreva-se bem antes de precisar da cota extra.

A maioria dos projetos nunca precisa disso. O restante deste guia é sobre como fazer muito com poucas unidades.

Configure o projeto

Os exemplos precisam do Node.js 20.6 ou posterior, para o integrado fetch e o --env-file bandeira. Não há pacotes para instalar. Faça uma pasta com um .env arquivo nele:

YOUTUBE_API_KEY=your-key-here

Cada exemplo importa um pequeno auxiliar. Ele cria a URL, adiciona sua chave e transforma erros de API em mensagens legíveis:

const API = 'https://www.googleapis.com/youtube/v3' const KEY = process.env.YOUTUBE_API_KEY export async function yt(endpoint, params) { const url = `${API}/${endpoint}?${new URLSearchParams({ ...params, key: KEY })}` const res = await fetch(url) const data = await res.json() if (!res.ok) { const reason = data.error?.errors?.(0)?.reason ?? data.error?.status throw new Error(`${res.status} ${reason}: ${data.error?.message}`) } return data }

Execute qualquer exemplo com node --env-file=.env seguido pelo nome do arquivo.

Exemplo 1: Obtenha a duração total de uma lista de reprodução

O YouTube não informa a duração de uma playlist. Para resolver isso, você precisa de dois métodos:

• playlistItems.list retorna até 50 vídeos da playlist por chamada, além de um nextPageToken quando há mais.
• videos.list pega até 50 IDs de vídeo por chamada e retorna cada vídeo contentDetails.duration.

As durações retornam no formato ISO 8601. PT15M33S é 15 minutos e 33 segundos, PT1H2M3S adiciona uma hora e um fluxo com mais de um dia parece P1DT2H3M4S. O toSeconds() a função abaixo lida com todos os três.

import { yt } from './yt.mjs' async function playlistVideoIds(playlistId) { const ids = () let pageToken do { const page = await yt('playlistItems', { part: 'contentDetails', playlistId, maxResults: 50, ...(pageToken && { pageToken }), }) ids.push(...page.items.map(item => item.contentDetails.videoId)) pageToken = page.nextPageToken } while (pageToken) return ids } function toSeconds(iso) { const (, d, h, m, s) = iso.match(/^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/) ?? () return (+d || 0) * 86400 + (+h || 0) * 3600 + (+m || 0) * 60 + (+s || 0) } async function durations(ids) { const seconds = () for (let i = 0; i < ids.length; i += 50) { const batch = await yt('videos', { part: 'contentDetails', id: ids.slice(i, i + 50).join(',') }) seconds.push(...batch.items.map(video => toSeconds(video.contentDetails.duration))) } return seconds } const format = total => `${Math.floor(total / 3600)}h ${Math.floor((total % 3600) / 60)}m ${total % 60}s` const ids = await playlistVideoIds(process.argv(2)) const seconds = await durations(ids) const total = seconds.reduce((sum, s) => sum + s, 0) console.log(`${seconds.length} of ${ids.length} videos available`) console.log(`Total length: ${format(total)}`) for (const speed of (1.25, 1.5, 2)) { console.log(`At ${speed}x: ${format(Math.round(total / speed))}`) }

Aqui está no freeCodeCamp Cursos completos em um vídeo lista de reprodução:

node --env-file=.env playlist-length.mjs PLWKjhJtqVAbnupwRFOq9zGOWjdvPRtCmO 52 of 52 videos available Total length: 184h 17m 53s At 1.25x: 147h 26m 18s At 1.5x: 122h 51m 55s At 2x: 92h 8m 57s

São 184 horas de cursos para 4 unidades de cota. Os vídeos privados e excluídos ainda aparecem nos itens de uma playlist, mas videos.list não os retorna, por isso o script imprime “52 de 52 vídeos disponíveis”. Numa lista de reprodução com vídeos removidos, os dois números serão diferentes.

Este é o núcleo do livre Calculadora de duração da playlist do YouTube Eu construí crieisso.ai. A versão ao vivo adiciona uma caixa de tempo alvo que calcula a velocidade necessária para terminar dentro de um prazo e aceita links de canal, vídeo e Shorts, bem como listas de reprodução.

Exemplo 2: liste os vídeos de um canal sem pesquisar

A maneira óbvia de encontrar os vídeos de um canal é procurá-los. Não faça isso: a pesquisa agora está limitada a 100 ligações por dia e não foi criada para listar tudo o que um canal postou. Cada canal tem uma lista de reprodução de uploads, e você pode acessá-la em duas ligações baratas:

1. channels.list com forHandle gira uma alça como @freecodecamp em um canal, incluindo o ID da playlist de envios em contentDetails.relatedPlaylists.uploads.
2. playlistItems.list nessa lista de reprodução retorna os vídeos, os mais recentes primeiro.

import { yt } from './yt.mjs' const { items: (channel) } = await yt('channels', { part: 'snippet,contentDetails,statistics', forHandle: process.argv(2), }) const uploads = channel.contentDetails.relatedPlaylists.uploads console.log(`${channel.snippet.title}: ${Number(channel.statistics.videoCount).toLocaleString()} videos`) const { items } = await yt('playlistItems', { part: 'snippet', playlistId: uploads, maxResults: 5 }) for (const item of items) { console.log(item.snippet.publishedAt.slice(0, 10), item.snippet.resourceId.videoId, item.snippet.title) } node --env-file=.env channel-videos.mjs @freecodecamp freeCodeCamp.org: 2,341 videos 2026-11-03 lR931Iz8Z6U Vector Databases Full Course for Beginners – Embeddings, Similarity Search & ChromaDB 2026-10-28 cqfl38Ip1ho How Ethical Hackers Actually Break Into Systems 2026-10-27 aZglGvBPQGs Jev Course – Prefill-Only Inference & Decision Models from Scratch 2026-10-23 JGly6PSK5iw Gemini 4 Argon API Crash Course 2026-10-22 gYXLRMycVMk MCP Security Fundamentals Course

Duas unidades e nenhuma de suas 100 pesquisas diárias. Para obter todos os envios em vez dos cinco mais recentes, percorra a lista de reprodução com os mesmos pageToken loop como no Exemplo 1.

Exemplo 3: obtenha estatísticas de um vídeo e estime o que ele ganhou

videos.list com part=statistics retorna a contagem de visualizações, curtidas e comentários de um vídeo. As contagens de antipatia são privadas desde dezembro de 2021 e favoriteCount é sempre 0, então não construa nada sobre eles. O script também lida com a falta de curtidas ou contagem de comentários, que você verá em alguns vídeos.

Desta vez o fields parâmetro corta a resposta aos valores que usamos. Isso diminui a resposta, mas não altera o custo: a chamada custa 1 unidade de qualquer maneira.

import { yt } from './yt.mjs' const { items: (video) } = await yt('videos', { part: 'snippet,statistics', id: process.argv(2), fields: 'items(snippet(title,publishedAt),statistics(viewCount,likeCount,commentCount))', }) const { viewCount, likeCount, commentCount } = video.statistics const views = Number(viewCount) const rpm = { low: 1, high: 4 } const usd = n => `$${Math.round(n).toLocaleString()}` console.log(video.snippet.title) console.log(`${views.toLocaleString()} views, ${likeCount ? Number(likeCount).toLocaleString() : 'hidden'} likes, ` + `${commentCount ? Number(commentCount).toLocaleString() : 'no'} comments`) console.log(`Estimated earnings: ${usd((views / 1000) * rpm.low)} to ${usd((views / 1000) * rpm.high)}`)

Aqui está o curso completo Aprenda Python do freeCodeCamp, um dos vídeos mais assistidos dessa playlist:

node --env-file=.env video-earnings.mjs rfscVS0vtbw Learn Python - Full Course for Beginners (Tutorial) 49,542,832 views, 1,123,599 likes, 46,100 comments Estimated earnings: $49,543 to $198,171

Trate a última linha como um intervalo aproximado, não como uma resposta. A API de dados não compartilha a receita de ninguém, portanto, qualquer estimativa é de visualizações multiplicadas por um RPM: o que um criador retém por 1.000 visualizações. O RPM varia muito de acordo com o assunto e onde os espectadores moram, e a estimativa pressupõe que o vídeo mostre anúncios, o que nem todo canal faz.

Como permanecer abaixo da sua cota

• Agrupe seus IDs. videos.list leva até 50 IDs para a mesma unidade de um único ID. Assistir 50 vídeos, um de cada vez, custa 50 vezes mais.
• Pule a pesquisa quando souber o que deseja. Procure canais com forHandle e seus vídeos por meio de playlists. Salve suas 100 pesquisas diárias para quando um usuário realmente pesquisar.
• Armazene em cache o que não muda. O título e a duração de um vídeo raramente mudam, então mantenha-os por um tempo, em vez de perguntar novamente a cada carregamento de página. As políticas para desenvolvedores do YouTube limitam por quanto tempo você pode armazenar dados de API, portanto, leia-as antes de armazenar qualquer coisa em cache por dias.
• Não tente novamente cegamente. Solicitações falhadas ainda custam pelo menos 1 unidade. Tente novamente em erros de rede, não em respostas 400 e 403.
• Peça apenas as peças que você usa. Isso não reduzirá o custo, mas respostas menores serão mais rápidas de serem buscadas e analisadas.

E às vezes você nem precisa de uma API. Quando criei um testador de fontes, precisei de uma lista de fontes do Google. A API do desenvolvedor do Google Fonts significaria uma chave e uma chamada em cada visita, para uma lista que quase não muda. Em vez disso, gerei um arquivo com as 500 fontes mais populares uma vez, a partir dos metadados de fontes públicas do Google, e a página o carrega como qualquer outro arquivo. Sem chave, sem cota e nada para falhar.

Erros comuns de chave de API do YouTube

Quando uma chamada falha, a resposta error.message e error.details(0).reason dizer por quê. Estes são os que você mais verá:

Mensagem de erro Razão Consertar Chave de API inválida. Por favor, passe uma chave de API válida. API_KEY_INVALID (400) Verifique se há um erro de digitação ou espaço perdido e certifique-se de enviar a chave que você pensa que está. A API de dados do YouTube v3 não foi usada no projeto… antes ou está desativada. SERVICE_DISABLED (403) Ative a API de dados do YouTube v3 no projeto ao qual a chave pertence. Solicitações do referenciador… são bloqueadas. API_KEY_HTTP_REFERRER_BLOCKED (403) Adicione seu site às restrições de site da chave ou chame a API de um servidor com uma chave restrita por IP. As solicitações para esta API… estão bloqueadas. API_KEY_SERVICE_BLOCKED (403) As restrições da API da chave não incluem a API de dados do YouTube v3. Adicione. A solicitação não pode ser concluída porque você excedeu sua cota. quotaExceeded (403) Aguarde a redefinição à meia-noite, horário do Pacífico, reduza suas chamadas ou solicite mais cota.

Para o erro de chave inválida, a resposta completa é semelhante a esta:

{ "error": { "code": 400, "message": "API key not valid. Please pass a valid API key.", "errors": ( { "message": "API key not valid. Please pass a valid API key.", "domain": "global", "reason": "badRequest" } ), "status": "INVALID_ARGUMENT", "details": ( { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "API_KEY_INVALID", "domain": "googleapis.com", "metadata": { "service": "youtube.googleapis.com" } }, { "@type": "type.googleapis.com/google.rpc.LocalizedMessage", "locale": "en-US", "message": "API key not valid. Please pass a valid API key." } ) } }

Perguntas frequentes

A chave da API do YouTube é gratuita?

Sim. Criar uma chave e chamar a API de dados do YouTube não custa nada. Em vez disso, você está limitado pela cota diária e não há nível pago: mais cota é obtida por meio de uma auditoria.

Onde encontro minha chave de API do YouTube?

No console do Google Cloud, selecione seu projeto e acesse APIs e serviços > Credenciais. Suas chaves estão listadas em Chaves de APIcom um Mostrar chave opção ao lado de cada um.

Posso usar uma chave de API do YouTube em JavaScript front-end?

Funciona, mas qualquer pessoa pode ler a chave da sua página. Se você fizer isso, restrinja a chave ao seu site e à API de dados do YouTube v3. Uma pequena rota de servidor que chama a API para você é mais segura e oferece um lugar para armazenar os resultados em cache.

Quantas solicitações posso fazer por dia?

Por padrão, 100 pesquisas, 100 uploads e 10.000 unidades para todo o resto. A maioria das leituras custa 1 unidade e videos.list leva 50 IDs por chamada, o que é suficiente para os detalhes de até 500.000 vídeos por dia.

Concluindo

Obter uma chave de API do YouTube é a parte fácil: um projeto, uma API para ativar, uma chave e duas restrições. A cota para 2026 é generosa se você trabalhar com ela:

• Lote até 50 IDs por videos.list chamar.
• Evite pesquisa quando um identificador ou lista de reprodução servirá, já que a pesquisa tem seu próprio limite de 100 chamadas.
• Cache o que não muda e não chame uma API para dados que você pode enviar como um arquivo.

Todos os três exemplos juntos custam 7 unidades, em 10.000. A partir daqui, tente commentThreads.list para extrair 100 comentários de um vídeo de cada vez ou estender o Exemplo 2 para percorrer todo o histórico de envio de um canal e adicionar tudo com o código do Exemplo 1.

Source link