Domande frequenti
Quale voce è migliore per un voice assistant?
, ma Aria è ideale per narratrici calde e chiare, mentre Felix offre un tono energico e promozionale. La scelta dipende dal tono del tuo assistente. Tutte le voci supportano 23 lingue e possono essere selezionate tramite il parametro voice nella richiesta POST al tuo endpoint API.
Come gestisco testi lunghi con l'API?
L'API accetta fino a 4096 caratteri per richiesta. Per testi più lunghi, devi suddividerli in parti di questa dimensione e unire i file audio risultanti nel tuo backend. Il tempo di generazione è circa reale (25 caratteri al secondo), quindi gestisci la coda delle richieste per evitare latenze.
Posso usare la stessa chiave su più server?
Sì, puoi utilizzare la tua chiave API tts-... su più server contemporaneamente. Ogni account ne ha una attiva per sito. Se emetti una nuova chiave, quella precedente viene disattivata immediatamente. Ricorda che il limite è di 60 richieste al minuto per chiave.
Qual è il formato audio più leggero?
Tra i formati disponibili (mp3, wav, opus, flac, pcm), Opus e MP3 offrono la migliore compressione per il dimensionamento del file. WAV e FLAC sono senza perdita ma più pesanti. PCM è grezzo e occupa più spazio. Scegli Opus per un buon equilibrio tra qualità e dimensione.
Come evito di superare i rate limit?
Il limite è di 60 richieste al minuto per chiave (10 prima del primo caricamento). Implementa una coda nel tuo backend per elaborare le richieste in sequenza se necessario. Monitora l'uso nella dashboard. Se superi il limite, le richieste potrebbero fallire o subire ritardi nella coda di elaborazione.
Le voci sono diverse per lingua?
No, le 8 voci preset (come Aria, Nova, Felix) parlano tutte le 23 lingue supportate. La voce rimane la stessa, ma il modello adatta l'accento e la pronuncia in base al codice ISO della lingua inviato o al testo rilevato. Non ci sono voci specifiche per lingua.
È necessario un backend per l'API?
Sì, è consigliabile. L'API accetta JSON e richiede autenticazione Bearer. Un backend gestisce la divisione dei testi lunghi (>4096 caratteri), l'assemblaggio dei file audio e la gestione dei rate limit. Puoi usare gli SDK OpenAI modificando il base_url o fare richieste HTTP dirette dal tuo server.
Come si calcola il costo preciso?
Il costo è $0.01 per 1.000 caratteri, inclusi spazi e punteggiatura. I caratteri vengono conteggiati nel testo inviato. Le richieste fallite sono gratuite e il credito viene restituito. Il prezzo è fisso indipendentemente dal formato o dalla voce scelta. Non ci sono costi fissi mensili.
Posso usare l'API per chiamate vocali?
Sì, puoi generare audio per chiamate vocali. Tuttavia, non offriamo streaming WebSocket in tempo reale. Devi generare il file audio completo e riprodurlo. Per conversazioni interattive, gestisci la latenza generando l'audio in anticipo o in parallelo, considerando che le richieste sono elaborate in sequenza sotto carico.
Quali errori sono comuni nell'integrazione?
Errori comuni includono superare i 4096 caratteri per singola richiesta o non impostare il campo language per testi latini non inglesi, che potrebbero essere interpretati male. Assicurati di gestire i rate limit e di non inviare richieste parallelle senza coda. Verifica sempre lo stato della risposta per evitare costi per errori di sintassi.
Come si gestisce la lingua automatica?
Se non specifichi il campo language, il sistema indovina la lingua dal testo (il testo latino non specificato defaults all'inglese). Per testi latini non inglesi, imposta esplicitamente il codice ISO (es. it per italiano). Le 23 lingue supportate includono italiano, spagnolo, francese e altre.
Il watermark audio è visibile?
Il watermark è inudibile. È un segnale audio nascosto che marca il file come sintesi vocale artificiale. Non influisce sulla qualità dell'ascolto né è visibile nel file audio stesso. Serve a identificare l'origine sintetica del contenuto audio generato.
Posso usare l'API in un'app mobile?
Sì, puoi chiamare l'API da un'app mobile tramite HTTP. Tuttavia, esponendo la chiave API nel client mobile, rischi che venga rubata. È meglio usare un backend intermedio che gestisca l'autenticazione e la generazione audio, oppure proteggere la chiave con limiti di IP se usata direttamente.
Come si aggiornano le voci disponibili?
Le voci sono fisse: 8 preset (Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion). Non ci sono aggiornamenti dinamici o nuove voci aggiunte frequentemente. Puoi vedere la lista completa e i dettagli chiamando l'endpoint GET /v1/voices. Il catalogo non cambia senza preavviso.
Scegliere la Voce Giusta
La scelta della voce influenza direttamente la percezione del tuo voice assistant. Con 8 preset basati su registrazioni licenziate, puoi selezionare il tono che meglio si adatta al contesto d'uso, che sia una chatbot informale o un assistente professionale.
Analisi dei 8 preset vocali
Ogni voce è ottimizzata per uno specifico uso. Aria offre una narrazione chiara, mentre Luna è ideale per storie. Felix e Milo garantiscono energia e naturalezza conversazionale, adatti a interazioni rapide.
- Aria: narratrice chiara e calda
- Nova: brillante e vivace
- Luna: morbida, per storytelling
- Sage: calma e istruttiva
- Felix: energica, per promo
- Milo: amichevole e conversazionale
- Atlas: neutra, per notizie
- Orion: profonda, per documentari
Maschili vs Femminili
La distinzione tra voci maschili e femminili ti permette di bilanciare l'esperienza utente. Atlas offre neutralità per le news, mentre Orion fornisce profondità per contenuti narrativi lunghi. Scegli in base al target del tuo assistente.
Tono e Personalità
Il tono deve coerere con il brand. Usa Sage per istruzioni tecniche o Milo per un supporto clienti amichevole. La coerenza vocale riduce l'affaticamento dell'utente durante conversazioni prolungate, migliorando l'accessibilità.
Configurazione Base
Per integrare la nostra API nei tuoi voice assistant, inizia configurando il base_url su https://api.karikya.info/v1. Questo permette di riutilizzare gli SDK ufficiali OpenAI con poche modifiche. La chiave API, ottenuta al login, si passa nell'header Authorization: Bearer per autenticare ogni richiesta.
Impostazione base_url
Modifica l'URL base nel tuo client HTTP o SDK. Tutte le chiamate ai modelli tts-1 e tts-1-hd passeranno attraverso questo endpoint. La struttura della richiesta JSON rimane identica allo standard OpenAI, garantendo compatibilità immediata.
- Utilizza
https://api.karikya.info/v1come base URL. - Mantieni la struttura JSON standard per le richieste.
Gestione della chiave API
Ogni account dispone di una chiave attiva per sito. Puoi generare una nuova chiave in qualsiasi momento dal pannello; la precedente diventerà invalida istantaneamente. Conserva la chiave in variabili d'ambiente per evitare fughe accidentali nei log.
- Una chiave per account per sito.
- La vecchia chiave cessa all'emissione della nuova.
Prima richiesta di test
Invia una POST a /v1/audio/speech con un testo breve, ad esempio "Ciao, sono il tuo assistente". Verifica di ricevere un file audio valido. Controlla che il saldo sia sufficiente: la prova gratuita offre 0,50$ per i primi test.
- Endpoint: POST /v1/audio/speech.
- Model: tts-1 o tts-1-hd.
Gestione del Testo
Il testo inviato all'API viene elaborato per generare audio coerente. Poiché ogni richiesta ha un limite preciso, la gestione efficiente del corpo del messaggio è fondamentale per evitare interruzioni nel flusso di voce dei tuoi voice assistant.
Questo processo garantisce che il contenuto narrativo non subisca tagli arbitrari, mantenendo la continuità semantica anche quando il testo supera le dimensioni massime consentite in una singola chiamata HTTP.
Split automatico del testo
Quando il testo supera i 4096 caratteri, devi segmentarlo in parti più piccole e unire i file audio risultanti. Ogni segmento viene sintetizzato individualmente e i file audio risultanti vengono uniti in un unico file finale.
Questo approccio richiede che tu implementi la logica di chunking nel tuo client, semplificando l'integrazione nei chatbot.
La continuità dipende dalla tua implementazione dell'unione dei file audio.
- Segmentazione automatica basata sui limiti di caratteri
- Unione trasparente dei file audio generati
- Nessuna modifica al testo originale
Limiti di 4096 caratteri
Ogni chiamata POST accetta al massimo 4096 caratteri nel campo input. Questo limite include spazi e punteggiatura.
Il calcolo è preciso: ogni spazio e segno di interpunzione conta come un carattere. Verifica sempre la lunghezza del testo prima dell'invio.
Superare questo limite restituisce un errore, quindi è consigliabile monitorare la lunghezza dei messaggi nei tuoi assistenti vocali.
- Limite rigido di 4096 caratteri per richiesta
- Include spazi e punteggiatura nel conteggio
- Errori se il testo è troppo lungo
Gestione punteggiatura
La punteggiatura influisce direttamente sulla durata e sulle pause nella sintesi. Virgole e punti determinano le pause naturali.
Non è necessario aggiungere marcatori speciali; il motore TTS interpreta automaticamente la struttura della frase.
Assicurati che il testo sia ben punteggiato per ottenere una prosodia naturale e comprensibile.
- La punteggiatura definisce le pause naturali
- Nessun marker speciale richiesto
- Migliora la comprensibilità del parlato
Ottimizzazione dei Costi
Controlla che ogni spazio e segno di punteggiatura conti, poiché il prezzo è di $0.01 per 1.000 caratteri totali. Un calcolo preciso evita sorprese in fattura e ti permette di stimare esattamente il costo per ogni risposta del tuo chatbot.
Calcolo caratteri effettivi
Considera tutto il testo inviato, spazi inclusi. Per testi lunghi, ricorda che il limite è di 4096 caratteri per richiesta: il tuo codice dovrà segmentare e unire i file audio risultanti per mantenere il controllo sui costi per sessione.
Uso della prova gratuita
Ottieni $0.50 di credito per testare l'API con Google in 7 giorni. È sufficiente per circa 50.000 caratteri. Verifica l'integrazione prima di spendere, poiché gli account creati con email non ricevono questo credito iniziale.
Top-up strategico con USDT
Usa USDT su TRON (TRC-20) per ricaricare da $5. Il saldo non scade e non ci sono costi nascosti. È il metodo più efficiente per indie developer che vogliono mantenere il controllo totale senza abbonamenti mensili.
Lingue e Regionalismi
Il nostro motore supporta 23 lingue, dall'arabo al turkish, garantendo qualità uniforme. Ogni voce può parlare qualsiasi lingua supportata senza limiti aggiuntivi.
Supporto per 23 lingue
Offriamo copertura completa per le principali lingue europee e asiatiche, inclusi inglese, spagnolo, tedesco, francese, italiano, cinese, giapponese e coreano. Sono supportate anche lingue come swahili, norvegese e malese. Non sono disponibili vietnamita, tailandese o ucraino.
Impostazione esplicita della lingua
Se non specifichi il campo language, il sistema indovina la lingua dal testo (il testo latino è predefinito in inglese). Per testi in altre lingue latin-script, imposta esplicitamente il parametro ISO per evitare errori di pronuncia.
Gestione script misti
Il riconoscimento si basa sullo script visivo. Per testi con script misti o lingue non latinche, specifica sempre il codice ISO per garantire la corretta selezione fonetica della voce scelta.
Errori e Robustezza
La robustezza di un voice assistant dipende dalla gestione corretta dei limiti e dei fallimenti. Con un limite di 60 richieste al minuto, è fondamentale monitorare le risposte API per evitare interruzioni brusche durante le conversazioni.
Implementare una logica di retry intelligente previene la perdita di input utente. Inoltre, la gestione degli audio mancanti garantisce che il sistema risponda sempre, mantenendo l'esperienza utente fluida anche sotto carico.
Gestione rate limit
Utilizza un semaforo per limitare le chiamate a 60 al minuto. Monitora l'intestazione Retry-After nei response 429 per pianificare le ritentative senza saturare la coda di elaborazione.
- Limite base: 10 req/min prima del primo top-up
- Limite standard: 60 req/min per chiave attiva
- Utilizza code FIFO per ordinare le richieste in uscita
Retry logico
Non ritentare immediatamente in caso di errore del server. Implementa un backoff esponenziale con jitter per evitare il thundering herd. Ritenta solo su errori transienti (5xx), non su errori di validazione.
- Errori 4xx: verifica il payload e ferma il retry
- Errori 5xx: ritenta con backoff crescente
- Timeout connessione: ritenta una volta sola
Gestione audio mancante
Se l'audio non viene restituito o è corrotto, mostra un messaggio vocale di fallback predefinito. Questo evita che il voice assistant rimanga in silenzio indefinito, mantenendo la conversazione attiva.
- Verifica la lunghezza del file audio ricevuto
- Usa un file MP3 di fallback locale
- Logga l'errore per debug futuro
Formati Audio
La scelta del formato audio influenza direttamente l'esperienza utente e i costi di trasmissione. Ogni formato offre un compromesso diverso tra qualità, dimensione del file e compatibilità con i client dei voice assistant.
Scegliere il formato giusto significa bilanciare la chiarezza della voce sintetica con l'efficienza della banda. Di seguito analizziamo i formati supportati dall'API.
MP3 per web
L'MP3 è lo standard de facto per la maggior parte dei browser e delle piattaforme di voice assistant. Offre una compressione lossy che mantiene una buona intelligibilità a file ridotti, ideale per flussi audio standard.
La compatibilità è universale: funziona nativamente su iOS, Android, web e la maggior parte dei framework di chatbot senza bisogno di codec aggiuntivi.
- Dimensioni file ottimizzate per il risparmio di banda
- Compatibilità nativa con quasi tutti i client
WAV per alta qualità
Il formato WAV offre audio non compresso, preservando ogni dettaglio della voce sintetica. È ideale per archiviazione locale o applicazioni che richiedono la massima fedeltà sonora.
Le dimensioni del file saranno significativamente più elevate rispetto all'MP3, ma la qualità audio rimane invariata rispetto all'output grezzo del motore di sintesi.
- Qualità audio bit-perfect
- Ideale per archiviazione o post-produzione
Opus per efficienza
Opus è un codec moderno che offre una compressione superiore a MP3 a parità di qualità percepita. È particolarmente utile per connessioni mobili o ambienti con banda limitata.
Permette di ridurre i costi di trasferimento dati mantenendo un'ottima chiarezza vocale, ideale per chatbot che operano su reti cellulari.
- Alta efficienza di compressione
- Ideale per reti mobili a banda limitata

Performance e Latenza
La sintesi vocale richiede tempo computazionale. Per testi lunghi, la generazione è circa in tempo reale (25 caratteri al secondo). Le frasi brevi impiegano pochi secondi aggiuntivi per l'avvio del motore.
Capire questi tempi aiuta a progettare interazioni naturali nei tuoi voice assistant, evitando che l'utente si senta lasciato in sospeso durante le pause di elaborazione.
Tempo di generazione reale
La velocità di generazione segue approssimativamente il tempo reale: circa 25 caratteri di testo al secondo per l'audio prodotto. Questo significa che un paragrafo di 500 caratteri richiederà circa 20 secondi di generazione pura.
Gestione della coda
Le richieste vengono elaborate in sequenza. Se il server è sotto carico, una tua richiesta potrebbe attendere in coda prima di iniziare la sintesi. Non ci sono garanzie di latenza fissa, ma il sistema gestisce le code in ordine di arrivo.
Parallelizzazione delle richieste
Puoi inviare più richieste contemporaneamente per ridurre la latenza percepita, sfruttando la tua chiave API. Ricorda che il limite è di 60 richieste al minuto. Pianifica le chiamate in base al traffico previsto del tuo chatbot per evitare code lunghe.
- Limite standard: 60 richieste/minuto
- Limite iniziale: 10 richieste/minuto
Best Practices
Per voice assistant e chatbot, evitare di rigenerare lo stesso audio per frasi comuni è fondamentale per ridurre latenza e costi. Poiché i file non vengono memorizzati sul nostro server, implementare un caching lato client basato sul contenuto del testo è la strategia più efficiente.
Conservare i file generati in cache locale o su un CDN permette di servire istantaneamente le risposte ripetute, migliorando l'esperienza utente senza consumare richieste API aggiuntive per ogni interazione identica.
Caching dei file audio
Implementa una cache basata su hash del testo input. Se la richiesta è identica, servi il file precedentemente generato. Questo riduce drasticamente i costi per frasi standard come "Benvenuto" o "Caricamento in corso".
- Usa hash SHA-256 del testo come chiave di cache
- Valida la cache prima di effettuare la POST a /v1/audio/speech
- Svuota la cache se cambiano parametri come speed o voice
Uso di voci consistenti
Mantieni la stessa voice ID per tutto il flusso conversazionale di un utente. Passare tra "aria" e "nova" a metà frase crea discontinuità udibile. Scegli una voce che rispecchi il tono del tuo brand e usala in modo uniforme.
- Associa una voice specifica all'ID utente nel database
- Evita switch dinamici della voce tra turni di conversazione consecutivi
- Documenta la scelta vociale per coerenza futura
Monitoraggio utilizzo
Tieni traccia dei caratteri consumati per anticipare l'esaurimento del credito. Il piano è a consumo ($0.01 per 1000 caratteri). Monitora i rate limit (60 req/min) per evitare code di attesa che aumentano la latenza percepita.
- Logga caratteri usati per ogni richiesta API
- Imposta alert quando il saldo scende sotto $1.00
- Monitora la coda di elaborazione per stimare la latenza media
Accessibilità
La nostra API è progettata per ridurre l'affaticamento cognitivo, offrendo un controllo preciso sulla sintesi vocale. Questo permette di adattare l'output alle esigenze specifiche di lettura, garantendo una fruizione più chiara e meno stancante per gli utenti con DSA.
Supporto DSA integrato
Offriamo voci naturali con articolazione chiara, ideali per la lettura ad alta voce di testi complessi. La possibilità di regolare la velocità e scegliere tra preset calmi o energici permette di personalizzare l'esperienza in base alle esigenze specifiche.
- Voci con articolazione naturale
- Supporto per letture prolungate
Chiarezza del parlato
Le voci sono ottimizzate per una pronuncia nitida, riducendo le ambiguità che possono confondere chi ha difficoltà di decodifica. Ogni voce è testata per garantire una dizione precisa in tutte le 23 lingue supportate.
Velocità personalizzabile
Il parametro speed (0.25–4.0) ti permette di rallentare il parlato per una migliore comprensione o accelerarlo per una consultazione rapida. Questo controllo è essenziale per adattarsi ai diversi ritmi di lettura degli utenti.
- Range 0.25x a 4.0x
- Adattamento al ritmo utente
Integrazione Avanzata
Per voice assistant e chatbot, simulare lo streaming è un'opzione per migliorare la UX. Poiché l'API restituisce il file completo alla fine, puoi anticipare l'audio spezzando il testo in chunk di 4096 caratteri. Genera ogni chunk in parallelo e riproduci i file in sequenza non appena arrivano, riducendo la latenza percepita dall'utente.
Questa tecnica riduce il tempo di attesa iniziale percepito dall'utente. È ideale per risposte lunghe o narrative, dove la latenza iniziale potrebbe interrompere l'engagement dell'utente senza questo accorgimento.
Streaming simulato
Invia richieste parallele per ogni segmento di testo. Ordina i risultati per indice e riproducili consecutivamente. Questo approccio riduce drasticamente il tempo totale rispetto all'attesa di un singolo file gigante, migliorando la reattività del bot.
Ricorda che ogni chunk ha un costo separato. Monitora il consumo di caratteri per ottimizzare la lunghezza dei chunk tra efficienza e velocità di riproduzione.
- Usa chunk di ~2000 caratteri per bilanciare latenza e overhead.
- Riproduci i file in ordine di arrivo per minimizzare il gap.
Gestione stati conversazionali
Mantieni il contesto della conversazione nel tuo backend, non nell'API. Passa solo il testo da sintetizzare alla richiesta POST. L'API è stateless: ogni chiamata è indipendente. Usa la variabile language per forzare la lingua se il contesto cambia, evitando guess errati.
Conserva le variabili di stato (es. tono, voce preferita) nel tuo sistema per applicare automaticamente le impostazioni voice e speed correnti a ogni nuova sintesi, garantendo coerenza narrativa.
- Non affidarti all'API per la memoria del contesto.
- Passa esplicitamente
languagese il contesto linguistico cambia.
Logica di fallback
Se una sintesi fallisce, il costo viene rimborsato. Implementa un retry con backoff esponenziale per errori temporanei. Se il limite di rate (60 req/min) viene raggiunto, attendi o scala le richieste. In caso di errore persistente, restituisci un messaggio testuale o un audio di riserva pre-caricato.
Monitora lo status code: 200 per successo, altri per errori. Gestisci i timeout con un timeout di richiesta ragionevole, considerando che la generazione può variare in base al carico del server.
- Retry con backoff esponenziale per errori 429 o 5xx.
- Usa audio di riserva per errori critici non recuperabili.
Prossimi Passi
Una volta completata l'integrazione API, il passaggio cruciale è validare la qualità audio in contesti reali. I voice assistant operano spesso in ambienti rumorosi o con connessioni instabili, dove la chiarezza della sintesi vocale diventa determinante per l'esperienza utente.
Testare su dispositivi diversi (smart speaker, smartphone, web) rivela problemi di latenza o formattazione che l'emulatore non mostra. Questo passaggio assicura che la voce risulti naturale e comprensibile anche in condizioni d'uso non ottimali.
Test su dispositivi reali
Verifica la compatibilità dei formati audio (mp3, opus) sui vari client. Misura il tempo di risposta effettivo tra l'invio della richiesta e la riproduzione dell'audio, considerando la latenza di rete.
Assicurati che la velocità di riproduzione sia adeguata al tipo di dispositivo. Alcuni smart speaker potrebbero avere limiti di buffer che richiedono una gestione attenta dei chunk audio.
Raccolta feedback utenti
Implementa meccanismi semplici per raccogliere opinioni sulla naturalezza della voce. Chiedi agli utenti finali se il tono della voce (es. 'aria' o 'atlas') è appropriato per il contesto conversazionale.
Analizza i dati di utilizzo per identificare voci o lingue sottoutilizzate. Il feedback diretto aiuta a calibrare le impostazioni di velocità e linguaggio per migliorare l'accessibilità, specialmente per utenti con DSA.
Scalatura del servizio
Monitora l'uso della chiave API per rimanere entro i 60 richieste al minuto. Se prevedi picchi di traffico, valuta di distribuire le richieste su più istanze o di gestire la coda con logica di retry.
Controlla il saldo USDT per garantire la continuità del servizio. Poiché non ci sono limiti di spesa mensili, puoi aumentare il volume semplicemente ricaricando, mantenendo la trasparenza sui costi.
Ascolta le 8 voci
Ogni campione sottostante è stato generato da questa API utilizzando la stessa frase. Offriamo voci naturali con articolazione chiara, ideali per la lettura ad alta voce di testi complessi.
23 lingue
Ogni voce può parlare in una di queste lingue.
