KolWrite KolWrite Desenvolvedores

Início rápido da API do KolWrite

Automatize tudo o que você faz no app KolWrite: enviar um arquivo, transcrevê-lo com todas as opções, exportar a transcrição e compartilhá-la, usando um token de acesso pessoal (PAT).

URL base: https://api-prod.kolwrite.com

1. Criar um token

O acesso à API é autoatendimento: depois que sua conta comprar créditos, ative-o em Configurações → Conta → Acesso à API. As chamadas gastam seus créditos.

No app KolWrite: Configurações → Conta → Acesso à API → Criar token. Escolha os escopos de que precisa (este passo a passo usa files:write, jobs:write, jobs:read, transcripts:read). O segredo (kol_...) é mostrado uma única vez; guarde-o em um lugar seguro.

Envie-o em cada requisição:

export KOLWRITE_TOKEN="kol_..."
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  https://api-prod.kolwrite.com/api/v1/billing/balance

2. Enviar um arquivo

Crie uma sessão de upload, envie os bytes com PUT para a URL pré-assinada e conclua o envio:

# a. create the session
SIZE=$(wc -c interview.wav | awk '{print $1}')
curl -X POST https://api-prod.kolwrite.com/api/v1/media/upload-session \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"filename\": \"interview.wav\", \"file_size_bytes\": $SIZE, \"content_type\": \"audio/wav\"}"
# → data.upload_url, data.finalize_token

# b. upload the bytes directly to storage
curl -X PUT "$UPLOAD_URL" --data-binary @interview.wav \
  -H "Content-Type: audio/wav"

# c. finalize
curl -X POST https://api-prod.kolwrite.com/api/v1/media/complete \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"finalize_token": "FINALIZE_TOKEN"}'
# → 201, data.media_id

Arquivos grandes são enviados em partes: a sessão devolve então data.upload_url como null e uma URL para cada parte em data.multipart_part_urls. Envie cada parte com PUT, guarde o cabeçalho ETag de cada resposta e passe-os na chamada de conclusão como uploaded_parts: uma lista de objetos {part_number, etag}.

3. Transcrever

Crie uma tarefa. profile escolhe o nível do modelo (oracle, oracle-mini, oracle-pro, oracle-max; liste-os com GET /api/v1/models); options reúne tudo o que a janela de análise do app oferece. Use um Idempotency-Key para que novas tentativas nunca enviem a tarefa em duplicidade:

curl -X POST https://api-prod.kolwrite.com/api/v1/jobs \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: interview-2026-07-08" \
  -d '{
    "type": "transcription",
    "input": {"type": "media_ref", "media_id": "MEDIA_ID"},
    "profile": "oracle",
    "options": {
      "language": "auto",
      "target_language": null,
      "diarization": {"mode": "regular", "num_speakers": null, "auto_speaker_names": true}
    }
  }'
# → 202 Accepted, data.job_id, data.status = "queued"

A gravação de legendas no vídeo funciona do mesmo jeito, com "type": "caption_burn" e um bloco de estilo options.caption_burn; veja a referência.

4. Aguardar o resultado

curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  https://api-prod.kolwrite.com/api/v1/jobs/JOB_ID
# data.status: queued → running → succeeded | failed | cancelled
# data.progress: 0–100, plus queue position while waiting

5. Exportar a transcrição

curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  "https://api-prod.kolwrite.com/api/v1/jobs/JOB_ID/export?format=srt&include_speakers=true"

Formatos: text, json, srt, vtt, docx, pdf. A exportação é a transcrição como está agora: as correções feitas no editor do KolWrite entram assim que são salvas, sem nenhum passo extra.

Para ler a transcrição atual de um arquivo pelo ID do arquivo no espaço de trabalho (o mesmo texto que aparece no app), use GET /api/v1/workspace-files/WORKSPACE_FILE_ID/transcript?format=json com o escopo transcripts:read. Os cabeçalhos X-Transcript-Version-Id e X-Transcript-Revision mudam sempre que a transcrição muda, para que um processo que consulta periodicamente saiba quando há algo novo. As versões salvas ficam em GET /api/v1/jobs/JOB_ID/artifacts e GET /api/v1/artifacts/{artifact_id}; uma versão salva é um instantâneo fixo e não inclui edições posteriores.

Para pegar só transcrições que uma pessoa aprovou, peça aos revisores que toquem em "Marcar como revisado" no editor. A partir daí a chamada de transcrição envia X-Transcript-Review-Status: reviewed até a próxima edição, e require_reviewed=true faz ela responder 409 transcript_not_reviewed caso contrário. GET /api/v1/transcript-reviews?since=... lista os arquivos revisados desde sua última consulta. Ou dispense as consultas: adicione um webhook com POST /api/v1/webhook-endpoints (escopo webhooks:manage) para transcript.reviewed, job.completed, job.failed, upload.completed ou upload.failed, e confira em cada requisição o cabeçalho KolWrite-Signature (HMAC-SHA256 de <t>.<raw body> com o segredo do endpoint).

Baixar SRT e VTT é grátis em todos os planos.

6. Opcional: compartilhar

Com shares:write:

curl -X POST https://api-prod.kolwrite.com/api/v1/shares \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"share_kind": "transcript", "artifact_id": "ARTIFACT_ID", "access_scope": "everyone"}'
# → data.share_url

Próximos passos

Versão em Markdown desta página