API Reference

A API de dados do YouTube permite a incorporação dr funções normalmente executadas no site do YouTube em seu próprio site ou aplicativo. As listas abaixo identificam os diferentes tipos de recursos que você pode recuperar usando a API. A API também oferece suporte a métodos para inserir, atualizar ou excluir muitos desses recursos.

Este guia de referência explica como usar a API para executar todas essas operações. O guia está organizado por tipo de recurso. Um recurso representa um tipo de item que compreende parte da experiência do YouTube, como um vídeo, uma playlist ou uma inscrição. Para cada tipo de recurso, o guia lista uma ou mais representações de dados, e os recursos são representados como objetos JSON. O guia também lista um ou mais métodos suportados (LIST, POST, DELETE etc.) para cada tipo de recurso e explica como usar esses métodos em seu aplicativo.

Como chamar a API

Os seguintes requisitos aplicam-se às solicitações de API de dados do YouTube:

  1. Todas as solicitações precisam especificar uma chave de API (com o parâmetro key) ou fornecer um token do OAuth 2.0. Sua chave de API está disponível no painel Acesso à API do Console do desenvolvedor do seu projeto.

  2. Você precisa enviar um token de autorização para cada solicitação de inserção, atualização e exclusão. Também é necessário enviar um token de autorização para qualquer solicitação que recupere os dados particulares do usuário autenticado.

    Além disso, alguns métodos de API para recuperação de recursos podem suportar parâmetros que necessitam de autorização ou podem conter metadados adicionais quando as solicitações são autorizadas. Por exemplo, uma solicitação para recuperar os vídeos enviados de um usuário também pode conter vídeos privados, se a solicitação for autorizada por esse usuário específico.

  3. A API suporta o protocolo de autenticação OAuth 2.0. Você pode fornecer um token do OAuth 2.0 de uma das seguintes formas:

    • Use o parâmetro de consulta access_token desta maneira: ?access_token=oauth2-token
    • Use o cabeçalho HTTP Authorization desta forma: Authorization: Bearer oauth2-token

    As instruções completas para implementar a autenticação OAuth 2.0 no seu aplicativo podem ser encontradas no guia de autenticação.

Tipos de recurso

Atividades

Um recurso activity contém informações sobre uma ação que um determinado canal ou usuário realizou no YouTube. As ações relatadas nos feeds de atividades incluem classificar um vídeo, compartilhar um vídeo, marcar um vídeo como favorito, enviar um vídeo e assim por diante. Cada recurso de activity identifica o tipo de ação, o canal associado à ação e os recursos associados à ação, como o vídeo que foi avaliado ou enviado.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
list GET /activities Retorna uma lista de eventos de atividade do canal que correspondem aos critérios da solicitação. Por exemplo, é possível recuperar eventos associados a um canal específico ou ao próprio canal do usuário.
insert POST /activities Observação:esse método foi descontinuado e não é mais compatível.

Legendas

Um recurso caption representa uma faixa de legenda do YouTube. Uma faixa de legenda está associada exatamente a um vídeo do YouTube.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
delete DELETE /captions Exclui a faixa de legenda especificada.
download GET /captions/id Faz o download de uma faixa de legenda. A faixa de legenda é retornada no formato original, a menos que a solicitação especifique um valor para o parâmetro tfmt e no idioma original, a menos que a solicitação especifique um valor para o parâmetro tlang.
insert POST /captions Faz upload de uma faixa de legenda.
list GET /captions Retorna uma lista de faixas de legenda associadas a um vídeo especificado. Observe que a resposta da API não contém as legendas reais e que o método captions.download fornece a capacidade de recuperar uma faixa de legenda.
update PUT /captions Atualiza uma faixa de legenda. Ao atualizar uma faixa de legenda, você pode mudar o status do rascunho, fazer upload de um novo arquivo de legenda ou ambos.

channelBanners

Um recurso do channelBanner contém o URL que você usaria para definir uma imagem recém-enviada como a imagem do banner de um canal.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
insert POST /channelBanners/insert Carrega uma imagem de banner de canal no YouTube. Este método representa as duas primeiras etapas de um processo de três etapas para atualizar a imagem do banner para um canal:

  1. Chame o método channelBanners.insert para fazer upload dos dados binários da imagem para o YouTube. A imagem precisa ter uma proporção de 16:9 e pelo menos 2.048 x 1.152 pixels. Recomendamos enviar uma imagem de 2.560 x 1.440 pixels.
  2. Extraia o valor da propriedade url da resposta que a API retorna para a etapa 1.
  3. Chame o método channels.update para atualizar as configurações da marca do canal. Defina o valor da propriedade brandingSettings.image.bannerExternalUrl como o URL da etapa 2.

ChannelSections

Um recurso channelSection contém informações sobre um conjunto de vídeos que um canal escolheu destacar. Por exemplo, uma seção pode apresentar os envios mais recentes, os mais populares ou os vídeos de uma ou mais playlists.

As seções de um canal só ficam visíveis se o canal exibir conteúdo em uma visualização de navegação, e não em uma visualização de feed. Para permitir que um canal exiba conteúdo em uma visualização de navegação, defina a propriedade brandingSettings.channel.showBrowseView como true para o canal especificado.

Um canal pode criar no máximo 10 seções.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
delete DELETE /channelSections Exclui uma seção do canal.
insert POST /channelSections Adiciona uma seção de canal ao canal do usuário autenticado. O canal pode criar até 10 seções.
list GET /channelSections Retorna uma lista de recursos channelSection que correspondem aos critérios da solicitação de API.
update PUT /channelSections Atualiza uma seção do canal.

Canais

Um recurso channel contém informações sobre um canal do YouTube.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
list GET /channels Retorna um conjunto de zero ou mais recursos channel que correspondem aos critérios da solicitação.
update PUT /channels Atualiza os metadados de um canal. No momento, esse método só oferece suporte a atualizações dos objetos brandingSettings e invideoPromotion do recurso channel e das respectivas propriedades filhas.

Conversas de comentários

Um recurso commentThread contém informações sobre uma conversa no YouTube, que inclui um comentário de nível superior e respostas, se houver, a esse comentário. Um recurso commentThread pode representar comentários sobre um vídeo ou um canal.

Tanto o comentário de nível superior quanto as respostas são, na verdade, comment recursos aninhados no commentThread. O recurso commentThread não contém necessariamente todas as respostas a um comentário, e você precisa usar o método comments.list se quiser recuperar todas as respostas de um comentário específico. Observe também que alguns comentários não têm respostas.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
list GET /commentThreads Retorna uma lista de segmentos de comentários que correspondem aos parâmetros de solicitação da API.
insert POST /commentThreads Cria um novo comentário de nível superior. Para adicionar uma resposta a um comentário, use o método comments.insert.

Comentários

Um recurso comment contém informações sobre um único comentário no YouTube. Um recurso comment pode representar um comentário sobre um vídeo ou um canal. Além disso, o comentário pode ser um comentário de nível superior ou uma resposta a um comentário de nível superior.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
list GET /comments Retorna uma lista de comentários que correspondem aos parâmetros da solicitação de API.
setModerationStatus POST /comments/setModerationStatus Define o status de moderação de um ou mais comentários. A solicitação de API precisa ser autorizada pelo proprietário do canal ou vídeo associado aos comentários.
insert POST /comments Cria uma resposta a um comentário existente. Observação:para criar um comentário de nível superior, use o método commentThreads.insert.
markAsSpam POST /comments/markAsSpam Observação:esse método foi descontinuado e não é mais compatível.
delete DELETE /comments Exclui um comentário.
update PUT /comments Modifica um comentário.

guideCategories

O recurso guideCategory identifica uma categoria que o YouTube atribui algoritmicamente com base no conteúdo ou em outros indicadores de um canal, como a popularidade do canal. A lista é semelhante às categorias de vídeo, com a diferença de que o usuário que fez o envio pode atribuir uma categoria de vídeo, mas somente o YouTube pode atribuir uma categoria de canal.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
list GET /guideCategories Retorna uma lista de categorias que podem ser associadas a canais do YouTube.

I18nIdiomas

O recurso i18nLanguage identifica um idioma do aplicativo que é compatível com o site do YouTube. O idioma do aplicativo também pode ser chamado de idioma da interface. Para o site do YouTube, um idioma do aplicativo pode ser selecionado automaticamente com base nas configurações da Conta do Google, idioma do navegador ou local do IP. Um usuário também pode selecionar manualmente o idioma desejado da IU no rodapé do site do YouTube.

Cada recurso i18nLanguage identifica um código de idioma e um nome. O código de idioma pode ser usado como o valor do parâmetro hl ao chamar métodos de API, como videoCategories.list e guideCategories.list.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
list GET /i18nLanguages Retorna uma lista de idiomas do aplicativo suportados pelo site do YouTube.

Regiões I18n

O recurso i18nRegion identifica uma área geográfica que um usuário do YouTube pode selecionar como região preferida do conteúdo. A região de conteúdo também pode ser chamada de localidade de conteúdo. Para o site do YouTube, uma região de conteúdo pode ser selecionada automaticamente com base em heurísticas como o domínio do YouTube ou o local do IP do usuário. Um usuário também pode selecionar manualmente a região do conteúdo desejada no rodapé do site do YouTube.

Cada recurso i18nRegion identifica um código de região e um nome. O código da região pode ser usado como o valor do parâmetro regionCode ao chamar métodos de API, como search.list, videos.list, activities.list e videoCategories.list.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
list GET /i18nRegions Retorna uma lista de regiões de conteúdo que são suportadas pelo site do YouTube.

Participantes

Um recurso member representa um membro de um canal do YouTube. Um membro oferece apoio monetário recorrente a um criador de conteúdo e recebe benefícios especiais. Por exemplo, os membros podem conversar quando o criador ativa o modo exclusivo para um chat.

Para mais informações sobre esse recurso, consulte a representação do recurso e a lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
list GET /members Lista os membros (anteriormente conhecidos como "patrocinadores") de um canal. A solicitação de API precisa ser autorizada pelo proprietário do canal.

Níveis de assinatura

Um recurso membershipsLevel identifica um nível de preço para o criador que autorizou a solicitação de API.

Para mais informações sobre esse recurso, consulte a representação do recurso e a lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
list GET /membershipsLevels Retorna um conjunto de zero ou mais recursos membershipsLevel pertencentes ao canal que autorizou a solicitação de API. Os níveis são retornados em ordem de exibição implícita.

PlaylistItems

Um recurso playlistItem identifica outro recurso incluído em uma playlist, por exemplo, um vídeo. Além disso, o recurso playlistItem contém detalhes sobre o recurso incluído que dizem respeito especificamente à forma como esse recurso é usado nessa playlist.

O YouTube também usa uma playlist para identificar a lista de vídeos enviados de um canal, e cada playlistItem nessa lista representa um vídeo enviado. Você pode recuperar o ID da playlist para essa lista a partir de channel resource para um determinado canal. Em seguida, use o método playlistItems.list para a lista.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
delete DELETE /playlistItems Exclui um item da playlist.
insert POST /playlistItems Adiciona um recurso a uma playlist.
list GET /playlistItems Retorna um conjunto de itens da playlist que correspondem aos parâmetros da solicitação de API. Você pode recuperar todos os itens da playlist em uma playlist especificada ou recuperar um ou mais itens da playlist por seus IDs exclusivos.
update PUT /playlistItems Modifica um item da playlist. Por exemplo, você poderia atualizar a posição do item na playlist.

Playlists

Um recurso playlist representa uma playlist do YouTube. Uma playlist é um conjunto de vídeos que podem ser visualizados em sequência e compartilhados com outros usuários. Uma playlist pode conter até 200 vídeos e o YouTube não limita o número de playlists que cada usuário cria. Por padrão, as playlists ficam visíveis publicamente a outros usuários, mas elas podem ser públicas ou privadas.

O YouTube também usa playlists para identificar coleções especiais de vídeos para um canal, como:

  • vídeos enviados
  • vídeos avaliados positivamente (gostei)
  • histórico de visualização
  • Assistir mais tarde
Mais especificamente, essas listas são associadas a um canal, que é um conjunto de vídeos, playlists e outras informações do YouTube de uma pessoa, um grupo ou uma empresa. É possível recuperar os IDs das playlists para cada uma dessas listas de channel resource para um determinado canal.

Depois, use o método playlistItems.list para recuperar qualquer uma dessas listas. Também é possível adicionar ou remover itens dessas listas chamando os métodos playlistItems.insert e playlistItems.delete.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
delete DELETE /playlists Exclui uma playlist.
list GET /playlists Retorna um conjunto de playlists que correspondem aos parâmetros da solicitação de API. Por exemplo, você pode recuperar todas as playlists que o usuário autenticado possui ou recuperar uma ou mais playlists por seus IDs únicos.
insert POST /playlists Cria uma playlist.
update PUT /playlists Modifica uma playlist. Por exemplo, você pode alterar o título, a descrição ou o status de privacidade de uma playlist.

Um resultado da pesquisa contém informações sobre um vídeo, um canal ou uma playlist do YouTube que corresponde aos parâmetros de pesquisa especificados em uma solicitação de API. Embora um resultado da pesquisa aponte para um recurso exclusivamente identificável, como um vídeo, ele não tem os próprios dados persistentes.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
list GET /search Retorna um conjunto de resultados de pesquisa que correspondem aos parâmetros de consulta especificados na solicitação de API. Por padrão, um conjunto de resultados da pesquisa identifica recursos correspondentes de video, channel e playlist, mas você também pode configurar consultas para extrair apenas um tipo específico de recurso.

Assinaturas

Um recurso subscription contém informações sobre uma inscrição de usuário do YouTube. Uma inscrição notifica o usuário quando novos vídeos são adicionados a um canal ou quando outro usuário executa uma das várias ações no YouTube, como o upload ou a classificação de um vídeo ou comentários sobre um vídeo.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
delete DELETE /subscriptions Exclui uma assinatura.
insert POST /subscriptions Adiciona uma inscrição para o canal do usuário autenticado.
list GET /subscriptions Retorna recursos de inscrição que correspondem a critérios da solicitação da API.

Miniaturas

Um recurso thumbnail identifica diferentes tamanhos de imagens em miniatura associados a um recurso. Observe as seguintes características das imagens em miniatura:

  • A propriedade snippet.thumbnails de um recurso é um objeto que identifica as imagens em miniatura disponíveis para esse recurso.
  • Um recurso thumbnail contém uma série de objetos. O nome de cada objeto (default, medium, high etc.) refere-se ao tamanho da imagem em miniatura.
  • Diferentes tipos de recursos podem suportar diferentes tamanhos de imagens em miniatura.
  • Diferentes tipos de recursos podem definir tamanhos diferentes para imagens em miniatura com o mesmo nome. Por exemplo, a imagem em miniatura default para um recurso video normalmente tem 120 x 90 pixels, e a imagem default para um recurso channel normalmente tem 88 x 88 pixels.
  • Recursos do mesmo tipo ainda podem ter diferentes tamanhos de imagem em miniatura para determinadas imagens, dependendo da resolução da imagem original ou do conteúdo carregado no YouTube. Por exemplo, um vídeo em HD pode apoiar miniaturas de resolução maior que vídeos não HD.
  • Cada objeto que contém informações sobre um tamanho de imagem em miniatura tem uma propriedade width e uma height. No entanto, as propriedades de largura e altura podem não ser retornadas para essa imagem.
  • Se uma imagem em miniatura carregada não corresponder às dimensões necessárias, a imagem será redimensionada para corresponder ao tamanho correto, sem alteração de sua proporção. A imagem não é cortada, mas pode incluir barras pretas para que o tamanho fique correto.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
set POST /thumbnails/set Carrega uma miniatura de vídeo personalizada para o YouTube e a define para um vídeo.

VideoAbuseReportReason

Um recurso videoAbuseReportReason contém informações sobre o motivo pelo qual um vídeo seria sinalizado por conter conteúdo abusivo. Quando o aplicativo chama o método videos.reportAbuse para denunciar um vídeo abusivo, a solicitação usa as informações de um recurso videoAbuseReportReason para identificar o motivo da denúncia.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
list GET /videoAbuseReportReasons Recuperar uma lista de motivos que podem ser usados para denunciar vídeos abusivos.

VideoCategories

O recurso videoCategory identifica uma categoria que foi ou poderia ser associada a vídeos enviados.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
list GET /videoCategories Retorna uma lista de categorias que podem ser associadas a vídeos do YouTube.

Vídeos

O recurso video representa um vídeo do YouTube.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
insert POST /videos Envia um vídeo para o YouTube e, opcionalmente, define os metadados do vídeo.
list GET /videos Retorna uma lista de vídeos que correspondem aos parâmetros de solicitação da API.
delete DELETE /videos Exclui um vídeo do YouTube.
update PUT /videos Atualiza os metadados de um vídeocanal..
rate POST /videos/rate Adiciona uma classificação gostei ou não gostei a um vídeo ou remove uma classificação de um vídeo.
getRating GET /videos/getRating Recupera as classificações que o usuário autorizado deu a uma lista de vídeos especificados.
reportAbuse POST /videos/reportAbuse Denunciar um vídeo por conteúdo abusivo.

Marcas-d'água

Um recurso watermark identifica uma imagem exibida durante reproduções de vídeos de um canal especificado. Você também pode especificar um canal de destino ao qual a imagem será vinculada, além dos detalhes de sincronismo que determinam quando uma marca d'água aparece durante reproduções de vídeo e o período em que ela estará visível.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
set POST /watermarks/set Envia uma imagem de marca d'água para o YouTube e define-a para um canal.
unset POST /watermarks/unset Exclui a imagem de marca-d'água do canal.