Panoramica dell'API
Chiamare Speechdash dalla propria applicazione e creare le chiavi API che ne autorizzano l'accesso.
L'API di Speechdash permette alla propria applicazione di creare documenti e generare discorsi con le stesse voci dell'app. Tutto ciò che crei tramite l'API appare anche nella tua libreria. Gli audio e i video trascritti finiti creati nell'app appaiono come documenti della libreria (source è transcription, con un transcript_id). Non esiste una risorsa REST /transcripts: usa gli endpoint dei documenti. L'API non avvia lavori di trascrizione.
URL di base:
https://api.speechdash.com/v1Controllo salute (nessuna chiave API): GET https://api.speechdash.com/health
Il contratto leggibile dalla macchina è pubblicato su https://api.speechdash.com/v1/openapi.json, quindi puoi generare un client per il tuo linguaggio.
Endpoints
| Metodo | Percorso | Scopo |
|---|---|---|
GET | /health | Stato del servizio (non sotto /v1) |
GET | /v1/openapi.json | Documento OpenAPI 3.1 |
GET | /v1/me | Account, piano e portafoglio |
GET | /v1/documents | Elenca i documenti della libreria, inclusi i trascritti finiti |
POST | /v1/documents | Crea un documento di testo (source=api) |
GET | /v1/documents/{document_id} | Leggi un documento e il suo testo |
PUT | /v1/documents/{document_id} | Aggiorna titolo, testo, lingua, is_archived, o visibility |
DELETE | /v1/documents/{document_id} | Elimina un documento |
POST | /v1/documents/{document_id}/translate | Nuova versione tradotta (stessi crediti dell'esportazione in MP3) |
GET | /v1/documents/{document_id}/export | Scarica pdf, docx, txt, csv, srt, o vtt |
POST | /v1/audio/speech | Sintetizza fino a 5.000 caratteri (JSON + audio) |
POST | /v1/audio/stream | Flusso WAV, fino a 20.000 caratteri |
POST | /v1/audio/stream/with-timestamps | SSE con audio per frase e segni temporali |
GET | /v1/voices | Catalogo delle voci |
GET | /v1/voices/{voice_id} | Una presets di voce |
Pagine OpenAPI interattive: Account, Documenti, Audio, Voci.
Server MCP (per assistenti AI)
Se usi Cursor, Claude Desktop o un altro client MCP, puoi aggiungere il server MCP ufficiale di Speechdash invece di chiamare HTTP direttamente. Esso espone la stessa libreria (inclusi i trascritti finiti), traduzione, esportazione, voci, snapshot dell'account e sintesi vocale non in streaming come strumenti supportati dalle stesse chiavi API e fatturazione di questa guida. La sintesi vocale in streaming rimane su REST.
Leggi Server MCP per l'elenco completo degli strumenti e la configurazione (stdio o Streamable HTTP). Puoi anche leggere l’Agents hub sul sito di marketing per documenti leggibili dalle macchine rivolti ai sistemi AI. Gli utenti finali possono iniziare da Chiavi API e MCP in questo Centro Assistenza.
Crea una chiave API
Apri Impostazioni → API.
Clicca su Nuova chiave e assegnale un nome che indichi dove verrà utilizzata, ad esempio Server di produzione.
Incolla la chiave immediatamente. Solo la sua prefissa è memorizzata, quindi viene mostrata una sola volta e mai più.
Una chiave agisce sul tuo account. Mantienila sul tuo server, mai in un browser, in un'app mobile o in un repository pubblico. Se una chiave viene compromessa, revocala da Impostazioni → API e ne crea una nuova.
Puoi mantenere fino a 10 chiavi attive, rinominarle in qualsiasi momento e vedere quando ogni chiave è stata utilizzata per l'ultima volta. Revocare una chiave interrompe immediatamente le sue richieste.
Autenticazione di una richiesta
Invia la chiave come token bearer:
curl https://api.speechdash.com/v1/me \
-H "Authorization: Bearer sh_live_tua_chiave"Le richieste senza una chiave valida rispondono con 401 e il codice unauthorized.
GET /me restituisce l'ID del tuo account, l'indirizzo email, il piano e il saldo del portafoglio (wallet_cents e display_credits), oltre a metadati sulla chiave API utilizzata. Usalo per verificare una chiave dopo la configurazione (ad esempio in Zapier).
POST /documents e POST /audio/speech accettano un intestazione opzionale Idempotency-Key. Riprovare la stessa chiave con lo stesso corpo riproduce la prima risposta di successo per 24 ore, quindi un guasto di rete non crea un secondo documento o addebita due volte la sintesi vocale. Se una risposta di sintesi vocale è troppo grande per essere memorizzata, un riprovare con la stessa chiave risponde 409 invece di rigenerare (la richiesta originale è già stata addebitata). Una disconnessione del client su /audio/speech risponde 204, regola qualsiasi audio già prodotto e rilascia la chiave in modo che un riprovare possa rigenerare. Gli endpoint audio in streaming rifiutano l'intestazione.
Crediti
La sintesi vocale consuma crediti dallo stesso portafoglio dell'app: 0,5 crediti (1 centesimo di portafoglio) per ogni 30 secondi di audio generato. Ogni richiesta tiene una stima (più un piccolo margine) prima che la generazione inizi, quindi si regola all'audio effettivamente prodotto. Il credito trattenuto non utilizzato viene rimborsato; ogni richiesta regolata appare in Impostazioni → Utilizzo crediti come Sintesi vocale API. Il campo billed_credits nelle risposte API è in centesimi di portafoglio (2 centesimi = 1 credito visualizzato). Se uno stream viene interrotto a metà, le frasi già consegnate vengono comunque addebitate.
Se il tuo saldo non può coprire il trattenimento, l'API risponde con 402 e il codice payment_required prima di generare qualcosa.
Creare documenti non consuma crediti, ma conta verso il limite giornaliero di documenti del tuo piano (Gratis: 3 al giorno; Unlimited: nessun limite giornaliero) e i limiti di durata dell-upload. L'esportazione di file non consuma crediti.
Fatturazione vs riproduzione Cloud in-app
La riproduzione Cloud in-app riutilizza la cache delle frasi per documento: riprodurre una frase già generata sul server può costare 0 crediti visualizzati. Gli endpoint REST e MCP di sintesi vocale sintetizzano sempre un audio fresco e fatturano per ogni 30 secondi iniziati alla stessa tariffa quando la generazione avviene. Non esiste una cache di riproduzione sull'API o sulla sintesi MCP.
Limitazioni
| Limite | Valore |
|---|---|
Richieste a /documents | 120 al minuto, per account |
Richieste a /audio/* | 60 al minuto, per account |
| Richieste vocali parallele | 3 per account |
POST /audio/speech input | 5.000 caratteri |
POST /audio/stream input | 20.000 caratteri |
| Testo del documento | 500.000 caratteri |
| Chiavi API attive | 10 |
I limiti di velocità sono contati per account, non per chiave, quindi le chiavi aggiuntive non aumentano la tua quota. Ogni risposta include X-Request-ID, e /documents e /audio/* restituiscono anche X-RateLimit-Limit, X-RateLimit-Remaining, e X-RateLimit-Reset. Cita X-Request-ID quando contatti il supporto.
Le richieste vocali hanno anche un limite di parallelismo: una quarta richiesta simultanea risponde con 429 mentre tre sono ancora in esecuzione, quindi una singola integrazione non può monopolizzare la sintesi. Riprova 429 e 503 dopo l'intestazione Retry-After.
Per contenuti più lunghi dei limiti di sintesi vocale, crea un documento con POST /v1/documents ed esporta il suo audio dall'app.
Documenti: condividi, traduzione, esportazione
I documenti serializzati includono visibility e share_url (null quando privati). PUT /v1/documents/{id} accetta visibility per pubblicare una pagina solo in lettura non elencata su /share/document/{id}, e is_archived per archiviare o ripristinare. Le pagine condivise sono solo testo. Non riproducono audio addebitato.
POST /v1/documents/{id}/translate crea una nuova versione tradotta. Addebita lo stesso portafoglio crediti dell'esportazione in MP3 (0,5 crediti per ogni 30 secondi di sintesi stimata) e risponde con 402 quando il portafoglio è insufficiente. Risponde con 503 quando la traduzione non è configurata o non è disponibile.
GET /v1/documents/{id}/export?format=pdf|docx|txt|csv|srt|vtt scarica la versione attuale come allegato. Aggiungi timestamps=1 per includere i tempi delle sezioni su PDF, DOCX, TXT e CSV. SRT e VTT necessitano di una trascrizione o di tempi delle frasi completi. Il testo memorizzato su GET /v1/documents/{id} mantiene gli intestazioni dei timestamp della trascrizione. Nasconderli è un'opzione di lettura dell'app solo.