# Trascrizione per app e prodotti SaaS

> Integra nel tuo prodotto note vocali, trascrizioni di riunioni, sottotitoli o ricerca nell’audio tramite un’API REST asincrona: carichi il file, avvii l’elaborazione, ricevi il webhook e salvi i segmenti di testo.

Ultimo aggiornamento: 2026-10-18 · HTML: https://console.kolwrite.com/it/use-cases/developers

## Come funziona in produzione

1. Il tuo backend chiama `POST /upload` per il file dell’utente e passa il form firmato al client per l’invio, oppure carica direttamente il file fino a 100 MiB.
2. Avvia la trascrizione passando il `fileUrl` appena ottenuto nel campo `audio_url`, insieme al tuo `webhook_url`.
3. Controlla la firma del webhook, scarta gli eventuali duplicati usando `X-KolWrite-Delivery-Id` e, se `result_omitted` è true, richiama `GET /transcribe/{jobId}` per recuperare i dati.
4. Salva i `segments` (con testo, tempi e interlocutori) per poi mostrarli, ed esporta i file `srt` o `txt` quando vengono richiesti.

Esempio di richiesta:

```json
{
  "audio_url": "<fileUrl from POST /upload>",
  "model": "oracle",
  "language": "auto",
  "include_diarization": true,
  "output_format": "json",
  "webhook_url": "https://api.example.com/hooks/kolwrite",
  "webhook_secret": "<random secret>"
}
```

## Verifica dei webhook

```javascript
import crypto from "node:crypto";

// Express-style handler; rawBody is the exact request body as received.
export function verifyKolWrite(req, rawBody, secret) {
  const timestamp = req.headers["x-kolwrite-timestamp"];
  const expected = "sha256=" + crypto.createHmac("sha256", secret)
    .update(timestamp + "." + rawBody).digest("hex");
  const given = req.headers["x-kolwrite-signature"] || "";
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
```

L’invio del webhook è garantito almeno una volta, con nuovi tentativi automatici in caso di errore. Usa sempre `GET /transcribe/{jobId}` come riferimento principale per lo stato del lavoro.

## Scegliere il modello in base al lavoro

| Caso d’uso | Impostazione | Perché |
| --- | --- | --- |
| Grandi volumi di audio pulito a basso costo | `model: "base"` | 0,40 crediti (0,48 US$) all’ora |
| Scelta standard per i file caricati dagli utenti | `model: "oracle"` | Qualità da produzione, con traduzione disponibile |
| Trascrizione tradotta in un’altra lingua | Modello Oracle + `translate_to` | Un’unica chiamata, testo già tradotto |
| Riconoscimento di chi parla | `include_diarization: true` | Incluso nel prezzo |
| Sottotitoli | `output_format: "srt"` | Pronti per i player video |

## Limiti da tenere presenti in fase di progettazione

- Caricamento Base64 inline: 4 MiB di file decodificato. Caricamento firmato: 100 MiB.
- Il modulo di caricamento firmato scade dopo 60 minuti, l'URL di lettura dopo 24 ore.
- I job sono asincroni. Mostra l'avanzamento a partire dagli stati `PENDING` e `IN_PROGRESS`.
- Non è possibile usare `channel_speaker_separation` insieme alla diarizzazione.

## Domande e risposte

### C'è un SDK?

L’API funziona con normali chiamate HTTPS e JSON, quindi puoi usare qualsiasi client HTTP. Se usi un generatore di codice, trovi il file OpenAPI 3.1 su /openapi.json.

### Come evito di elaborare due volte lo stesso webhook?

Filtra i duplicati controllando l'header `X-KolWrite-Delivery-Id`. I tentativi di reinvio mantengono lo stesso ID.

### Come funziona la fatturazione?

Paghi al secondo di audio in base alla tariffa in crediti del modello, senza importo minimo. 1 credito costa 1,20 US$.

## Pagine correlate

- [Agenti IA e vibe coding](https://console.kolwrite.com/it/use-cases/ai-agents)
- [Call center e chiamate di vendita](https://console.kolwrite.com/it/use-cases/call-centers)
- [Aziende](https://console.kolwrite.com/it/use-cases/enterprise)
- [Lingue supportate](https://console.kolwrite.com/it/languages/)

---
Ottieni una chiave API: https://console.kolwrite.com/auth?lang=it · Documentazione dell’API: https://console.kolwrite.com/it/public_api_docs · llms.txt: https://console.kolwrite.com/llms.txt