Automatizzare le trascrizioni con l'API: Esempi pratici
Ricette di automazione con l'API di VoxScriber: inviare registrazioni tramite URL, scegliere engine e formati, usare idempotency_key e metadata, e ricevere tutto tramite webhook.
Con l'API trasformi qualsiasi fonte di registrazioni — telefonia, registratore di riunioni, sistema interno — in testo ricercabile, senza intervento manuale. Questo articolo presenta il flusso consigliato e ricette pronte. Prima, vedi i prerequisiti in API di trascrizione (piano Profissional+ e chiave vpt_live_).
Il flusso consigliato
- Invia l'audio tramite URL con un
webhook_url. - Ricevi il callback al termine (successo o fallimento).
- Scarica i file esportati tramite i link del risultato — valgono per 7 giorni.
Niente polling: con un limite di 60 richieste/minuto per chiave, interrogare lo stato in loop spreca quota. Il webhook consegna l'esito da solo, con fino a 6 riconsegne se il tuo server non è raggiungibile.
Ricetta 1 — trascrivere ogni nuova registrazione
curl -X POST https://api.voxscriber.com/v1/transcriptions \
-H "Authorization: Bearer $VPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"audio_url": "https://storage.suaempresa.com/calls/2026-08-02-0931.mp3",
"webhook_url": "https://api.suaempresa.com/hooks/vpt",
"formats": ["txt", "docx"],
"metadata": { "call_id": "0931", "agente": "maria" },
"idempotency_key": "call-2026-08-02-0931"
}'
metadatatorna nel webhook — usalo per correlare il risultato con il record nel tuo sistema.idempotency_keygarantisce che invii accidentali (retry dalla tua parte, deploy nel mezzo del job) non processino né addebitino lo stesso audio due volte.
Ricetta 2 — scegliere l'engine in base al costo
Il campo engine accetta ASSEMBLYAI (Premium, predefinito), WHISPER (Standard) e ELEVENLABS (Ultra). Per volumi elevati in cui il costo conta più della rifinitura, usa Whisper — 1 ciclo/min contro 4 del Premium:
-d '{ "audio_url": "...", "webhook_url": "...", "engine": "WHISPER" }'
Regola pratica: Premium per riunioni e interviste importanti; Standard (Whisper) per volumi elevati e audio con rumore; Ultra quando la separazione dei parlanti deve essere impeccabile (disponibile su Profissional+).
Ricetta 3 — sottotitoli automatici
Richiedi formats: ["srt", "vtt"] e ricevi i sottotitoli pronti per YouTube o player web direttamente nel webhook. Dettagli su ogni formato in Esportare in altri strumenti.
Limiti che influiscono sulle automazioni
| Elemento | Regola |
|---|---|
| Rate limit | 60 richieste/min per chiave |
audio_url | solo https, pubblica, fino a 500 MB (download) o 5 GB tramite passthrough con l'engine Premium |
| Formati | seguono il gate del tuo piano; quelli non consentiti tornano in exports_skipped |
| Link di download | scadono in 7 giorni (la trascrizione resta nell'archivio) |
| Cicli | stessi costi del sito, addebitati sullo stesso saldo |
Controlla il tuo saldo di cicli: oggi non esiste un tetto di spesa per chiave. Un'automazione con un loop incontrollato consuma saldo reale. L'idempotency_key è la tua prima linea di difesa.
FAQ
Come ricevo il testo finale — nel webhook o devo scaricarlo?
Il webhook porta l'esito e i link dei file esportati nei formati richiesti. Scarica i file entro 7 giorni; dopodiché, il contenuto continua a essere disponibile nell'archivio del sito.
Posso impostare la lingua dell'audio?
Sì, tramite il campo language. Senza, vale l'impostazione predefinita dell'account; il rilevamento automatico è supportato dalle engine.
E se due sistemi inviano lo stesso audio?
Usa la stessa idempotency_key in entrambi — solo il primo processa e addebita.
L'automazione funziona per i membri dell'organizzazione?
Sì — e il consumo segue le regole del piano aziendale. Per l'audit delle chiamate su larga scala, vedi l'API dedicata.
Articoli correlati
Non risolto? Apri un ticket — il nostro team risponde rapidamente.