SDK para Node.js

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

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”. Depois, configure a variável TRANSCRIPT1_API_KEY no servidor ou informe apiKey ao criar o cliente:

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.

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:

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

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.

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.

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

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:

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:

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

Interrompa uma chamada

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

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:

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);
  }
}

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; os campos das respostas, na referência da API.

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.