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. Cada solicitação precisa 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 para desenvolvedores do seu projeto.

  2. Você precisa enviar um token de autorização para cada solicitação de inserção, atualização e exclusão. Você também precisa 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 forma: ?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 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 atividade 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 activity identifica o tipo de ação, o canal associado à ação e os recursos associados a ela, 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 determinado canal 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 é 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 Carrega uma faixa de legenda.
list GET /captions Retorna uma lista de faixas de legendas associadas a um vídeo especificado. 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, é possível mudar o status do rascunho, fazer upload de um novo arquivo de legenda 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 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 enviar os 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 2560 x 1440 pixels.
  2. Extraia o valor da propriedade url da resposta que a API retorna na etapa 1.
  3. Chame o método channels.update para atualizar as configurações de 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 optou por destacar. Por exemplo, uma seção pode incluir os envios mais recentes, os mais acessados ou os vídeos de uma ou mais playlists.

As seções de um canal só ficam visíveis se o canal mostrar conteúdo em uma visualização de navegação, e nã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. Um 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 propriedades filhas deles.

CommentThreads

Um recurso commentThread contém informações sobre uma conversa do YouTube, que compreende 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 canal.

O comentário de nível superior e 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. Além disso, 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 conversas 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 existente, 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 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 para 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

Um recurso guideCategory identifica uma categoria que o YouTube atribui algoritmicamente com base no conteúdo de um canal ou em outros indicadores, como a popularidade do canal. A lista é semelhante a categorias de vídeo. A diferença é 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.

I18nLanguages

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

Cada recurso i18nLanguage identifica um código de idioma e um nome. O código do 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 de aplicativos com suporte no 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. 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. O 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 o site do YouTube suporta.

Participantes

Um recurso member representa um membro de um canal do YouTube. Um membro oferece apoio monetário recorrente ao criador de conteúdo e recebe benefícios especiais. Por exemplo, os membros podem conversar quando o criador ativa o modo exclusivo para membros no 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.

MembershipsLevels

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 de propriedade do canal que autorizou a solicitação de API. Os níveis são retornados em ordem de exibição implícita.

PlaylistItems

O 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 se referem 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. Cada playlistItem nessa lista representa um vídeo enviado. Você pode recuperar o ID da playlist para essa lista no channel resource de 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
Para ser mais específico, essas listas estão associadas a um canal, que é um conjunto de vídeos, playlists e outras informações do YouTube de uma pessoa, grupo ou empresa. Você pode recuperar os IDs das playlists para cada uma dessas listas no channel resource de 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, canal ou playlist do YouTube que correspondem 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 da pesquisa que correspondem aos parâmetros de consulta especificados na solicitação de API. Por padrão, um conjunto de resultados da pesquisa identifica os recursos correspondentes de video, channel e playlist, mas também é possível configurar consultas para recuperar 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

O recurso thumbnail identifica diferentes tamanhos de imagens em miniatura associadas 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 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 normalmente tem 120 x 90 pixels, e a 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.

VideoAbuseReportReasons

Um recurso videoAbuseReportReason contém informações sobre o motivo de 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 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 Recupere 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 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

Um 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 que é mostrada 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 de um canal.