Guia rápido

Para usar a API, você precisa de uma chave no cabeçalho Authorization. O endereço é https://api.transcript1.com. Neste guia, você cria a chave, envia um link ou arquivo e busca o texto da transcrição.

1. Crie uma conta e uma chave de API

Faça seu cadastro com e-mail, Google ou Microsoft. Depois de confirmar o e-mail, você ganha 60 minutos grátis para testar. Com Google ou Microsoft, os minutos entram na hora. Essa oferta vale uma vez por conta e não exige cartão.

No painel, abra “API keys”, em /dashboard/account/tokens, e crie uma chave. Ela começa com t1_ e só aparece uma vez. Copie antes de sair da página e defina a variável TRANSCRIPT1_API_KEY:

export TRANSCRIPT1_API_KEY="t1_..."

2. Envie um link de vídeo

Você pode enviar links do YouTube, X, TikTok, Instagram, Facebook, Bluesky, Twitch, Dailymotion, Pinterest, LinkedIn e Snapchat. Consulte Links aceitos e opções para conferir os tipos de gravação pública e as restrições de cada plataforma. A API reconhece a plataforma pelo endereço, sem exigir platform. Vamos usar um vídeo do YouTube no exemplo.

Chame POST /v1/transcriptions com o link. Para aguardar até 60 segundos nessa chamada, acrescente wait=60 à query string. A resposta de criação não traz o texto da transcrição. Por isso, o exemplo em Python faz outra chamada a GET /v1/transcriptions/:id?wait=60 para buscá-lo. Já o SDK de Node.js usa a chave de TRANSCRIPT1_API_KEY e cuida da espera e da consulta.

cURL

curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

Python

import os
import requests
 
headers = {"Authorization": f"Bearer {os.environ['TRANSCRIPT1_API_KEY']}"}
response = requests.post(
    "https://api.transcript1.com/v1/transcriptions?wait=60",
    headers=headers,
    json={"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"},
)
response.raise_for_status()
transcription = response.json()
while True:
    transcription = requests.get(
        f"https://api.transcript1.com/v1/transcriptions/{transcription['id']}?wait=60",
        headers=headers,
    ).json()
    if transcription["status"] in ("completed", "failed", "canceled"):
        break
 
if transcription["status"] == "completed":
    print(transcription["transcript"]["text"])
else:
    print(transcription["status"], transcription["error"])

Node.js

Salve o exemplo em index.mjs e rode node index.mjs. Se preferir um arquivo .js, configure "type": "module" no package.json.

// npm i @transcript1/sdk
import { Transcript1 } from '@transcript1/sdk';
 
const t1 = new Transcript1();
const transcription = await t1.transcribe('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
console.log(transcription.transcript.text);

No modo padrão, buscamos primeiro as legendas no idioma original do YouTube, X, TikTok, Bluesky, Dailymotion e LinkedIn. Se não houver legendas que possam ser usadas, transcrevemos o áudio com IA. Isso mantém o funcionamento das legendas do YouTube e do X. Fora do YouTube, as legendas trazem marcações de tempo por segmento, não por palavra. Nem todo vídeo tem legendas disponíveis. Para ir direto ao áudio, use source=stt ou ative a identificação de falantes. Já o modo captions (somente legendas) não baixa áudio nem usa STT. Veja como escolher em Links aceitos e opções.

3. Busque a transcrição

O status HTTP indica se você precisa consultar de novo:

• 200: a transcrição terminou durante a espera. Confira se status é completed, failed ou canceled.
• 202: o processamento continua. Chame GET /v1/transcriptions/:id?wait=60 e repita até chegar a um status final. Cada consulta espera até 60 segundos.

Quando o status é completed, a resposta tem este formato. O exemplo está abreviado:

{
  "id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
  "object": "transcription",
  "status": "completed",
  "transcript_source": "youtube_captions",
  "language": "en",
  "billed_minutes": 4,
  "transcript": {
    "text": "Welcome back to the channel. Today we are looking at how transcripts are made.",
    "speakers": [],
    "segments": [
      { "start": 0, "end": 4.2, "speaker": null, "language": "en", "text": "Welcome back to the channel." },
      { "start": 4.2, "end": 9.8, "speaker": null, "language": "en", "text": "Today we are looking at how transcripts are made." }
    ]
  }
}

Leia o texto completo em transcript.text. Para trabalhar com trechos e marcações de tempo, use transcript.segments: cada segmento traz start e end em segundos.

Você também pode baixar texto simples com text ou legendas com srt e vtt:

curl "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD?format=srt" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY"

Essa chamada usa GET /v1/transcriptions/:id?format=srt. O arquivo no formato escolhido só vem quando o status é completed. Antes disso, a API responde com o objeto JSON para você acompanhar o processamento.

4. Transcreva um arquivo

Se o áudio ou vídeo está no seu computador e tem até 95 MB, envie o arquivo em uma chamada multipart/form-data:

curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F [email protected]

Para arquivos maiores, de até 2 GB, use o upload em partes. Se a conexão cair, você continua de onde parou. Veja o passo a passo em Uploads.

Próximos passos

• Links aceitos e opções: escolha entre legendas e IA, ative a identificação de falantes e configure o idioma.
• Uploads: envie o arquivo de uma vez ou em partes.
• Webhooks: receba um aviso assinado quando a transcrição terminar.
• Servidor MCP: conecte Claude, ChatGPT, Cursor, VS Code ou Claude Code ao transcript1.
• Referência da API: consulte os endpoints e seus parâmetros.