Documentazione API Text-to-Speech: Guida Tecnica per Dev

Di Team editoriale VocePubblica · Aggiornato 2026-11-18

Questa guida tecnica descrive l'API text-to-speech di VocePubblica, progettata per sviluppatori indipendenti che integrano la sintesi vocale in servizi governativi o campagne NGO. Troverai esempi concreti per generare file audio tramite l'endpoint POST /v1/audio/speech, compatibile con gli SDK OpenAI modificando il base_url, e una panoramica sui 8 voice preset e sui 23 linguaggi supportati.

La documentazione copre l'intero workflow: dall'ottenimento della API Key nella pagina /get-api-key/ alla gestione dei limiti di 60 richieste al minuto. Non troverai promemoria superflui, solo le specifiche tecniche necessarie per l'integrazione rapida, con dettagli su formati audio, codifica dei caratteri e gestione degli errori per garantire un flusso di lavoro prevedibile.

Documentazione API Text-to-Speech: Guida Tecnica per Dev

Domande frequenti

Come si ottiene la API Key?

Registrati alla pagina /get-api-key/ di musiris.net utilizzando Google o email e password. L’account è specifico per questo sito. Una volta effettuato l’accesso, la dashboard mostra la tua chiave API attiva, il saldo e un esempio di comando curl pronto all’uso per iniziare a generare audio immediatamente.

Qual è il formato predefinito di output?

Puoi scegliere tra mp3, wav, opus, flac o pcm impostando il campo response_format nella richiesta JSON. Imposta il campo response_format nella richiesta JSON per ottenere il file audio nel formato desiderato. I file sono restituiti direttamente nella risposta dell’endpoint POST /v1/audio/speech.

L'API supporta SSML per il controllo delle pause?

No, l’API non supporta SSML. Non sono disponibili tag personalizzati per le pause, la pronuncia o l’intonazione. Per controllare la velocità, utilizza il parametro speed (da 0.25 a 4.0). Se hai bisogno di formattazione avanzata del testo, dovrai gestirla a livello applicativo prima dell’invio.

Posso cambiare velocità della voce?

Sì, puoi impostare la velocità tra 0.25 e 4.0 tramite il parametro speed nella richiesta JSON. Questo parametro si applica a tutti i modelli tts-1 e tts-1-hd. La velocità influisce sulla durata della generazione, ma non cambia il tono o il timbro della voce selezionata.

Quali sono i limiti di frequenza (rate limit)?

Il limite è di 60 richieste al minuto per chiave API. Prima del primo caricamento, il limite è di 10 richieste al minuto. Le richieste fallite sono gratuite. Se la coda è sotto carico, le richieste potrebbero attendere prima del processing.

Come si gestisce un testo superiore a 4096 caratteri?

Devi dividere manualmente il testo in parti di massimo 4096 caratteri ciascuna. Invia ogni parte come richiesta separata all’endpoint POST. Successivamente, unisci i file audio risultanti nel tuo codice o script. Ogni richiesta conta come una singola unità ai fini del billing e dei rate limit.

La risposta contiene l'audio o un link?

La risposta contiene direttamente il file audio generato. Non viene restituito un link di download né un ID per recuperare l’audio in seguito. Il file viene restituito nel corpo della risposta HTTP con il formato scelto. I file non vengono memorizzati sul server dopo la consegna.

È disponibile un SDK nativo proprietario?

No, non esiste un SDK proprietario. Utilizza l’SDK ufficiale OpenAI modificando il base_url in https://api.musiris.net/v1. Funziona anche con richieste HTTP standard. Non sono disponibili SDK mobili, plugin WordPress o estensioni browser. La comunicazione avviene tramite JSON e il protocollo standard REST.

Prima richiesta

curl

curl https://api.musiris.net/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.musiris.net/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.musiris.net/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariafemminile
novafemminile
lunafemminile
sagefemminile
felixmaschile
milomaschile
atlasmaschile
orionmaschile
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Primi passi

Illustrazione dell'onda sonora per: Primi passi

Per iniziare a utilizzare l'API TTS di VocePubblica, è necessario prima creare un account sulla piattaforma. Questo passaggio è essenziale per generare le credenziali necessarie all'autenticazione e per monitorare l'utilizzo dei caratteri.

Una volta ottenuto l'accesso, l'autenticazione avviene tramite un token Bearer. Ogni account dispone di una sola chiave attiva, che può essere rigenerata in qualsiasi momento per garantire la sicurezza delle richieste API.

Ottenere la API Key

Ottenere la API Key

Dopo la creazione dell'account, la tua API key viene visualizzata immediatamente nella dashboard. Puoi rigenerare la chiave in qualsiasi momento; la precedente diventerà inattiva istantaneamente.

  • Una sola chiave attiva per account
  • Rigenerazione immediata con invalidazione precedente

Autenticazione Bearer

Autenticazione Bearer

Includi la chiave nell'intestazione HTTP di ogni richiesta POST utilizzando il formato Authorization: Bearer tts-.... Questo metodo garantisce che solo i tuoi servizi possano accedere all'endpoint di sintesi vocale.

Creazione account

Registrati su /get-api-key/ utilizzando il tuo account Google o creando un profilo con email e password. Gli account creati con email e password non includono il credito di prova iniziale.

  • Login con Google o email/password
  • Credenziali visibili nella dashboard

Endpoint Principali

Illustrazione dell'onda sonora per: Endpoint Principali

L'API espone tre endpoint principali per gestire il ciclo di vita della sintesi vocale. L'endpoint di generazione audio è il cuore del servizio, mentre i due endpoint di lettura forniscono metadati essenziali per la configurazione.

Ogni richiesta deve includere la chiave API nell'intestazione Authorization. Le risposte sono in formato JSON o audio binario a seconda dell'endpoint consultato.

POST /v1/audio/speech ['Invia il testo da sintetizzare e ricevi il file audio. Supporta i modelli tts-1 e tts-1-hd con lo stesso motore.', 'Il corpo della richiesta deve essere in JSON con i campi input, voice e response_format. I dati audio vengono restituiti direttamente nel corpo della risposta.'] ['Endpoint principale per la generazione audio', 'Supporta input fino a 4096 caratteri', 'Restituisce audio binario o errore JSON']

GET /v1/voices ['Restituisce la lista delle 8 voci disponibili con i relativi metadati. Ogni voce è associata a un set di lingue supportate e formati audio compatibili.', 'Utilizza questa endpoint per verificare la disponibilità di una voce specifica prima di inviare una richiesta di sintesi.']

GET /v1/models ['Elenco dei modelli disponibili (tts-1 e tts-1-hd). Entrambi utilizzano lo stesso motore e hanno lo stesso prezzo.']

Parametri Richiesta

Illustrazione dell'onda sonora per: Parametri Richiesta

La configurazione richiede la selezione di un modello (tts-1 o tts-1-hd) e di una delle otto voci predefinite. Ogni voce supporta tutte le 23 lingue elencate; per testi latini non inglesi, impostare esplicitamente il campo language per evitare l'indovinamento automatico.

Il parametro input accetta fino a 4096 caratteri per richiesta. Il testo viene elaborato in modo sincrono, quindi per testi più lunghi è necessario dividere l'input in parti più piccole e unirne successivamente i file audio generati.

Model e Voice

Scegliere tra tts-1 o tts-1-hd non cambia il motore di sintesi né il prezzo. Le otto voci (es. aria, nova, felix) sono statiche e non prevedono clonazione personalizzata. Se la lingua non è specificata, il sistema tenta di indovinarla basandosi sullo script, ma per il latino si consiglia l'impostazione esplicita.

  • Modelli: tts-1, tts-1-hd
  • Voci: 8 preset disponibili
  • Lingua: opzionale, ma raccomandata per il latino

Input e Lunghezza

Il campo input accetta stringhe JSON fino a 4096 caratteri. Spazi e punteggiatura vengono conteggiati nel limite. Per progetti governativi o NGO con testi estesi, è necessario implementare logicamente lo splitting del testo in chunk gestibili e l'assemblaggio finale degli audio.

  • Limite: 4096 caratteri per richiesta
  • Conteggio: include spazi e punteggiatura
  • Gestione: splitting manuale per testi lunghi

Response Format

Specificare il formato desiderato tramite response_format. Le opzioni disponibili sono mp3, wav, opus, flac e pcm. La scelta influenza solo la compressione e il peso del file restituito nella risposta.

  • Formati: mp3, wav, opus, flac, pcm
  • Output: file audio binario nella risposta
  • Nessuno streaming in tempo reale

Esempio cURL

Illustrazione dell'onda sonora per: Esempio cURL

Per testare rapidamente la sintesi vocale, invia una richiesta POST all'endpoint con un modello e una voce predefiniti. Questo metodo garantisce il funzionamento base senza configurazioni complesse.

Comando base

Esegui questo comando per generare un file audio MP3 di prova utilizzando la voce predefinita.

  • curl -X POST https://api.musiris.net/v1/audio/speech \ -H "Authorization: Bearer tts-tuachi_key" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Ciao mondo", "voice": "nova"}'

Parametri avanzati

Aggiungi il parametro speed per regolare la velocità di lettura tra 0.25 e 4.0. Specifica response_format per ottenere WAV o FLAC se necessiti di alta fedeltà.

Usa il campo language per forzare il riconoscimento, utile quando il testo è in latino ma non è inglese.

Output audio

La risposta contiene il file audio binario. Salva l'output in un file locale per l'integrazione nei tuoi servizi governativi o NGO.

Uso con SDK OpenAI

Illustrazione dell'onda sonora per: Uso con SDK OpenAI

L'API è compatibile con le librerie ufficiali OpenAI poiché rispetta lo stesso formato delle richieste. Basta sostituire l'URL base con quello di Musiris.net. Questa strategia permette di riutilizzare codice esistente senza modifiche strutturali complesse.

È sufficiente aggiornare la configurazione del client SDK per puntare all'endpoint corretto. Le chiavi API e i parametri di sintesi vocale funzionano come previsto dall'endpoint, garantendo un'integrazione rapida per gli sviluppatori indie.

Configurazione base_url

Imposta la variabile base_url su https://api.musiris.net/v1. Questo punto di ingresso instrada le richieste verso il nostro motore di sintesi vocale, mantenendo la struttura JSON originale.

Assicurati che l'header Authorization contenga la tua chiave tts-.... La libreria invierà automaticamente le credenziali con ogni richiesta POST.

  • base_url: https://api.musiris.net/v1`
  • Authorization: Bearer tts-xxxxxxxx`

Compatibilità librerie

Le librerie openai per Python e Node.js funzionano nativamente. Utilizzano lo stesso schema di serializzazione per i parametri model, input e voice.

Poiché il formato di risposta è identico, non sono necessari adattamenti specifici per la gestione del flusso audio o dei metadati.

Gestione client

Inizializza il client passando la tua API Key e il nuovo base_url. La gestione degli errori e dei limiti di velocità segue le stesse convenziioni SDK standard.

Ricorda che il rate limit è di 60 richieste al minuto. Monitora le intestazioni di risposta per evitare code di elaborazione prolungate.

Uso con SDK OpenAI

Gestione Errori

Illustrazione dell'onda sonora per: Gestione Errori

L'API restituisce codici di errore standard per identificare problemi specifici, consentendo agli sviluppatori di correggere rapidamente le richieste fallite senza costi aggiuntivi.

La gestione robusta degli errori è fondamentale per garantire il corretto funzionamento dei servizi governativi e NGO in ambienti con connettività variabile.

Errori comuni

I principali errori riguardano parametri mancanti o invalidi, come un formato audio non supportato o un voice non esistente. Ogni risposta di errore include un dettaglio chiaro per facilitare il debug immediato.

  • 400 Bad Request: parametri JSON non validi o mancanti
  • 401 Unauthorized: API key errata
  • 413 Payload Too Large: testo superiore a 4096 caratteri

Rate limiting 60/min

Ogni chiave API è limitata a 60 richieste al minuto (10/min prima del primo caricamento). Superato il limite, la risposta è un 429 Too Many Requests.

  • Limit standard: 60 req/min per chiave
  • Limit iniziale: 10 req/min
  • Header X-RateLimit-Remaining indica le richieste residue

Retry logic

Implementare un retry con backoff esponenziale è consigliato per gestire picchi di carico o code di elaborazione. I fallimenti temporanei sono restituiti con codice 503 o 429.

  • Usare retry con jitter per evitare collisioni
  • Ritentare solo su errori 429 o 503
  • Massimo 3 tentativi per richiesta critica

Limiti e Performance

Illustrazione dell'onda sonora per: Limiti e Performance

L'API gestisce fino a 4096 caratteri per singola richiesta. Per testi più lunghi, è necessario suddividere l'input e unire i file audio risultanti.

La generazione richiede circa un secondo ogni 25 caratteri di testo per testi brevi; per testi lunghi la velocità è circa in tempo reale. Le richieste vengono elaborate in sequenza; sotto carico, potrebbe verificarsi un accodamento.

4096 caratteri max

Ogni chiamata POST accetta un massimo di 4096 caratteri, inclusi spazi e punteggiatura. Se il testo supera questo limite, la richiesta viene rifiutata.

  • Calcola i caratteri prima di inviare.
  • Dividi il testo in chunk più piccoli.
  • Unisci i file audio in fase di post-processing.

Velocità reale

Il tempo di generazione è approssimativamente pari alla durata reale dell'audio, con un rapporto di circa 25 caratteri per secondo di audio prodotto.

Accodamento richieste

Le richieste vengono elaborate una dopo l'altra. In periodi di alto traffico, le richieste possono rimanere in coda prima della generazione effettiva.

  • Monitora i tempi di risposta.
  • Implementa ritardi esponenziali nei retry.

Formati Supportati

Illustrazione dell'onda sonora per: Formati Supportati

La scelta del formato influenza direttamente il bilanciamento tra qualità audio e consumo di banda. Ogni formato offre un compromesso diverso tra dimensione del file e fedeltà del suono, permettendo di ottimizzare i costi di trasmissione per ogni progetto.

MP3 e WAV

MP3 è la scelta standard per la web distribution grazie alla sua compressione lossy e ampia compatibilità. WAV offre audio lossless non compresso, ideale per archiviazione locale o editing professionale, garantendo la massima fedeltà possibile dal motore di sintesi.

  • MP3: compresso, ideale per streaming web
  • WAV: lossless, perfetto per archiviazione e editing

OPUS e FLAC

OPUS garantisce una compressione efficiente con ottima qualità a bitrate ridotti, ottimo per applicazioni mobile o connessioni lente. FLAC offre una compressione lossless senza perdita di dati, riducendo la dimensione del file rispetto a WAV mantenendo l'integrità audio originale.

  • OPUS: alta efficienza, bassa banda
  • FLAC: lossless, spazio ridotto rispetto a WAV

PCM grezzo

Il formato PCM restituisce dati audio PCM non compressi. È utile quando il client deve gestire la codifica o l'elaborazione audio direttamente, offrendo il flusso di byte grezzo senza overhead di container.

Ascolta le 8 voci

Ogni campione sottostante è stato generato da questa API utilizzando la stessa frase. Non esiste un archivio persistente dei file audio prodotti, riducendo il rischio di accessi successivi ai dati.

Avatar della voce aria
ariafemminile
Avatar della voce nova
novafemminile
Avatar della voce luna
lunafemminile
Avatar della voce sage
sagefemminile
Avatar della voce felix
felixmaschile
Avatar della voce milo
milomaschile
Avatar della voce atlas
atlasmaschile
Avatar della voce orion
orionmaschile

23 lingue

Ogni voce può parlare in una di queste lingue.

Fonti e ulteriori letture

  1. Wikipedia
  2. ISO 639 language codes
  3. LibriVox public-domain audiobooks
  4. OpenAI API reference: create speech
  5. LibriTTS-R paper (arXiv 2305.18802)
  6. openai-python on GitHub
  7. Node.js documentation
  8. W3C WAI: making audio and video accessible
  9. LibriTTS-R corpus (OpenSLR 141)
  10. Creative Commons Attribution 4.0
  11. Python documentation
  12. FFmpeg documentation

Altro su questo sito