API di Trascrizione: Panoramica, Autenticazione e Limiti
Come usare l'API REST di VoxScriber: chi ha accesso, come funzionano le chiavi vpt_live_, autenticazione Bearer, limiti di richiesta e addebito a cicli.
L'API REST di VoxScriber ti permette di inviare audio tramite URL e ricevere la trascrizione pronta nel tuo sistema, senza passare dal sito. Usa gli stessi motori e addebita gli stessi cicli delle trascrizioni fatte nel pannello.
Chi può usarla
L'API è disponibile a partire dal piano Profissional (R$ 39,90/mese). Hanno accesso: Profissional, Premium, tutti i piani Enterprise (mensili e annuali) e i piani legacy equivalenti. Se il tuo account non è idoneo, gli endpoint delle chiavi restituiscono l'errore 403 PLAN_NOT_ELIGIBLE.
Chiavi API
Crea la chiave
Copia subito il segreto
vpt_live_... e viene mostrata una sola volta, al momento della creazione. Noi conserviamo solo un hash di essa: non è possibile recuperarla in seguito.Conservala in modo sicuro
Hai perso la chiave? Non c'è modo di visualizzarla di nuovo. Revoca la vecchia chiave e creane una nuova. Le chiavi compromesse vanno revocate immediatamente.
La creazione di chiavi personali non ha ancora una schermata dedicata nel pannello. Se il tuo piano è idoneo e vuoi iniziare a usare l'API, apri un ticket e il team attiva l'accesso con te.
Autenticazione
Ogni richiesta porta la chiave nell'header Authorization:
Authorization: Bearer vpt_live_SUA_CHAVE
Una richiesta senza header restituisce 401 MISSING_API_KEY.
Inviare un audio per la trascrizione
L'endpoint di trascrizione si trova sul gateway api.voxscriber.com:
curl -X POST https://api.voxscriber.com/v1/transcriptions \
-H "Authorization: Bearer vpt_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"audio_url": "https://exemplo.com/gravacoes/reuniao.mp3",
"webhook_url": "https://seusistema.com/webhooks/vozparatexto",
"formats": ["txt", "srt"]
}'
Campi accettati nel corpo: audio_url, webhook_url, engine (ASSEMBLYAI, WHISPER o ELEVENLABS), language, formats (txt, json, srt, vtt, docx, pdf), metadata e idempotency_key. Il risultato arriva al tuo webhook_url — vedi Webhook e notifiche.
Usa idempotency_key con un tuo identificatore (es.: l'ID della registrazione nel tuo sistema). Se la stessa richiesta viene reinviata per errore, l'audio non viene elaborato — né addebitato — due volte.
Limiti
| Limite | Valore |
|---|---|
| Richieste per chiave | 60 al minuto |
| Audio scaricato da URL | fino a 500 MB (timeout di 60 s) |
| Audio tramite passthrough (engine Premium legge l'URL direttamente) | fino a 5 GB |
| Chiavi attive per account | 20 |
Regole di sicurezza sugli URL: solo https, nessun reindirizzamento e gli indirizzi interni/privati sono bloccati. L'URL dell'audio deve essere accessibile pubblicamente.
I formati di esportazione disponibili seguono il gate del tuo piano, come sul sito — i formati fuori piano vengono restituiti elencati in exports_skipped.
Addebito
L'API addebita gli stessi cicli di una trascrizione fatta sul sito, in base al motore scelto (Standard/Whisper: 1 ciclo/min; Premium: 4 cicli/min; Ultra: 10 cicli/min). Non esiste oggi una quota mensile di chiamate né un tetto di spesa per chiave: controlla il consumo tramite il tuo saldo di cicli. Vedi Cosa Sono i Cicli e Quanto Costa Ogni Minuto.
FAQ
Ho perso la mia chiave API. Come la recupero?
Non si può recuperare — nel database resta solo l'hash. Revoca la chiave persa e creane una nuova.
L'API costa più del sito?
No. Il costo in cicli è identico, determinato dal motore e dalla durata dell'audio.
Posso inviare il file direttamente invece di un URL?
Il canale principale è tramite audio_url. Se i tuoi audio non hanno un URL pubblico, contatta il supporto per valutare il flusso migliore per il tuo caso.
Esiste documentazione OpenAPI?
La spec pubblica in /.well-known/openapi.json copre oggi solo gli endpoint pubblici (statistiche e trascrizioni condivise). Per il resto, usa questa guida e il supporto.
Articoli correlati
- Webhook e notifiche
- Automatizzare con l'API
- Cosa Sono i Cicli e Quanto Costa Ogni Minuto
- Esportare in altri strumenti
Non hai risolto? Apri un ticket — il nostro team risponde rapidamente.