# SDK para Node.js

> Integre transcrições ao seu servidor com @transcript1/sdk. Envie links ou arquivos, baixe texto e legendas, acompanhe o progresso e trate erros.

Canonical: https://transcript1.com/pt/docs/sdk
Language: pt-BR
Last updated: 2026-10-16

Com `@transcript1/sdk`, você envia links ou arquivos e aguarda a transcrição no seu código TypeScript ou JavaScript. Use o pacote no servidor.

Para links de redes sociais, use o SDK 1.1.0 ou mais recente. O SDK 1.0.1 só aceita YouTube e recusa os outros links antes de chamar a API. Atualize com `npm i @transcript1/sdk@latest`.

A versão acima cobre as seis plataformas originais. Twitch, Dailymotion, Pinterest, LinkedIn e Snapchat precisam de uma versão que já inclua essas plataformas. Versões antigas podem recusar os links antes do envio.

## Instale o pacote

```bash
npm i @transcript1/sdk
```

Os exemplos abaixo usam módulos ES. Salve o código em `.mjs` ou configure `"type": "module"` no `package.json` se usar `.js`. No Node 20.19+, você também pode importar com `require()`, como em `require('@transcript1/sdk')`.

## Configure sua chave de API

Crie uma chave em [“API keys”](https://transcript1.com/dashboard/account/tokens). Depois, configure a variável `TRANSCRIPT1_API_KEY` no servidor ou informe `apiKey` ao criar o cliente:

```javascript
import { Transcript1 } from '@transcript1/sdk';

const t1 = new Transcript1(); // reads TRANSCRIPT1_API_KEY
const other = new Transcript1({ apiKey: 't1_...' });
```

Se não encontrar uma chave, o construtor lança `Transcript1Error` com `missing_api_key`.

## Envie e aguarde a transcrição

Chame `transcribe(input, options)` para criar a transcrição e esperar o texto ficar pronto. A promise retorna um objeto `CompletedTranscription`, com `status: 'completed'` e o campo `transcript`. Se a transcrição falhar ou você cancelar, a promise é rejeitada.

```javascript
const done = await t1.transcribe('https://youtu.be/dQw4w9WgXcQ');
console.log(done.transcript.text);

const file = await t1.transcribe('./interview.m4a', { speakers: true });
```

Se enviar um Buffer ou Uint8Array, passe também o nome do arquivo. É por ele que o SDK reconhece o formato:

```javascript
import { readFile } from 'node:fs/promises';

const buffer = await readFile('./call.mp3');
const call = await t1.transcribe(buffer, { filename: 'call.mp3' });
```

O SDK trata strings iniciadas por `http://` ou `https://` como links. As demais são caminhos de arquivo. Você pode usar links do YouTube, X, TikTok, Instagram, Facebook, Bluesky, Twitch, Dailymotion, Pinterest, LinkedIn e Snapchat, ou fazer upload. Confira os tipos de gravação pública, as legendas disponíveis e as restrições em [Links aceitos e opções](https://transcript1.com/pt/docs/sources-and-options). As plataformas adicionais exigem HTTPS. Para arquivos, o limite é de 2.000.000.000 bytes, com extensão mp3, wav, m4a, flac, ogg, opus, mp4, mov, webm ou mkv.

O post precisa ser público. Se tiver vários vídeos, transcrevemos só o primeiro. A API reconhece a plataforma pelo link. Os formatos de link curto e os limites estão em [Links aceitos e opções](https://transcript1.com/pt/docs/sources-and-options).

Também aceitamos Blob, `ReadableStream<Uint8Array>` e iteráveis assíncronos de blocos Uint8Array. Para Blob, informe `filename`, exceto quando usar um File com nome. Para streams e iteráveis assíncronos, informe tanto `filename` quanto `size`, em bytes.

## Baixe texto ou legendas

Use `download(id, options)` para aguardar a conclusão e baixar a transcrição como string. Isso também vale para JSON: você recebe o texto JSON da API, sem parse para objeto.

```javascript
const text = await t1.download(done.id); // text is the default
const withTimes = await t1.download(done.id, { timestamps: true });
const srt = await t1.download(done.id, { format: 'srt' });
const vtt = await t1.download(done.id, { format: 'vtt' });
const json = await t1.download(done.id, { format: 'json' });
```

Combine `timestamps: true` apenas com `text`. Em outros formatos, a promise é rejeitada com `invalid_input`. Se a transcrição falhar ou você cancelar, a promise de `download` também é rejeitada.

## Inicie agora e consulte depois

Se não quiser esperar o texto, use `transcriptions.create`. No caso de arquivos, a chamada só retorna depois de terminar o upload, mas não espera a transcrição.

```javascript
const job = await t1.transcriptions.create('./long-interview.mp4');
const now = await t1.transcriptions.get(job.id);
const finished = await t1.transcriptions.get(job.id, { wait: true });
```

Sem `wait`, `get` informa o estado naquele momento. Com `wait: true`, a promise aguarda até o status ser `completed`, `failed` ou `canceled`. Confira `finished.status` antes de acessar o texto. Diferentemente de `transcribe`, a promise de `get` não é rejeitada se o processamento falhar ou você cancelar a transcrição.

## Liste transcrições, exclua e consulte a conta

```javascript
for await (const item of t1.transcriptions.list({ status: 'completed', limit: 50 })) {
  console.log(item.id, item.created_at);
}

await t1.transcriptions.delete(job.id);
const account = await t1.account();
console.log(account.minutes.remaining);
```

Ao iterar com `list`, o SDK busca as páginas conforme necessário. Você pode filtrar por `status` e `platform` (`youtube`, `x`, `tiktok`, `instagram`, `facebook`, `bluesky`, `twitch`, `dailymotion`, `pinterest`, `linkedin`, `snapchat` ou `upload`). Escolha de 1 a 100 itens por página com `limit`; o padrão da API é 20. Os campos continuam em `snake_case`, como na API. Guarde `media_id` como veio, sem tentar interpretar a string.

Use `delete` para cancelar uma transcrição em andamento ou excluir uma já finalizada, junto com o texto. Para consultar plano, saldo de minutos e limites, use `account`.

## Opções

Ao criar o cliente, você pode passar `apiKey`, `baseUrl`, `fetch` e `maxRetries`. Se não informar `baseUrl`, usamos `TRANSCRIPT1_API_URL`, quando definida; caso contrário, `https://api.transcript1.com`. Para usar sua própria implementação de fetch, passe `fetch`. O padrão de `maxRetries` é 2, com valores inteiros de 0 a 10.

Estas opções valem tanto para `transcribe` quanto para `transcriptions.create`:

| Opção | Para que serve |
|---|---|
| `speakers` | Ativa a identificação de falantes. |
| `language` | Escolhe `auto` (padrão) ou um idioma pelo código ISO 639-1. |
| `source` | Para links, aceita `auto` ou `stt`. YouTube, X, TikTok, Bluesky, Dailymotion e LinkedIn também aceitam `captions` (somente legendas) quando há uma faixa que possa ser usada. |
| `fresh` | Pede uma nova transcrição do link, sem reutilizar uma das últimas 24 horas. |
| `filename` | Informa o nome para Buffers, Blobs sem nome e streams, que exigem esse campo. Também pode substituir o nome original de um arquivo. |
| `size` | Informa o tamanho em bytes. É obrigatório para streams e iteráveis assíncronos. |
| `idempotencyKey` | Define a chave de idempotência. Se você não passar uma, o SDK gera um UUID novo por chamada. |
| `onProgress` | Define a função que recebe os eventos de progresso. |
| `signal` | Recebe um AbortSignal para interromper a chamada. |

Em `transcriptions.get`, as opções são `wait`, `includeWords`, `onProgress` e `signal`. Para pedir marcações de tempo por palavra, use `includeWords: true`. Durante a espera, `onProgress` avisa sobre mudanças no processamento.

Em `download`, você pode passar `format`, `timestamps` e `signal`. `list` também aceita `signal`. Para `transcriptions.delete(id, options)` e `account(options)`, informe `{ signal }` no argumento de opções.

## Acompanhe o progresso

Configure `onProgress` em `transcribe`, `transcriptions.create` ou `transcriptions.get` quando estiver aguardando a transcrição:

```javascript
await t1.transcribe('./interview.m4a', {
  onProgress(event) {
    console.log(event);
  },
});
```

| Evento | O que você recebe |
|---|---|
| `upload` | Bytes enviados em `sent` e tamanho completo em `total`. |
| `status` | Estado atual da transcrição em `status`. |
| `waiting_slot` | Tempo de espera em segundos, em `retryAfter`, até tentar iniciar a transcrição de novo. |
| `reconnecting` | Aviso de queda de conexão durante a espera. Não tem campos extras e aparece uma vez por interrupção. |

## Interrompa uma chamada

Para interromper a chamada, passe o `AbortSignal` de um AbortController. Se quiser impor um prazo, use `AbortSignal.timeout`:

```javascript
await t1.transcribe('https://youtu.be/dQw4w9WgXcQ', {
  signal: AbortSignal.timeout(10 * 60_000),
});
```

Se a interrupção acontecer antes da primeira requisição, a promise é rejeitada com `aborted`, sem ID de transcrição. Durante o upload, o SDK tenta excluir a transcrição se ela ainda estiver em `awaiting_upload`. Depois, a promise é rejeitada com `aborted` e o ID.

Interromper a espera não para a transcrição. Ela continua rodando, e você pode usar o `transcriptionId` do erro para voltar a acompanhar com `transcriptions.get(id, { wait: true })`. Para cancelar a transcrição de fato, chame `transcriptions.delete(id)`.

Durante a espera, o SDK repete chamadas que falham por erro de rede ou HTTP 429, 500, 502, 503 e 504, sem limite de tentativas. O intervalo de reconexão aumenta de 2 para 4, 8, 16 e, por fim, 30 segundos. Para as outras chamadas, vale `maxRetries`. Se você já estiver no limite de transcrições ativas, o SDK espera e tenta criar a transcrição de novo. Use `signal` para limitar o tempo total dessas operações.

## Trate os erros

Capture `Transcript1Error` para tratar erros da API, falhas na transcrição e erros locais do SDK:

```javascript
import { Transcript1Error } from '@transcript1/sdk';

try {
  await t1.transcribe('./call.mp3');
} catch (error) {
  if (error instanceof Transcript1Error) {
    console.error(error.code, error.message, error.transcriptionId);
  }
}
```

| Campo | Como ler |
|---|---|
| `message` | Explicação do erro. |
| `code` | Código da API, da falha na transcrição, `canceled` ou um código local do SDK. |
| `status` | Status HTTP. Não aparece em falhas de processamento ou erros locais. |
| `details` | Campos adicionais da API, como `minutes_needed` e `action_url`. Sem detalhes extras, é um objeto vazio. |
| `retryable` | Indica se vale tentar novamente. O padrão é `false`. |
| `transcriptionId` | ID da transcrição, se já houver um. |
| `transcription` | Objeto mais recente da transcrição, quando disponível. |

O SDK usa os códigos locais `missing_api_key`, `invalid_input`, `aborted`, `network_error` e `upload_token_refused`. Se a resposta de erro não for JSON, o código terá o formato `http_<status>`.

Se o processamento falhar sem informar um objeto de erro, o SDK usa `transcription_failed`. Se a transcrição estiver concluída, mas a consulta não trouxer o texto, a promise de `transcribe` é rejeitada com `internal_error`. Os códigos da API estão em [Erros e novas tentativas](https://transcript1.com/pt/docs/errors); os campos das respostas, na [referência da API](https://transcript1.com/pt/docs/api-reference).

## Onde o SDK pode rodar

Use Node 20.19+ no servidor. Bun e Deno devem funcionar pela compatibilidade com `node:`, mas nossos testes automatizados rodam só no Node. Nunca use o SDK no navegador nem exponha sua chave de API no código do cliente.