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.

Ottieni una chiave API Guida rapida Lingue supportate

Ultimo aggiornamento: · Markdown

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:

{
  "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

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’usoImpostazionePerché
Grandi volumi di audio pulito a basso costomodel: "base"0,40 crediti (0,48 US$) all’ora
Scelta standard per i file caricati dagli utentimodel: "oracle"Qualità da produzione, con traduzione disponibile
Trascrizione tradotta in un’altra linguaModello Oracle + translate_toUn’unica chiamata, testo già tradotto
Riconoscimento di chi parlainclude_diarization: trueIncluso nel prezzo
Sottotitolioutput_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