# Guia rápido

> Comece com uma chave de API e transcreva um vídeo por link ou envie um arquivo. Exemplos em cURL, Python e Node.js.

Canonical: https://transcript1.com/pt/docs/getting-started
Language: pt-BR
Last updated: 2026-10-14

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](https://transcript1.com/signup) 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”](https://transcript1.com/dashboard/account/tokens), 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`:

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

```bash
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

```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`.

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

## 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:

```json
{
  "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`:

```bash
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`:

```bash
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F file=@interview.m4a
```

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](https://transcript1.com/pt/docs/uploads).

## Próximos passos

- [Links aceitos e opções](https://transcript1.com/pt/docs/sources-and-options): escolha entre legendas e IA, ative a identificação de falantes e configure o idioma.
- [Uploads](https://transcript1.com/pt/docs/uploads): envie o arquivo de uma vez ou em partes.
- [Webhooks](https://transcript1.com/pt/docs/webhooks): receba um aviso assinado quando a transcrição terminar.
- [Servidor MCP](https://transcript1.com/pt/docs/mcp): conecte Claude, ChatGPT, Cursor, VS Code ou Claude Code ao transcript1.
- [Referência da API](https://transcript1.com/pt/docs/api-reference): consulte os endpoints e seus parâmetros.