# 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:

```bash
export KOLWRITE_TOKEN="kol_..."
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  https://api.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:

```bash
# 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_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:

```bash
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

```bash
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 waiting
```

## 5. Esportare la trascrizione

```bash
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`:

```bash
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
```

## Prossimi passi

- [Autenticazione e ambiti](/locales/it/authentication.md)
- [Errori e limiti di frequenza](/locales/it/errors.md)
- [Riferimento completo dell’API](/) · [Specifica OpenAPI](/openapi.json)