# YouTube transcript API que também funciona sem legendas

> YouTube transcript API: envie o link e receba JSON, TXT, SRT ou VTT. Usamos as legendas; se faltarem, a IA transcreve. 1 crédito por minuto.

Canonical: https://transcript1.com/pt/features/youtube-transcript-api
Language: pt-BR
Last updated: 2026-10-19

Com a YouTube transcript API do transcript1, você envia o link do vídeo e recebe JSON, texto, SRT ou VTT. Primeiro buscamos uma faixa de legendas que possa ser usada. Se não houver, a IA transcreve o áudio.

- Primeiro as legendas; se não houver, transcrição com IA
- 1 crédito por minuto em qualquer uma das opções
- Links watch, youtu.be, Shorts e embed

## Escolha de onde vem o texto

### Use o link que você já tem

Aceitamos links watch, youtu.be, Shorts, embed e live, com ou sem www. Todos identificam o vídeo, mas uma transmissão ainda ao vivo não pode ser transcrita.

### Legendas do próprio vídeo

Com source=auto, damos preferência às legendas enviadas pelo criador. Depois vêm as geradas automaticamente. Não usamos faixas traduzidas automaticamente.

### Transcrição mesmo sem legendas

Se não encontrarmos legendas que possam ser usadas, transcrevemos o áudio. Para usar IA desde o início, envie source=stt.

### Saiba qual fonte foi usada

O campo transcript_source informa youtube_captions ou speech_to_text. Sua aplicação consegue distinguir uma faixa do YouTube de uma nova transcrição do áudio.

### O preço não muda com a fonte

Cada minuto de vídeo custa 1 crédito, com arredondamento para cima. Se a transcrição falhar ou você cancelar, não há cobrança.

## 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](https://transcript1.com/pt/docs/api-reference#create-a-transcription) 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

```
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](https://transcript1.com/pt/docs/api-reference#the-transcription-object).

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.

### Exemplo resumido de resposta JSON

```
{
  "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](https://transcript1.com/pt/docs/sources-and-options#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.

### Request para transcrever o áudio com IA

```
{
  "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](https://transcript1.com/pt/docs/errors) 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](https://transcript1.com/pt/docs/api-reference#idempotency). 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](https://transcript1.com/pt/features/transcrever-tiktok), [Instagram](https://transcript1.com/pt/features/transcricao-do-instagram) e outras fontes compatíveis. Confira as combinações na [documentação de fontes](https://transcript1.com/pt/docs/sources-and-options) antes de oferecê-las no seu produto.

## Dúvidas frequentes

### Funciona se o vídeo não tiver legendas?

Sim. Com source=auto, a IA transcreve o áudio quando não há uma faixa de legendas que possa ser usada. Se você quiser aceitar somente legendas, escolha source=captions.

### Quais links do YouTube posso enviar?

Links watch, youtu.be, Shorts, embed e live. Páginas de canal e links que apontam só para uma playlist retornam 422 invalid_url. O link live identifica um vídeo, mas não permite transcrever uma transmissão ainda ao vivo.

### Posso transcrever um vídeo privado?

Não. Conseguimos buscar vídeos públicos ou não listados. Vídeos privados, com restrição de idade ou ainda ao vivo não funcionam. Se você tem o arquivo original, envie-o por upload.

### Quanto custa cada transcrição?

1 crédito por minuto de vídeo, arredondado para cima, tanto para legendas quanto para IA. Você recebe 60 minutos grátis uma única vez após confirmar o e-mail. Não precisa de cartão.

### É o pacote Python youtube-transcript-api?

Não. O transcript1 é uma API REST hospedada. Para usá-la em Python, faça um request HTTP com sua chave de API.

## Veja também

- [Tempos e legendas](https://transcript1.com/pt/features/criar-arquivo-srt)
- [API para arquivos](https://transcript1.com/pt/features/speech-to-text-api)
- [Webhooks](https://transcript1.com/pt/features/webhook-transcricao)
- [Reaproveitar conteúdo](https://transcript1.com/pt/use-cases/video-em-artigo-de-blog)