Transcrição para apps e produtos SaaS

Coloque recursos de notas de voz, transcrição de reuniões, legendas ou busca em áudio no seu produto usando uma API REST assíncrona. Você faz o upload, inicia a tarefa, recebe o aviso via webhook e salva os trechos transcritos.

Obter uma chave de API Início rápido Idiomas suportados

Última atualização: · Markdown

Como funciona em produção

  1. Seu backend chama POST /upload para o arquivo do usuário e repassa o formulário assinado para o cliente fazer o envio, ou então sobe o arquivo direto pelo servidor (até 100 MiB).
  2. Comece a tarefa passando o fileUrl recebido no campo audio_url, junto com o seu webhook_url.
  3. Confirme a assinatura do webhook, descarte entregas repetidas checando o X-KolWrite-Delivery-Id e, caso result_omitted venha como true, busque o resultado em GET /transcribe/{jobId}.
  4. Salve os segments (com texto, tempos e falantes) para mostrar na sua interface e exporte em srt ou txt quando o usuário pedir.

Requisição para iniciar a tarefa:

{
  "audio_url": "<fileUrl from POST /upload>",
  "model": "oracle",
  "language": "auto",
  "include_diarization": true,
  "output_format": "json",
  "webhook_url": "https://api.example.com/hooks/kolwrite",
  "webhook_secret": "<random secret>"
}

Validação dos webhooks

import crypto from "node:crypto";

// Express-style handler; rawBody is the exact request body as received.
export function verifyKolWrite(req, rawBody, secret) {
  const timestamp = req.headers["x-kolwrite-timestamp"];
  const expected = "sha256=" + crypto.createHmac("sha256", secret)
    .update(timestamp + "." + rawBody).digest("hex");
  const given = req.headers["x-kolwrite-signature"] || "";
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

Cada aviso é entregue pelo menos uma vez, com novas tentativas se houver falha. Use sempre o endpoint GET /transcribe/{jobId} como sua fonte oficial de consulta.

Escolha o modelo conforme a tarefa

O que o produto precisaConfiguraçãoPor quê
Grande volume de áudio limpo gastando poucomodel: "base"0,40 créditos (US$ 0,48) por hora
Padrão para arquivos enviados por usuáriosmodel: "oracle"Qualidade de produção, com opção de tradução
Transcrição em outro idiomaModelo Oracle + translate_toUma única tarefa já devolve o texto traduzido
Identificar quem falou cada trechoinclude_diarization: trueJá incluído no preço
Legendasoutput_format: "srt"Pronto para players de vídeo

Limites para considerar na arquitetura

  • Upload inline em Base64: até 4 MiB de mídia decodificada. Upload assinado: até 100 MiB.
  • O formulário de upload assinado expira em 60 minutos, e a URL de leitura, em 24 horas.
  • As tarefas são assíncronas. Acompanhe o progresso pelos status PENDING e IN_PROGRESS.
  • Não é possível usar channel_speaker_separation junto com a diarização.

Perguntas e respostas

Existe SDK?

A API usa HTTPS e JSON padrão, então qualquer cliente HTTP resolve. Se quiser gerar código, use a especificação OpenAPI 3.1 em /openapi.json.

Como evito processar o mesmo webhook duas vezes?

Use o cabeçalho X-KolWrite-Delivery-Id para filtrar duplicatas. Quando há nova tentativa de envio, o ID é mantido.

Como funciona a cobrança?

A cobrança é por segundo de áudio, seguindo a tabela de créditos do modelo, sem valor mínimo. 1 crédito sai por US$ 1,20.

Páginas relacionadas