Os exemplos a seguir mostram como usar a API de dados do YouTube (v3) para executar funções relacionadas às legendas.
Recuperar uma lista de faixas de legenda de um vídeo
Para recuperar uma lista de faixas de legendas disponíveis para um vídeo específico, chame o método captions.list
. Defina o valor do parâmetro videoId
para o ID do vídeo do YouTube que identifica exclusivamente o vídeo para o qual você está recuperando legendas. Sua solicitação precisa ser autorizada usando o OAuth 2.0.
A solicitação abaixo recupera uma lista de legendas ocultas para um vídeo no canal do YouTube das histórias do Google:
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.captions.list? part=snippet &videoId=PRU2ShMzQRg
Consulte a documentação do método captions.list
para ver exemplos de código.
Criar uma faixa de legenda
Não é possível testar essa consulta usando o APIs Explorer porque ele não é compatível com o upload de arquivos, que é um requisito desse método.
Você pode usar o método captions.insert
da API para enviar uma nova faixa de legenda para um vídeo. Ao fazer upload de uma faixa, é necessário especificar um valor para as seguintes propriedades de recurso caption
:
snippet.videoId
: identifica o vídeo ao qual a faixa de legenda está sendo adicionada.snippet.language
: o idioma da faixa de legenda.snippet.name
: o nome da faixa de legenda.
As seguintes opções adicionais estão disponíveis no envio de faixas de legenda:
-
Se você definir o parâmetro
sync
comotrue
, o YouTube vai ignorar os códigos de tempo que estão no arquivo de legenda enviado e gerar novos códigos de tempo para as legendas.Defina o parâmetro
sync
comotrue
se você estiver fazendo upload de uma transcrição sem códigos de tempo ou se suspeitar que os códigos de arquivo no seu arquivo estão incorretos e quiser que o YouTube tente corrigi-los. -
Se você definir a propriedade
snippet.isDraft
do recursocaption
comotrue
, a faixa não ficará visível publicamente.
Consulte a documentação do método captions.insert
para ver exemplos de código.
Fazer o download de uma faixa de legenda
Não é possível testar esta consulta usando o APIs Explorer porque o APIs Explorer não é compatível com o recurso de 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 de forma exclusiva a faixa de legenda que você está baixando. 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 pretendido. A definição do parâmetro lista os valores compatíveis. -
Para recuperar uma 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 identifique o idioma da legenda. A tradução é gerada usando uma tradução automática, como o Google Tradutor.
Consulte a documentação do método captions.download
para ver exemplos de código.
Atualizar uma faixa de legenda
A API é compatível com a capacidade de alterar o status de rascunho de uma faixa de legenda, fazer upload de uma nova faixa de legenda para um arquivo ou ambas.
Você pode usar o APIs Explorer para testar a capacidade de alterar 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 tem suporte à capacidade de upload de arquivos.
A solicitação abaixo recupera uma lista de legendas ocultas para um vídeo no canal do YouTube das histórias do Google:
A solicitação atualiza o status do rascunho de uma faixa de legenda para true
, o que significa que a faixa não ficará visível ao público. 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 ver exemplos de código.
Excluir uma faixa de legenda
Este exemplo mostra como excluir uma faixa de legenda. O exemplo tem as seguintes etapas:
-
Etapa 1: recuperar o ID da faixa de legenda
Siga as etapas acima para recuperar uma lista de faixas de legenda de um vídeo. A lista pode ser usada para exibir uma lista de faixas de legenda, usando o ID de cada faixa como chave.
-
Etapa 2: excluir a faixa
Chame o método
captions.delete
para excluir um vídeo específico. Na solicitação, o parâmetroid
especifica o ID da faixa de legenda que você está excluindo. A solicitação precisa ser autorizada usando o OAuth 2.0. Se estiver testando essa consulta no APIs Explorer, você precisará substituir um ID de faixa de legenda válido pelo valor do parâmetroid
.https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.captions.delete? id=CAPTION_TRACK_ID