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 seções a seguir 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.

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. A 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 maneiras:

    • 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

    Instruções completas para implementar a autenticação do 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 canal ou usuário específico realizou no YouTube. As ações informadas nos feeds de atividades incluem avaliar, compartilhar, marcar como favorito, enviar um vídeo e assim por diante. 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.

Legendas

Um recurso caption representa uma faixa de legenda do YouTube. Uma faixa de legenda está 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 da faixa, fazer upload de um novo arquivo de legenda para ela ou ambos.

channelBanners

Um recurso channelBanner contém o URL que você usaria para definir uma imagem recém-enviada como a imagem do 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. Esse método representa as duas primeiras etapas de um processo de três etapas para atualizar a imagem do banner de um canal:
  1. Chame o método channelBanners.insert para fazer upload dos dados de imagem binários para o YouTube. A imagem precisa ter uma proporção de 16:9 e pelo menos 2048 x 1152 pixels. Recomendamos fazer upload de uma imagem de 2560 x 1440 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 de branding do canal. Defina o valor da propriedade brandingSettings.image.bannerExternalUrl como o URL obtido na 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 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 o conteúdo for exibido em uma visualização de navegação, e não em um feed. Para permitir que um canal mostre 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 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 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. Esse método só aceita 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 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 recursos comment aninhados dentro do recurso commentThread. O recurso commentThread não contém necessariamente todas as respostas a um comentário. Use o método comments.list se quiser 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 conversas em comentários que correspondem aos parâmetros da 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 um 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 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 para um comentário. Observação:para criar um comentário de nível superior, use o método commentThreads.insert.
delete DELETE /comments Exclui um comentário.
update PUT /comments Modifica um comentário.

I18nLanguages

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

Cada recurso i18nLanguage identifica um código e um nome de idioma. O código de idioma pode ser usado como o valor do parâmetro hl ao chamar métodos de API como 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 /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. Um usuário também pode selecionar manualmente a região de conteúdo no rodapé do site do YouTube.

Cada recurso i18nRegion identifica um código e um nome de região. 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 conversar quando o criador de conteúdo ativa o modo exclusivo para membros em um chat.

Para mais informações sobre esse recurso, consulte a representação de 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 (antes chamados de "patrocinadores") de um canal. O pedido de API precisa ser autorizado pelo proprietário do canal.

MembershipsLevels

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

Para mais informações sobre esse recurso, consulte a representação de 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 de propriedade do canal que autorizou a solicitação de 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 está 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 na playlist.

O YouTube também usa uma playlist para identificar a lista de vídeos enviados de um canal, com cada playlistItem nessa lista representando um vídeo enviado. Você pode recuperar 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 de um canal, como:

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

Para ser mais específico, essas listas estão associadas a um canal, que é um conjunto de vídeos de uma pessoa, grupo ou empresa, playlists, e outras informações do YouTube. É possível recuperar os IDs de playlist de cada uma dessas listas no channel resource de um determinado 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.

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 da pesquisa que correspondem aos parâmetros de consulta especificados na solicitação da API. Por padrão, um conjunto de resultados de pesquisa identifica recursos video, channel e playlist correspondentes, mas você também pode configurar consultas para recuperar somente um tipo específico de recurso.

Inscrições

Um recurso subscription contém informações sobre a assinatura de um 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 imagens em miniatura associados a um recurso. 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 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 de um recurso video geralmente tem 120 x 90 pixels, e a imagem em 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 imagem em miniatura tem uma propriedade width e uma propriedade 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 um motivo para um vídeo ser sinalizado por conter conteúdo abusivo. Quando seu 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 Recupera 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 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.