Estamos atualizando a API Data para corresponder à forma como o YouTube conta as visualizações dos Shorts.
Saiba mais
Implementação: legendas
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Os exemplos a seguir mostram como usar a API Data do YouTube (v3) para realizar funções relacionadas às legendas.
Extrair uma lista de faixas de legendas de um vídeo
Criar uma faixa de legenda
Essa consulta não pode ser testada usando o APIs Explorer porque ele não oferece suporte para fazer upload de arquivos, o que é um requisito para esse método.
Você pode usar o método captions.insert da API para fazer o upload de uma nova faixa de legenda para um vídeo. Ao fazer o upload de uma faixa, você precisa especificar um valor para as seguintes propriedades de recurso caption:
As seguintes opções adicionais estão disponíveis ao fazer o upload de uma faixa de legenda:
-
Se você definir o parâmetro sync como true, o YouTube vai ignorar todos os códigos de tempo no arquivo de legenda enviado e gerar novos códigos de tempo para as legendas.
Defina o parâmetro sync como true se você estiver fazendo upload de uma transcrição que não tem códigos de tempo ou se você suspeita que os códigos de tempo no seu arquivo estão incorretos e quer que o YouTube tente corrigi-los.
-
Se você definir a propriedade snippet.isDraft do recurso caption como true, a faixa não vai ficar visível ao público.
Consulte a documentação do método captions.insert para conferir exemplos de código.
Fazer o download de uma faixa de legenda
Essa consulta não pode ser testada usando o APIs Explorer porque ele não oferece suporte para download de arquivos.
Para fazer o download de uma faixa de legenda específica, chame o método captions.download. Defina o valor do parâmetro id como o ID da faixa de legenda do YouTube que identifica exclusivamente a faixa de legenda que você está fazendo o download. Sua solicitação precisa ser autorizada usando o OAuth 2.0.
A API v3 é compatível com as seguintes opções:
-
Para especificar que uma faixa de legenda precisa ser retornada em um formato específico, defina o valor do parâmetro tfmt para identificar o formato desejado. A definição do parâmetro lista os valores aceitos.
-
Para recuperar a tradução de uma faixa de legenda, defina o valor do parâmetro tlang como um código de idioma de duas letras ISO 639-1 que identifica o idioma de legenda desejado. A tradução é gerada usando tradução automática, como o Google Tradutor.
Consulte a documentação do método captions.download para conferir exemplos de código.
Atualizar uma faixa de legenda
A API oferece suporte à capacidade de mudar o status de rascunho de uma faixa de legenda, fazer upload de uma nova faixa de legenda para um arquivo ou ambos.
Use o APIs Explorer para testar a capacidade de mudar o status de rascunho de uma faixa. No entanto, não é possível usar o APIs Explorer para atualizar a faixa de legenda real, porque a ferramenta não oferece suporte ao upload de arquivos.
A solicitação abaixo recupera uma lista de legendas de um vídeo no canal do YouTube do Google Stories:
A solicitação atualiza o status de rascunho de uma faixa de legenda para true, o que significa que a faixa não será visível publicamente. Para concluir a solicitação no APIs Explorer, você precisa definir o valor da propriedade id para identificar uma faixa de legenda.
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.captions.update?
part=snippet
Consulte a documentação do método captions.update para conferir exemplos de código.
Excluir uma faixa de legenda
Este exemplo mostra como excluir uma faixa de legenda. O exemplo tem as seguintes etapas:
Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2024-11-23 UTC.
[null,null,["Última atualização 2024-11-23 UTC."],[[["\u003cp\u003eThis document provides instructions on how to use the YouTube Data API (v3) to manage video captions.\u003c/p\u003e\n"],["\u003cp\u003eYou can retrieve a list of caption tracks for a specific video using the \u003ccode\u003ecaptions.list\u003c/code\u003e method, requiring OAuth 2.0 authorization.\u003c/p\u003e\n"],["\u003cp\u003eUploading a new caption track to a video is achieved using the \u003ccode\u003ecaptions.insert\u003c/code\u003e method, requiring the \u003ccode\u003esnippet.videoId\u003c/code\u003e, \u003ccode\u003esnippet.language\u003c/code\u003e, and \u003ccode\u003esnippet.name\u003c/code\u003e properties to be set.\u003c/p\u003e\n"],["\u003cp\u003eDownloading a specific caption track is possible via the \u003ccode\u003ecaptions.download\u003c/code\u003e method, including options to specify the desired format and retrieve a translated version.\u003c/p\u003e\n"],["\u003cp\u003eThe API allows for updating a caption track's draft status and even deleting it completely using the \u003ccode\u003ecaptions.update\u003c/code\u003e and \u003ccode\u003ecaptions.delete\u003c/code\u003e methods respectively.\u003c/p\u003e\n"]]],["The YouTube Data API (v3) facilitates caption management. Key actions include: retrieving caption track lists for a video via `captions.list`; creating new tracks with `captions.insert`, specifying video ID, language, and name; downloading tracks with `captions.download`, allowing format and language selection; updating track status or file with `captions.update`; and deleting tracks using `captions.delete` after retrieving the track ID. Uploading caption files cannot be tested in the APIs Explorer.\n"],null,["# Implementation: Captions\n\nThe following examples show how to use the YouTube Data API (v3) to perform functions related to captions.\n\nRetrieve a list of caption tracks for a video\n---------------------------------------------\n\nTo retrieve a list of caption tracks that are available for a specific video, call the [captions.list](/youtube/v3/docs/captions/list) method. Set the [videoId](/youtube/v3/docs/captions/list#videoId) parameter value to the YouTube video ID that uniquely identifies the video for which you are retrieving captions. Your request must be authorized using OAuth 2.0.\n\nThe request below retrieves a list of captions for a video on the Google Stories YouTube channel: \n\n```\nhttps://developers.google.com/apis-explorer/#p/youtube/v3/youtube.captions.list?\npart=snippet\n&videoId=PRU2ShMzQRg\n```\n\nSee the [captions.list](/youtube/v3/docs/captions/list#usage) method's documentation for code samples.\n\nCreate a caption track\n----------------------\n\nThis query cannot be tested using the APIs Explorer because the APIs Explorer does not support the ability to upload files, which is a requirement for this method.\n\nYou can use the API's [captions.insert](/youtube/v3/docs/captions/insert) method to upload a new caption track for a video. When uploading a track, you must specify a value for the following `caption` resource properties:\n\n\u003cbr /\u003e\n\n- [snippet.videoId](/youtube/v3/docs/captions#snippet.videoId) - This identifies the video to which the caption track is being added.\n- [snippet.language](/youtube/v3/docs/captions#snippet.language) - The language of the caption track.\n- [snippet.name](/youtube/v3/docs/captions#snippet.name) - The name of the caption track.\n\n\u003cbr /\u003e\n\nThe following additional options are available when uploading a caption track:\n\n- If you set the [sync](/youtube/v3/docs/captions/insert#sync) parameter to `true`, YouTube will disregard any time codes that are in the uploaded caption file and generate new time codes for the captions.\n\n You should set the [sync](/youtube/v3/docs/captions/insert#sync) parameter to `true` if you are uploading a transcript, which has no time codes, or if you suspect the time codes in your file are incorrect and want YouTube to try to fix them.\n- If you set the `caption` resource's [snippet.isDraft](/youtube/v3/docs/captions#snippet.isDraft) property to `true`, the track will not be publicly visible.\n\nSee the [captions.insert](/youtube/v3/docs/captions/insert#examples) method's documentation for code samples.\n\nDownload a caption track\n------------------------\n\nThis query cannot be tested using the APIs Explorer because the APIs Explorer does not support the ability to download files.\n\nTo download a specific caption track, call the [captions.download](/youtube/v3/docs/captions/download) method. Set the [id](/youtube/v3/docs/captions/download#id) parameter value to the YouTube caption track ID that uniquely identifies the caption track that you are downloading. Your request must be authorized using OAuth 2.0.\n\nThe v3 API supports the following options:\n\n- To specify that a caption track should be returned in a specific format, set the [tfmt](/youtube/v3/docs/captions/download#tfmt) parameter value to identify the desired format. The parameter definition lists supported values.\n\n- To retrieve a translation of a caption track, set the [tlang](/youtube/v3/docs/captions/download#tlang) parameter value to an [ISO 639-1 two-letter language code](http://www.loc.gov/standards/iso639-2/php/code_list.php) that identifies the desired caption language. The translation is generated by using machine translation, such as Google Translate.\n\nSee the [captions.download](/youtube/v3/docs/captions/download#examples) method's documentation for code samples.\n\nUpdate a caption track\n----------------------\n\nThe API supports the ability to change a caption track's [draft status](/youtube/v3/docs/captions#snippet.isDraft), upload a new caption track for a file, or both.\n\nYou can use the APIs Explorer to test the ability to change a track's draft status. However, you cannot use the APIs Explorer to update the actual caption track because tool does not support the ability to upload files.\n\nThe request below retrieves a list of captions for a video on the Google Stories YouTube channel:\n\nThe request updates the draft status of a caption track to `true`, which means the track will not be publicly visible. To complete the request in the APIs Explorer, you need to set the `id` property's value to identify a caption track. \n\n```\nhttps://developers.google.com/apis-explorer/#p/youtube/v3/youtube.captions.update?\npart=snippet\n```\n\nSee the [captions.update](/youtube/v3/docs/captions/update#usage) method's documentation for code samples.\n\nDelete a caption track\n----------------------\n\nThis example shows how to delete a caption track. The example has the following steps:\n\n- **Step 1: Retrieve the caption track ID**\n\n Follow the steps above to [retrieve a list of caption tracks](#captions-list) for a video. The list could be used to display a list of caption tracks, using each track's ID as a key.\n- **Step 2: Delete the track**\n\n Call the [captions.delete](/youtube/v3/docs/captions/delete) method to delete a specific video. In the request, the `id` parameter specifies the caption track ID of the track that you are deleting. The request must be authorized using OAuth 2.0. If you are testing this query in the APIs Explorer, you will need to substitute a valid caption track ID for the `id` parameter value. \n\n ```\n https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.captions.delete?\n id=CAPTION_TRACK_ID\n ```"]]
