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 podem ser recuperados 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. Cada solicitação precisa especificar uma chave de API (com o parâmetro key) ou fornecer um token OAuth 2.0. Sua chave de API está disponível no painel Acesso à API do Console para desenvolvedores do seu projeto.

2. Você deve enviar um token de autorização para cada solicitação de inserção, atualização e exclusão. Você também deve enviar um token de autorização para qualquer solic que recupera os dados privados 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 maneira: Authorization: Bearer oauth2-token

   As instruções completas para implementar a autenticação do OAuth 2.0 no seu aplicativo estão disponíveis no guia de autenticação.

Tipos de recurso

Atividades

Um recurso activity contém informações sobre uma ação realizada por um canal ou usuário específico no YouTube. As ações informadas nos feeds de atividades incluem a classificação de um vídeo, o compartilhamento de um vídeo, a marcação de um vídeo como favorito, o envio de um vídeo etc. Cada recurso activity identifica o tipo de ação, o canal associado a ela e os recursos associados, como o vídeo que foi avaliado ou enviado.

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

Método	Solicitação HTTP	Descrição
URIs relativos 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 canal do usuário.
insert	POST /activities	Observação:este método foi descontinuado e não tem mais suporte.

Legendas

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

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

Método	Solicitação HTTP	Descrição
URIs relativos 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. A resposta da API não contém as legendas reais, e o método captions.download permite recuperar uma faixa de legenda.
update	PUT /captions	Atualiza uma faixa de legenda. Ao atualizar uma faixa de legenda, você pode mudar o status de rascunho dela, fazer upload de um novo arquivo de legenda ou fazer as duas coisas.

channelBanners

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

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

Método	Solicitação HTTP	Descrição
URIs relativos 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: Chame o método channelBanners.insert para enviar os dados de imagem binária ao 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 2560 x 1440 pixels. Extraia o valor da propriedade url da resposta que a API retorna para a etapa 1. Chame o método channels.update para atualizar as configurações de branding do canal. Defina o valor da propriedade brandingSettings.image.bannerExternalUrl como o URL recebido na etapa 2.

ChannelSections

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

As seções de um canal só ficam visíveis se ele mostra conteúdo em uma visualização de navegação, e não no 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 obter mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

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

Canais

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

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

Método	Solicitação HTTP	Descrição
URIs relativos a https://www.googleapis.com/youtube/v3
list	GET /channels	Retorna uma coleção 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 nos objetos brandingSettings e invideoPromotion do recurso channel e nas propriedades filhas deles.

CommentThreads

Um recurso commentThread contém informações sobre uma conversa de comentários do YouTube, que inclui um comentário de nível superior e as respostas, se houver. 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 recursos comment aninhados no recurso commentThread. O recurso commentThread não contém necessariamente todas as respostas a um comentário. Use o método comments.list para recuperar todas as respostas de um comentário específico. Além disso, alguns comentários não têm respostas.

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

Método	Solicitação HTTP	Descrição
URIs relativos a https://www.googleapis.com/youtube/v3
list	GET /commentThreads	Retorna uma lista de linhas 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 do YouTube. Um recurso comment pode representar um comentário sobre um vídeo ou canal. Além disso, o comentário pode ser de nível superior ou uma resposta a um comentário de nível superior.

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

Método	Solicitação HTTP	Descrição
URIs relativos a https://www.googleapis.com/youtube/v3
list	GET /comments	Retorna uma lista de comentários que correspondem aos parâmetros da solicitação da API.
setModerationStatus	POST /comments/setModerationStatus	Define o status de moderação de um ou mais comentários. A solicitação da API precisa ser autorizada pelo proprietário do canal ou do 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 tem mais suporte.
delete	DELETE /comments	Exclui um comentário.
update	PUT /comments	Modifica um comentário.

guideCategories

Um recurso guideCategory identifica uma categoria que o YouTube atribui de forma algorítmica com base no conteúdo de um canal ou em outros indicadores, como a popularidade dele. A lista é semelhante às categorias de vídeo, mas a diferença é que o usuário que enviou o conteúdo pode atribuir uma categoria de vídeo, mas apenas 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 relativos a https://www.googleapis.com/youtube/v3
list	GET /guideCategories	Retorna uma lista de categorias que podem ser associadas a canais do YouTube.

I18nLanguages

Um recurso i18nLanguage identifica um idioma de aplicativo compatível com o site do YouTube. A linguagem do aplicativo também pode ser chamada de linguagem da interface. No site do YouTube, um idioma de aplicativo pode ser selecionado automaticamente com base nas configurações da Conta do Google, no idioma do navegador ou na localização do IP. O usuário também pode selecionar manualmente o idioma da interface desejado 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 obter mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método	Solicitação HTTP	Descrição
URIs relativos a https://www.googleapis.com/youtube/v3
list	GET /i18nLanguages	Retorna uma lista de idiomas de aplicativos compatíveis com o site do YouTube.

I18nRegions

Um recurso i18nRegion identifica uma área geográfica que um usuário do YouTube pode selecionar como a região de conteúdo preferida. A região de conteúdo também pode ser chamada de localidade de conteúdo. No 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. O usuário também pode selecionar manualmente a região de 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 obter mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método	Solicitação HTTP	Descrição
URIs relativos a https://www.googleapis.com/youtube/v3
list	GET /i18nRegions	Retorna uma lista de regiões de conteúdo compatíveis com o site do YouTube.

Membros

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

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 relativos a https://www.googleapis.com/youtube/v3
list	GET /members	Lista os membros (antigos "patrocinadores") de um canal. A solicitação da API precisa ser autorizada pelo proprietário do canal.

MembershipsLevels

Um recurso membershipsLevel identifica um nível de preço para o criador que autorizou a solicitação da 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 relativos a https://www.googleapis.com/youtube/v3
list	GET /membershipsLevels	Retorna uma coleção de zero ou mais recursos membershipsLevel pertencentes ao canal que autorizou a solicitação da API. Os níveis são retornados na ordem de exibição implícita.

PlaylistItems

Um recurso playlistItem identifica outro recurso, como um vídeo, que é incluído em uma playlist. Além disso, o recurso playlistItem contém detalhes sobre o recurso incluído que se referem especificamente a como ele é usado nessa playlist.

O YouTube também usa uma playlist para identificar a lista de vídeos enviados de um canal, com cada playlistItem na lista representando um vídeo enviado. É possível extrair o ID da playlist dessa lista no channel resource de um determinado canal. Em seguida, use o método playlistItems.list na lista.

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

Método	Solicitação HTTP	Descrição
URIs relativos 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. 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 em um canal, como:

• vídeos enviados
• vídeos avaliados positivamente (gostei)
• histórico de visualização
• Assistir mais tarde

Mais especificamente, essas listas estão associadas a um canal, que é uma coleção de vídeos, playlists e outras informações do YouTube de uma pessoa, grupo ou empresa. É possível extrair os IDs de cada uma dessas listas do channel resource de um canal.

Em seguida, 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 obter mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método	Solicitação HTTP	Descrição
URIs relativos 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.

Pesquisar

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

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

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

Inscrições

Um recurso subscription contém informações sobre uma assinatura 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 relativos 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 miniatura de imagem 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.) se refere ao tamanho da 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 de miniatura default de um recurso video geralmente tem 120 x 90 pixels, e a imagem de miniatura default de um recurso channel geralmente 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 o tamanho de uma 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 relativos 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.

VideoAbuseReportReasons

Um recurso videoAbuseReportReason contém informações sobre o motivo pelo qual um vídeo foi 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 obter mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

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

VideoCategories

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

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

Método	Solicitação HTTP	Descrição
URIs relativos 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

Um recurso video representa um vídeo do YouTube.

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

Método	Solicitação HTTP	Descrição
URIs relativos 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 conter conteúdo abusivo.

Marcas-d'água

Um recurso watermark identifica uma imagem que aparece durante a reprodução dos vídeos de um canal específico. 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 obter mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método	Solicitação HTTP	Descrição
URIs relativos 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 de um canal.