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.kolwrite.com
1. Criar um token
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.kolwrite.com/api/v1/billing/balance2. 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.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.kolwrite.com/api/v1/media/complete \
-H "Authorization: Bearer $KOLWRITE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"finalize_token": "FINALIZE_TOKEN"}'
# → 201, data.media_idArquivos 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.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.kolwrite.com/api/v1/jobs/JOB_ID
# data.status: queued → running → succeeded | failed | cancelled
# data.progress: 0–100, plus queue position while waiting5. Exportar a transcrição
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
"https://api.kolwrite.com/api/v1/jobs/JOB_ID/export?format=srt&include_speakers=true"Formatos: text, json, srt, vtt. Artefatos de transcrição duráveis (com histórico de versões) estão em GET /api/v1/jobs/JOB_ID/artifacts e GET /api/v1/artifacts/{artifact_id}, com o escopo transcripts:read.
Baixar SRT e VTT exige o plano Plus ou superior; os outros planos recebem HTTP 403 com o código subtitle_export_requires_plus.
6. Opcional: compartilhar
Com shares:write:
curl -X POST https://api.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