Documentação da API da KolWrite

Autenticação

Todas as requisições à API devem ser autenticadas com a sua chave de API exclusiva. Inclua-a nos cabeçalhos da requisição:

x-api-key: YOUR_API_KEY

Você pode gerar e gerenciar suas chaves de API no Console da KolWrite após criar uma conta.

Início rápido

Comece rápido com estes exemplos básicos.

1. Iniciar a transcrição

Envie uma requisição POST para o endpoint `/transcribe` com a URL do arquivo de áudio que você quer transcrever.

Requisição:

POST https://app.kolwrite.com/transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270"
}

Resposta:

A API devolve um `jobId` para você consultar o resultado da transcrição depois.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

2. Obter o resultado da transcrição

De Send a GET request a the `/transcribe/{jobId}` endpoint using the `jobId` received from the previous step.

Requisição:

GET https://app.kolwrite.com/transcribe/34c63d45-4cb5-473b-bc60-25c175e69c57
x-api-key: YOUR_API_KEY

Resposta (exemplo):

Quando o status do trabalho for COMPLETED, a resposta inclui os detalhes da transcrição.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          },
          {
            "start": 1.5,
            "end": 1.9,
            "word": "welcome"
          }
        ]
      }
    ]
  }
}

Modelos e créditos de uso

O uso dos modelos é cobrado em créditos de uso por segundo, sem valor mínimo. O checkout, os recibos e os documentos fiscais mostram a moeda real usada no pagamento.

1 crédito é a unidade de cobrança da API que antes aparecia como $1.00 no console.

Contas de faturamento israelenses elegíveis compram créditos de uso em ILS ao preço líquido de ILS 3.60 por crédito antes do IVA. O checkout mostra os créditos de uso, o valor líquido, o IVA e o total final em ILS antes do pagamento. As demais contas compram créditos de uso em USD a USD 1.20 por crédito, salvo se condições de pedido separadas se aplicarem.

Complementos: A diarização regular de falantes e a separação de canais no modo standard a separação de canais estão incluídas. A diarização Pro de falantes adiciona 0.20 créditos por hora de áudio. overlap a separação de canais é cobrada pela tarifa do modelo selecionado sobre o maior valor entre a duração da gravação e o tempo total de fala detectado nos seus canais físicos; nenhum dos modos de canal acrescenta cobrança extra de diarização. O Oracle Mini ativa automaticamente o alinhamento de carimbos de tempo quando a diarização de falantes ou a separação de canais é selecionada.

Endpoints da API

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "clip.mp3",
  "contentType": "audio/mpeg",
  "content": "<base64-encoded media bytes>"
}

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "meeting.mp3",
  "contentType": "audio/mpeg"
}

// upload is the JSON response from POST /upload
const form = new FormData();
for (const [name, value] of Object.entries(upload.uploadFields)) {
  form.append(name, value);
}
form.append('file', file, file.name);
await fetch(upload.uploadUrl, { method: 'POST', body: form });

POST /transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "<fileUrl returned by POST /upload>",
  "model": "oracle"
}

POST /transcribe

Envia um arquivo de áudio para transcrição assíncrona, com opção de diarização de falantes.

Parâmetros do corpo da requisição

Exemplo de requisição (com diarização):

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270",
  "word_timestamps": true,
  "model": "edge",
  "output_format": "json",
  "include_diarization": true,
  "num_speakers": 2
}

Resposta:

Retorna um objeto com o `jobId` da tarefa de transcrição enviada.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

GET /transcribe/{jobId}

Consulta o status e o resultado de um job de transcrição específico.

Parâmetros de caminho

Corpo da resposta

Exemplo de resposta (saída JSON com diarização de falantes):

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          }
        ]
      },
      {
        "start": 4.1,
        "end": 6.8,
        "text": "Thank you. Let's begin with the quarterly review.",
        "speaker": "Speaker 2",
        "words": [
          {
            "start": 4.1,
            "end": 4.5,
            "word": "Thank"
          },
          {
            "start": 4.6,
            "end": 4.9,
            "word": "you"
          }
        ]
      }
    ]
  }
}

Diarização de falantes

A diarização identifica e separa quem está falando na gravação. Com essa opção ativada, a KolWrite analisa o áudio, detecta quando muda a voz e identifica o falante de cada trecho.

Todos os modelos da lista contam com diarização de falantes e separação de canais. No Oracle Mini, o alinhamento de timestamps é ativado automaticamente sempre que você escolhe um modo de falantes.

Como ativar a diarização

Para ativar a diarização de falantes, defina o parâmetro include_diarization em true na sua requisição de transcrição:

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "include_diarization": true,
  "num_speakers": 3
}

Otimização do número de falantes

Para obter os melhores resultados, informe o número esperado de falantes com o parâmetro num_speakers . Se você não souber o número exato, pode:

• Omita o parâmetro (o sistema detecta automaticamente)
• Informe um intervalo estimado configurando o valor com o seu melhor palpite

Diarização Pro

Para identificar falantes com mais precisão, principalmente em áudios com acústica ruim, ative a Diarização Pro. Esse recurso tem um custo adicional de 0.20 créditos por hora de áudio.

Para usá-la, defina o parâmetro pro_diarization em true. Este parâmetro pode ser usado em conjunto com include_diarization.

{
  "audio_url": "https://example.com/panel-discussion.mp3",
  "include_diarization": true,
  "pro_diarization": true
}

Separação de falantes por canal

A separação de canais transcreve cada faixa física de áudio de forma independente e identifica os segmentos e palavras retornados com seus respectivos campos físicos channel e speaker. Requer uma fonte de dois a oito canais audio_url e não pode ser combinada com a diarização regular ou Pro. O Oracle Mini ativa automaticamente o alinhamento de carimbos de tempo em ambos os modos de canal.

Usar standard quando os falantes se alternam; cobra-se uma única tarifa de áudio do modelo selecionado. Use overlap quando os falantes podem se sobrepor; cobra-se a tarifa do modelo selecionado sobre o maior valor entre a duração da gravação e o tempo total de fala detectado nos seus canais físicos.

{
  "audio_url": "https://example.com/stereo-call.wav",
  "model": "oracle",
  "channel_speaker_separation": "overlap",
  "channel_labels": {"0": "Agent", "1": "Customer"}
}

Webhooks de conclusão

Defina webhook_url para receber transcription.completed e transcription.failed eventos. Falhas de entrega são repetidas, mas os clientes devem continuar a oferecer suporte a GET /transcribe/{jobId} como fonte de verdade.

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "output_format": "json",
  "webhook_url": "https://example.com/kolwrite-webhook",
  "webhook_secret": "replace-with-your-secret"
}

Cada entrega inclui X-KolWrite-Event, X-KolWrite-Job-Id, X-KolWrite-Delivery-Id e X-KolWrite-Timestamp. A entrega ocorre pelo menos uma vez. Novas tentativas reutilizam o mesmo ID de entrega, então filtre eventos duplicados usando X-KolWrite-Delivery-Id. Se houver um segredo configurado, calcule o HMAC-SHA256 sobre timestamp + "." + raw_request_body e compare-o com X-KolWrite-Signature.

{
  "event": "transcription.completed",
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "createdAt": "2026-07-10T09:30:00+00:00",
  "model": "base",
  "output_format": "json",
  "result_available": true,
  "result_omitted": false,
  "result_size_bytes": 12480,
  "result": { "language": "en", "segments": [] }
}

Para output_format: "json", o webhook result é um objeto JSON. Os resultados TXT e SRT são entregues como strings.

Em resultados grandes, pode-se definir result_omitted para true; obtenha o resultado completo em GET /transcribe/{jobId}. Eventos com falha incluem um campo error campo.

Formato de saída com diarização

Quando a diarização está ativada, cada segmento da saída JSON inclui o campo speaker que identifica o falante (por exemplo, “Speaker 1”, “Speaker 2” etc.).

Formatos de saída

Formato JSON

Saída detalhada com segmentos, timestamps e dados opcionais por palavra.

Formato TXT

Transcrição em texto puro com identificação de falantes (quando a diarização está ativada).

Formato SRT

Formato de legenda SubRip com marcações de tempo, compatível com players de vídeo e editores de legenda.

Com os carimbos de tempo por palavra ativados (o padrão), o SRT gera um bloco por palavra, mostrando o texto inteiro do trecho com a palavra do momento destacada. Para gerar um bloco por trecho, passe word_timestamps como false. Não retornamos WebVTT; se precisar desse formato, converta o SRT com o ffmpeg.

Status do serviço

Veja a página de status da API da KolWrite para ver a disponibilidade em tempo real, o histórico de atividade e os incidentes de nível de serviço.

GET /health não exige chave de API e retorna o estado atual da API, do recebimento de trabalhos e do processamento de transcrições. Uma resposta 200 significa que o serviço está operacional ou degradado; uma resposta 503 significa que o estado atual é desconhecido ou indisponível. Ambas as respostas incluem detalhes de estado em JSON.

GET /health/history?period=24h retorna um histórico compacto de disponibilidade. Os períodos aceitos são 24h, 7d e 30d.

Códigos de status