Documentazione dell’API di KolWrite

Autenticazione

Tutte le richieste API devono essere autenticate con la tua chiave API univoca. Includila nelle intestazioni della richiesta:

x-api-key: YOUR_API_KEY

Puoi generare e gestire le tue chiavi API nella Console di KolWrite dopo aver creato un account.

Guida rapida

Inizia subito con questi esempi di base.

1. Avvia la trascrizione

Invia una richiesta POST all'endpoint `/transcribe` con l'URL del file audio da trascrivere.

Richiesta:

POST https://app.kolwrite.com/transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270"
}

Risposta:

L’API restituisce un `jobId` che ti servirà per recuperare i risultati della trascrizione.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

2. Ottieni il risultato della trascrizione

Da Send a GET request a the `/transcribe/{jobId}` endpoint using the `jobId` received from the previous step.

Richiesta:

GET https://app.kolwrite.com/transcribe/34c63d45-4cb5-473b-bc60-25c175e69c57
x-api-key: YOUR_API_KEY

Risposta (esempio):

Quando lo stato del lavoro è COMPLETED, la risposta conterrà i dettagli della trascrizione.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          },
          {
            "start": 1.5,
            "end": 1.9,
            "word": "welcome"
          }
        ]
      }
    ]
  }
}

Modelli e crediti di utilizzo

Il consumo dei modelli viene calcolato in crediti di utilizzo al secondo, senza addebito minimo. Il checkout, le ricevute e i documenti fiscali indicano la valuta reale usata per l'acquisto.

1 credito è l'unità di fatturazione dell'API, che prima veniva mostrata come $1.00 nella console API.

Gli account di fatturazione israeliani idonei acquistano crediti di utilizzo in ILS a un prezzo netto di ILS 3.60 per credito prima dell’IVA. Il checkout mostra i crediti di utilizzo, l’importo netto, l’IVA e il totale finale in ILS prima del pagamento. Gli altri account acquistano crediti di utilizzo in USD a USD 1.20 per credito, salvo condizioni d’ordine separate.

Componenti aggiuntivi: La diarizzazione normale dei parlanti e la separazione dei canali in modalità standard la separazione dei canali sono inclusi. La diarizzazione Pro dei parlanti aggiunge 0.20 crediti per ora di audio. overlap la separazione dei canali viene fatturata alla tariffa del modello selezionato sul valore maggiore tra la durata della registrazione e il tempo totale di parlato rilevato sui suoi canali fisici; nessuna delle due modalità di canale aggiunge un supplemento di diarizzazione. Oracle Mini attiva automaticamente l’allineamento dei timestamp quando è selezionata la diarizzazione dei parlanti o la separazione dei canali.

Endpoint API

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "clip.mp3",
  "contentType": "audio/mpeg",
  "content": "<base64-encoded media bytes>"
}

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "meeting.mp3",
  "contentType": "audio/mpeg"
}

// upload is the JSON response from POST /upload
const form = new FormData();
for (const [name, value] of Object.entries(upload.uploadFields)) {
  form.append(name, value);
}
form.append('file', file, file.name);
await fetch(upload.uploadUrl, { method: 'POST', body: form });

POST /transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "<fileUrl returned by POST /upload>",
  "model": "oracle"
}

POST /transcribe

Invia un file audio per la trascrizione asincrona, con possibilità di attivare la diarizzazione dei parlanti.

Parametri del corpo della richiesta

Richiesta di esempio (con diarizzazione):

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270",
  "word_timestamps": true,
  "model": "edge",
  "output_format": "json",
  "include_diarization": true,
  "num_speakers": 2
}

Risposta:

Restituisce un oggetto con il `jobId` del task di trascrizione inviato.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

GET /transcribe/{jobId}

Recupera lo stato e il risultato di uno specifico job di trascrizione.

Parametri del percorso

Corpo della risposta

Risposta di esempio (output JSON con diarizzazione dei parlanti):

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          }
        ]
      },
      {
        "start": 4.1,
        "end": 6.8,
        "text": "Thank you. Let's begin with the quarterly review.",
        "speaker": "Speaker 2",
        "words": [
          {
            "start": 4.1,
            "end": 4.5,
            "word": "Thank"
          },
          {
            "start": 4.6,
            "end": 4.9,
            "word": "you"
          }
        ]
      }
    ]
  }
}

Diarizzazione dei parlanti

La diarizzazione individua e distingue le diverse voci presenti in una registrazione. Quando la attivi, KolWrite analizza l'audio, rileva i cambi di voce e assegna a ogni segmento l'etichetta del relativo parlante.

Tutti i modelli in elenco supportano la diarizzazione dei parlanti e la separazione dei canali. Con Oracle Mini, l'allineamento dei timestamp si attiva in automatico non appena scegli una modalità per i parlanti.

Come attivare la diarizzazione

Per attivare la diarizzazione dei parlanti, imposta il parametro include_diarization su true nella tua richiesta di trascrizione:

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "include_diarization": true,
  "num_speakers": 3
}

Ottimizzazione del numero di parlanti

Per ottenere i migliori risultati, indica il numero previsto di parlanti con il parametro num_speakers . Se non conosci il numero esatto, puoi:

• Ometti il parametro (il sistema lo rileva in automatico)
• Indica un intervallo approssimativo in base alla tua stima

Diarizzazione Pro

Per identificare i parlanti con maggiore precisione, soprattutto in condizioni acustiche difficili, puoi attivare Pro Diarization. Questa funzione ha un costo aggiuntivo di 0.20 crediti per ora di audio.

Per usarla, imposta il parametro pro_diarization su true. Questo parametro può essere usato insieme a include_diarization.

{
  "audio_url": "https://example.com/panel-discussion.mp3",
  "include_diarization": true,
  "pro_diarization": true
}

Separazione dei parlanti per canale

La separazione dei canali trascrive ogni traccia audio fisica separatamente e assegna ai segmenti e alle parole restituiti i rispettivi campi fisici channel e speaker. Richiede una sorgente da due a otto canali indicata tramite audio_url e non può essere combinata con la diarizzazione normale o Pro. Oracle Mini attiva automaticamente l’allineamento dei timestamp per entrambe le modalità di canale.

Usa standard quando i parlanti intervengono a turno; viene fatturata una sola tariffa audio del modello selezionato. Usa overlap quando i parlanti possono sovrapporsi; viene fatturata la tariffa del modello selezionato sul valore maggiore tra la durata della registrazione e il tempo totale di parlato rilevato sui suoi canali fisici.

{
  "audio_url": "https://example.com/stereo-call.wav",
  "model": "oracle",
  "channel_speaker_separation": "overlap",
  "channel_labels": {"0": "Agent", "1": "Customer"}
}

Webhook di completamento

Imposta webhook_url per ricevere transcription.completed e transcription.failed eventi. Le consegne non riuscite vengono ritentate, ma i client devono continuare a supportare GET /transcribe/{jobId} come fonte di riferimento.

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "output_format": "json",
  "webhook_url": "https://example.com/kolwrite-webhook",
  "webhook_secret": "replace-with-your-secret"
}

Ogni consegna include X-KolWrite-Event, X-KolWrite-Job-Id, X-KolWrite-Delivery-Id e X-KolWrite-Timestamp. La consegna è garantita almeno una volta. I nuovi tentativi usano lo stesso ID di consegna, quindi rimuovi gli eventi duplicati usando X-KolWrite-Delivery-Id. Se hai configurato un segreto, calcola l’HMAC-SHA256 su timestamp + "." + raw_request_body e confrontalo con X-KolWrite-Signature.

{
  "event": "transcription.completed",
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "createdAt": "2026-07-10T09:30:00+00:00",
  "model": "base",
  "output_format": "json",
  "result_available": true,
  "result_omitted": false,
  "result_size_bytes": 12480,
  "result": { "language": "en", "segments": [] }
}

Per output_format: "json", il webhook result è un oggetto JSON. I risultati TXT e SRT vengono consegnati come stringhe.

Nei risultati di grandi dimensioni si può impostare result_omitted su true; recupera il risultato completo da GET /transcribe/{jobId}. Gli eventi non riusciti includono un campo error campo.

Formato di output con diarizzazione

Quando la diarizzazione è attiva, ogni segmento dell’output JSON include il campo speaker che identifica il parlante (ad es. «Speaker 1», «Speaker 2» e così via).

Formati di output

Formato JSON

Output dettagliato con segmenti, timestamp e dati opzionali per singola parola.

Formato TXT

Trascrizione in testo semplice con le etichette dei parlanti (se la diarizzazione è attiva).

Formato SRT

Sottotitoli in formato SubRip con timestamp, pronti per lettori video ed editor di sottotitoli.

Per impostazione predefinita i timestamp per parola sono attivi e l’SRT contiene un blocco per ogni parola, dove compare l’intero segmento con la parola corrente evidenziata. Per avere un solo blocco per segmento, imposta word_timestamps su false. Il WebVTT non viene restituito; se ti serve, converti l’SRT con ffmpeg.

Stato del servizio

Consulta la pagina di stato dell’API di KolWrite per vedere la disponibilità in tempo reale, lo storico dell’uptime e gli incidenti a livello di servizio.

GET /health non richiede alcuna chiave API e restituisce lo stato attuale dell’API, dell’acquisizione dei lavori e dell’elaborazione delle trascrizioni. Una risposta 200 significa che il servizio è operativo o con prestazioni ridotte; una risposta 503 significa che lo stato attuale è sconosciuto o non disponibile. Entrambe le risposte includono i dettagli di stato in JSON.

GET /health/history?period=24h restituisce uno storico compatto della disponibilità. I periodi supportati sono 24h, 7d e 30d.

Codici di stato