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

Última atualização: 2026-10-18 · HTML: https://console.kolwrite.com/pt/use-cases/developers

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

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

```javascript
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 precisa | Configuração | Por quê |
| --- | --- | --- |
| Grande volume de áudio limpo gastando pouco | `model: "base"` | 0,40 créditos (US$ 0,48) por hora |
| Padrão para arquivos enviados por usuários | `model: "oracle"` | Qualidade de produção, com opção de tradução |
| Transcrição em outro idioma | Modelo Oracle + `translate_to` | Uma única tarefa já devolve o texto traduzido |
| Identificar quem falou cada trecho | `include_diarization: true` | Já incluído no preço |
| Legendas | `output_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

- [Agentes de IA e vibe coding](https://console.kolwrite.com/pt/use-cases/ai-agents)
- [Centrais de atendimento e chamadas de vendas](https://console.kolwrite.com/pt/use-cases/call-centers)
- [Empresas](https://console.kolwrite.com/pt/use-cases/enterprise)
- [Idiomas suportados](https://console.kolwrite.com/pt/languages/)

---
Obter uma chave de API: https://console.kolwrite.com/auth?lang=pt · Documentação da API: https://console.kolwrite.com/pt/public_api_docs · llms.txt: https://console.kolwrite.com/llms.txt