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.mp3Python (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 | |
|---|---|
aria | femminile |
nova | femminile |
luna | femminile |
sage | femminile |
felix | maschile |
milo | maschile |
atlas | maschile |
orion | maschile |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
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
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
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
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
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
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
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.

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
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
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.
23 lingue
Ogni voce può parlare in una di queste lingue.
Fonti e ulteriori letture
- Wikipedia
- ISO 639 language codes
- LibriVox public-domain audiobooks
- OpenAI API reference: create speech
- LibriTTS-R paper (arXiv 2305.18802)
- openai-python on GitHub
- Node.js documentation
- W3C WAI: making audio and video accessible
- LibriTTS-R corpus (OpenSLR 141)
- Creative Commons Attribution 4.0
- Python documentation
- FFmpeg documentation
