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-prod.kolwrite.com
1. Creare un token
L’accesso API è self-service: quando il tuo account ha acquistato crediti, attivalo in Impostazioni → Account → Accesso API. Le chiamate usano i tuoi crediti.
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-prod.kolwrite.com/api/v1/billing/balance
2. 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-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
I 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-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"
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-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. Esportare la trascrizione
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
"https://api-prod.kolwrite.com/api/v1/jobs/JOB_ID/export?format=srt&include_speakers=true"
Formati: text, json, srt, vtt, docx, pdf. L'esportazione è la trascrizione così com'è ora: le correzioni fatte nell'editor di KolWrite sono incluse appena salvate, senza passaggi aggiuntivi.
Per leggere la trascrizione attuale di un file tramite l'ID del file nello spazio di lavoro (lo stesso testo che si vede nell'app), usa GET /api/v1/workspace-files/WORKSPACE_FILE_ID/transcript?format=json con l'ambito transcripts:read. Le intestazioni X-Transcript-Version-Id e X-Transcript-Revision cambiano ogni volta che cambia la trascrizione, così un processo che interroga periodicamente sa quando c'è qualcosa di nuovo. Le versioni salvate sono in GET /api/v1/jobs/JOB_ID/artifacts e GET /api/v1/artifacts/{artifact_id}; una versione salvata è un'istantanea fissa e non include modifiche successive.
Per prendere solo le trascrizioni approvate da una persona, chiedi ai revisori di toccare "Segna come revisionata" nell'editor. Da quel momento la chiamata della trascrizione invia X-Transcript-Review-Status: reviewed fino alla modifica successiva, e require_reviewed=true la fa rispondere 409 transcript_not_reviewed negli altri casi. GET /api/v1/transcript-reviews?since=... elenca i file revisionati dalla tua ultima interrogazione. Oppure niente interrogazioni: aggiungi un webhook con POST /api/v1/webhook-endpoints (ambito webhooks:manage) per transcript.reviewed, job.completed, job.failed, upload.completed o upload.failed, e verifica in ogni richiesta l'intestazione KolWrite-Signature (HMAC-SHA256 di <t>.<raw body> con il segreto dell'endpoint).
Il download di SRT e VTT è gratuito in tutti i piani.
6. Facoltativo: condividere
Con 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