Guida rapida all’API di KolWrite
Automatizza tutto ciò che fai nell’app KolWrite: caricare un file, trascriverlo con tutte le opzioni, esportare la trascrizione e condividerla, con un token di accesso personale (PAT).
URL di base: https://api.kolwrite.com
1. Creare un token
Nell’app KolWrite: Impostazioni → Account → Accesso API → Crea token. Scegli gli ambiti che ti servono (questa guida usa files:write, jobs:write, jobs:read, transcripts:read). Il segreto (kol_...) viene mostrato una sola volta: conservalo in un posto sicuro.
Invialo con ogni richiesta:
export KOLWRITE_TOKEN="kol_..."
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
https://api.kolwrite.com/api/v1/billing/balance2. Caricare un file
Crea una sessione di caricamento, invia i byte con PUT all’URL prefirmato e poi completa il caricamento:
# 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_idI file grandi vengono caricati a parti: la sessione restituisce allora data.upload_url come null e un URL per ogni parte in data.multipart_part_urls. Invia ogni parte con PUT, conserva l’intestazione ETag di ogni risposta e passale alla chiamata di completamento come uploaded_parts: un elenco di oggetti {part_number, etag}.
3. Trascrivere
Crea un job. profile sceglie il livello del modello (oracle, oracle-mini, oracle-pro, oracle-max; elencali con GET /api/v1/models); options contiene tutto ciò che offre la finestra di analisi dell’app. Usa un Idempotency-Key perché i nuovi tentativi non inviino mai il job due volte:
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"L’incorporamento dei sottotitoli nel video funziona allo stesso modo, con "type": "caption_burn" e un blocco di stile options.caption_burn; vedi il riferimento.
4. Attendere il risultato
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. Esportare la trascrizione
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
"https://api.kolwrite.com/api/v1/jobs/JOB_ID/export?format=srt&include_speakers=true"Formati: text, json, srt, vtt. Gli artefatti di trascrizione duraturi (con cronologia delle versioni) si trovano in GET /api/v1/jobs/JOB_ID/artifacts e GET /api/v1/artifacts/{artifact_id}, con l’ambito transcripts:read.
Il download di SRT e VTT richiede il piano Plus o superiore; gli altri piani ricevono HTTP 403 con il codice subtitle_export_requires_plus.
6. Facoltativo: condividere
Con 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