Envie o link pela API de transcrição do YouTube
Faça um POST com o link do vídeo e sua chave de API, em Python ou no cliente HTTP que você usa. Com wait=60, o request espera até 60 segundos. A referência de criação mostra os campos e códigos de status.
Crie a chave no painel e use-a no servidor ou em um script. Assim que o request retornar, salve o ID da transcrição. Se ela ainda estiver em andamento, consulte GET /v1/transcriptions/:id. O fim da espera HTTP não interrompe o processamento.
Antes de completed, você pode receber queued, fetching ou transcribing. Só mostre a transcrição quando ela estiver pronta. Se o status for failed, trate o erro. Uma demora na rede ou um vídeo indisponível não deve virar uma transcrição vazia apresentada como concluída.
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-H "Content-Type: application/json" \
-d '{"platform":"youtube","url":"https://youtu.be/dQw4w9WgXcQ"}'Confira a origem do texto em transcript_source
A resposta informa se o texto veio das legendas e se a faixa foi enviada pelo criador ou gerada automaticamente. billed_minutes traz a duração arredondada para cima. Veja os demais campos no objeto de transcrição.
Guarde transcript_source e caption_kind quando precisar registrar a origem do texto. As legendas do criador mantêm o texto publicado, sem marcações por palavra. As automáticas do YouTube trazem o início de cada palavra. A transcrição com IA traz início, fim e confiança.
Os segmentos incluem início e fim em segundos. Use esses tempos para sincronizar a leitura com o vídeo ou levar o trecho certo a um assistente. Só peça include=words se precisar das marcações por palavra. O JSON abaixo ilustra a estrutura da resposta; não é uma citação do vídeo usado no request.
{
"id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
"status": "completed",
"transcript_source": "youtube_captions",
"caption_kind": "auto_generated",
"language": "en",
"billed_minutes": 4,
"transcript": {
"text": "Welcome back to the channel. Today we are looking at how transcripts are made.",
"segments": [
{ "start": 0, "end": 4.2, "speaker": null, "language": "en", "text": "Welcome back to the channel." }
]
}
}Extrair legendas do YouTube via API ou transcrever o áudio?
O padrão é source=auto. Use captions quando você precisar das legendas publicadas: se não houver uma faixa disponível, a API retorna no_captions sem cobrar. Use stt para sempre transcrever o áudio. Confira as combinações na documentação de source.
Para obter uma transcrição nova do áudio ou identificar falantes, escolha speech-to-text. Com source=auto e diarize=true, a API ignora as legendas e usa IA. Já source=captions com diarize=true gera um erro; a identificação de falantes não é descartada sem aviso.
O idioma também entra nessa escolha. A faixa precisa corresponder ao idioma pedido ou, com language=auto, ao idioma original do vídeo. Não usamos traduções automáticas das legendas. Ao transcrever áudio, language serve como dica para o reconhecimento, não como pedido de tradução.
{
"platform": "youtube",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"source": "stt"
}Confira o erro antes de enviar o vídeo de novo
Vídeos privados, com restrição de idade ou ainda ao vivo exigem outra fonte. Repetir o mesmo request não resolve. Se receber no_captions, decida se uma transcrição do áudio atende ao seu caso. Se o processamento continua, consulte o ID existente. A lista de erros ajuda a decidir o que fazer.
Para repetir um request de criação após uma falha de conexão, siga o contrato de Idempotency-Key. Reutilizar uma transcrição recente é outra opção: ela procura o mesmo vídeo com as mesmas configurações. Uma transcrição em cache ainda pode ser cobrada como nova. Consultar uma transcrição já concluída não consome minutos.
Sua aplicação também recebe links de outras plataformas? YouTube, X, TikTok e Bluesky permitem buscar legendas e recorrer ao áudio com auto. O mesmo endpoint aceita TikTok, Instagram e outras fontes compatíveis. Confira as combinações na documentação de fontes antes de oferecê-las no seu produto.