Guida all'Integrazione API Text-to-Speech

Di Team editoriale di VoceIndie · Aggiornato 2026-11-19

Questa guida spiega come integrare la nostra API Text-to-Speech per costruire voice assistant e chatbot efficaci. Troverai tutti i dettagli tecnici necessari per inviare richieste e ricevere file audio, dalle credenziali di accesso ai parametri di configurazione. È pensata per gli indie developer che cercano una soluzione semplice, trasparente e priva di complessità inutili.

Imparerai a usare il formato JSON standard, compatibile con gli SDK OpenAI, e a gestire limiti di velocità e formati di output. Ogni esempio è concreto e pronto all'uso, perfetto per chi vuole generare audio di qualità con poche righe di codice senza doversi preoccupare di protocolli complicati o configurazioni strane.

Guida all'Integrazione API Text-to-Speech

Domande frequenti

Come si autentica la richiesta?

Includi l'intestazione Authorization: Bearer tts-... con la tua chiave API attiva nel corpo della richiesta HTTP. La chiave inizia con tts- e viene generata nella tua dashboard. È l'unico metodo di autenticazione supportato per identificare il tuo account e addebitare i caratteri generati.

Posso usare la libreria ufficiale OpenAI?

Sì, le SDK ufficiali OpenAI funzionano modificando il base_url su https://api.karikya.info/v1 e usando la tua chiave VoceIndie. La forma del corpo della richiesta è identica a quella dell'endpoint /v1/audio/speech di OpenAI, garantendo una compatibilità immediata senza modifiche al codice.

Qual è il limite di caratteri?

Il campo input accetta fino a 4096 caratteri per singola richiesta. Ogni carattere, incluso spazi e punteggiatura, viene conteggiato per il calcolo del prezzo. Se il testo supera questo limite, dovrai suddividerlo in parti più piccole e unire i file audio risultanti.

Cosa succede se supero i rate limit?

Il limite è di 60 richieste al minuto per chiave (10/min prima del primo caricamento). Le richieste vengono elaborate in coda una dopo l'altra. Se superi il limite, la richiesta verrà scartata con un errore 429.

È possibile impostare la lingua esplicitamente?

Sì, usa il campo language con il codice ISO. Se non impostato, il sistema indovina la lingua dal testo (il testo latino predefinito è inglese). Per testi in latino non inglesi, imposta sempre il parametro language per evitare errori di sintesi.

Quali formati audio sono supportati?

Puoi specificare mp3, wav, opus, flac o pcm nel campo response_format. Ogni file generato contiene un watermark invisibile che ne certifica la natura sintetica. Scegli il formato in base alle tue esigenze di compressione e compatibilità con i tuoi voice assistant.

Come si gestisce il testo lungo?

Dividi il testo in blocchi di massimo 4096 caratteri e invia richieste separate. Riceverai più file audio che dovrai unire. La generazione è quasi in tempo reale, ma le richieste vengono accodate sotto carico, quindi i tempi di attesa possono variare in base alla coda.

Il modello tts-1-hd costa di più?

No, tts-1 e tts-1-hd utilizzano lo stesso motore e hanno lo stesso prezzo di $0.01 per 1.000 caratteri. La scelta tra i due modelli non influisce sul costo finale della tua richiesta, permettendoti di testare la qualità senza variare il budget.

Posso cambiare chiave API in qualsiasi momento?

Sì, puoi emettere una nuova chiave dalla dashboard in qualsiasi momento. La chiave precedente diventa immediatamente inattiva al momento dell'emissione della nuova. Puoi avere una sola chiave attiva per account, garantendo un controllo semplice e immediato sull'accesso al tuo account.

Quali sono gli errori più comuni?

Gli errori più comuni derivano da chiavi non valide, limiti di caratteri superati o formattazione JSON errata. Verifica sempre l'autorizzazione e il formato del corpo. Le richieste fallite sono gratuite e il credito viene restituito integralmente, quindi non perdi soldi per errori di sintassi.

L'audio viene salvato sul server?

No, l'audio generato viene restituito nella risposta e non viene memorizzato dai nostri server. Vengono conservati solo i metadati della richiesta (ora, caratteri, stato) per fini di fatturazione. Il testo in input è usato solo per la generazione e non per l'addestramento.

Posso usare la chiave su più dispositivi?

Sì, la chiave API è valida per tutte le richieste HTTP verso l'endpoint. Non ci sono limiti sul numero di dispositivi o istanze che possono utilizzare la stessa chiave simultaneamente, purché rispettino i rate limit di 60 richieste al minuto per chiave.

La velocità influisce sul prezzo?

No, il parametro speed (da 0.25 a 4.0) non influisce sul prezzo. Paghi in base ai caratteri di input inviati, indipendentemente dalla velocità di sintesi o dalla durata finale del file audio generato. La velocità cambia solo l'esperienza uditiva del voice assistant.

Come si ottiene la lista delle voci?

Effettua una richiesta GET /v1/voices per ottenere la lista completa delle 8 voci, dei linguaggi supportati, dei formati e dei prezzi. Puoi anche usare GET /v1/models per verificare i modelli disponibili. Questi endpoint forniscono tutte le informazioni necessarie per integrare la tua applicazione.

Prima richiesta

curl

curl https://api.karikya.info/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.karikya.info/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.karikya.info/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

Autenticazione

Illustrazione dell'onda sonora per: Autenticazione

Per utilizzare l'API Text-to-Speech di VoceIndie è necessario autenticare ogni richiesta con una chiave API valida. La chiave identifica il tuo account e determina il limite di richieste per minuto, garantendo che il servizio sia utilizzato in modo equo e trasparente.

Formato della chiave API

Formato della chiave API

Le chiavi API iniziano sempre con il prefisso tts- e sono associate a un singolo account. Puoi visualizzarle e gestirle nella pagina /get-api-key/, dove trovi anche il saldo e lo storico dei caratteri utilizzati.

  • Formato: tts- seguito da caratteri alfanumerici
  • Una sola chiave attiva per account

Header Authorization

Header Authorization

Ogni richiesta HTTP deve includere l'header Authorization con il valore Bearer <chiave>. Questo header è essenziale per l'identificazione del cliente e il calcolo del consumo nei limiti di rate limit.

  • Header: Authorization: Bearer tts-...

Gestione delle chiavi

È possibile emettere una nuova chiave in qualsiasi momento dalla dashboard. La chiave precedente diventerà immediatamente inattiva, quindi assicurati di aggiornare le configurazioni nei tuoi voice assistant o chatbot prima di revocare quella vecchia.

Endpoint Principale

Illustrazione dell'onda sonora per: Endpoint Principale

Per generare audio, invia una richiesta POST a https://api.karikya.info/v1/audio/speech. Il servizio accetta testo e restituisce un file audio pronto per l'integrazione nei tuoi voice assistant o chatbot.

Questa è l'unica endpoint necessaria per la sintesi. Non richiede protocolli complessi: basta inviare il testo e ricevere il risultato in formato audio.

POST /v1/audio/speech

Invia una richiesta HTTP POST all'endpoint specificato. Il servizio elabora la richiesta e restituisce il file audio sintetizzato.

Corpo della richiesta JSON

Utilizza un corpo JSON standardizzato. I campi obbligatori sono model ("tts-1" o "tts-1-hd"), input (testo fino a 4096 caratteri) e voice (uno degli 8 preset disponibili). Puoi opzionalmente specificare response_format, speed e language.

  • model: "tts-1" o "tts-1-hd"
  • input: testo massimo 4096 caratteri
  • voice: nome del preset (es. "aria", "nova")
  • response_format: mp3, wav, opus, flac, pcm
  • speed: valore tra 0.25 e 4.0
  • language: codice ISO opzionale

Risposta audio

La risposta contiene il file audio binario. I file generati non vengono conservati dal servizio e sono restituiti direttamente nella risposta HTTP.

Parametri Richiesta

Illustrazione dell'onda sonora per: Parametri Richiesta

La generazione audio richiede specificare il modello, il testo di input e la voce desiderata. Ogni richiesta elabora al massimo 4096 caratteri, spazi e punteggiatura inclusi. Per testi più lunghi, è necessario segmentare l'input e unire i file audio risultanti.

Model: tts-1 e tts-1-hd

Scegli tra "tts-1" o "tts-1-hd". Entrambi utilizzano lo stesso motore e hanno lo stesso prezzo di $0.01 per 1.000 caratteri, garantendo coerenza nei costi indipendentemente dalla qualità selezionata.

Input: testo massimo 4096 char

Il campo input accetta stringhe fino a 4096 caratteri. Il testo viene inviato in formato JSON. Se il contenuto supera il limite, la richiesta fallirà; segmenta manualmente il testo e unisci i file audio risultanti.

Voice: selezione preset

Il parametro voice accetta uno degli 8 preset disponibili, tra cui voci maschili e femminili. Ogni voce è ottimizzata per diversi contesti, dal narratore caldo alla voce neutra per le news, supportando tutte le 23 lingue disponibili.

  • aria: narratrice calda e chiara
  • nova: voce brillante ed energica
  • luna: morbido stile storytelling
  • sage: istruzione calma
  • felix: energetico per promo
  • milo: conversazionale e amichevole
  • atlas: neutro per notizie
  • orion: profondo per documentari

Formati e Velocità

Illustrazione dell'onda sonora per: Formati e Velocità

La tua API offre cinque formati audio per adattarsi a ogni ambiente di deployment: mp3, wav, opus, flac e pcm. Scegli il formato che meglio bilancia qualità, compressione e compatibilità con il tuo voice assistant o chatbot.

response_format supportati

I formati disponibili sono mp3, wav, opus, flac e pcm. Ogni formato ha un impatto diverso sulla dimensione del file e sull'uso della CPU del client per la decodifica.

  • mp3: leggero e universale
  • wav: qualità lossless, file più grandi
  • opus: compressione efficiente
  • flac: qualità perfetta senza compressione con perdita
  • pcm: dati grezzi, massima fedeltà

Range di velocità

Puoi regolare la velocità diSpeech tra 0.25 e 4.0. Questo ti permette di ottimizzare la durata dell'audio per le interazioni utente, rendendo il voice assistant più reattivo o più dettagliato a seconda del contesto.

Lingua opzionale

Se non specifichi il parametro language, il sistema tenta di indovinarlo dallo script del testo. Per testi in latino non inglesi, imposta esplicitamente il codice ISO per garantire la pronuncia corretta.

Esempio con cURL

Illustrazione dell'onda sonora per: Esempio con cURL

Per testare rapidamente la sintesi vocale senza scrivere codice complesso, puoi utilizzare cURL direttamente dal terminale. Questo metodo è ideale per verificare che l'endpoint risponda correttamente prima di implementare la logica nella tua voice assistant o chatbot.

Il comando base invia una richiesta POST con un payload JSON che specifica il modello, la voce e il testo da convertire. È il modo più diretto per ottenere un file audio e validare l'integrazione con la tua infrastruttura.

Comando base

Invia una richiesta semplice per generare un file MP3 con la voce predefinita. Sostituisci <YOUR_API_KEY> con la tua chiave attiva ottenuta dalla dashboard.

Parametri personalizzati

Modifica i parametri per adattare la voce al tono del tuo assistente. Ad esempio, usa nova per un tono energico o sage per istruzioni calme. Puoi anche regolare la velocità tra 0.25 e 4.0.

  • Model: tts-1 o tts-1-hd
  • Voce: aria, nova, luna, sage, felix, milo, atlas, orion
  • Formato: mp3, wav, opus, flac, pcm

Output file audio

Il comando restituisce il flusso audio binario. Reindirizzalo in un file locale con l'operatore > per analizzarne la qualità o integrarlo direttamente nel flusso di risposta della tua applicazione.

Esempio con cURL

Esempio con OpenAI SDK

Illustrazione dell'onda sonora per: Esempio con OpenAI SDK

L'API è compatibile con i client ufficiali OpenAI. La sola modifica necessaria è impostare il campo base_url sul nostro endpoint, mantenendo invariata la struttura delle chiamate.

Questo approccio semplifica l'integrazione nei voice assistant esistenti, evitando la creazione di librerie personalizzate.

Modifica di base_url

Imposta base_url su https://api.karikya.info/v1 nel tuo client. Questo instrada le richieste verso il nostro endpoint principale.

Inizializzazione client

Inizializza l'SDK passando la tua chiave API nel parametro api_key e la nuova URL base. Il client utilizzerà automaticamente l'header Authorization: Bearer corretto.

  • Chiave: tts-...
  • URL: https://api.karikya.info/v1

Chiamata speech()

Chiama il metodo speech() con i parametri standard (model, input, voice). Il client restituirà il flusso audio binario pronto per la riproduzione nel tuo chatbot.

Limiti e Rate Limit

Illustrazione dell'onda sonora per: Limiti e Rate Limit

Per garantire un servizio stabile, ogni chiave API è limitata a 60 richieste al minuto. Prima del primo caricamento, il limite è di 10 richieste/minuto. Questo valore è sufficiente per la maggior parte dei voice assistant, ma è utile monitorare i consumi per evitare blocchi temporanei durante picchi di attività.

Coda di elaborazione

Le richieste vengono elaborate in sequenza. Se il server è sotto carico, la tua richiesta potrebbe attendere in coda prima della sintesi. I testi lunghi generano audio in tempo reale (circa 25 caratteri al secondo), mentre le frasi brevi richiedono pochi secondi. Non ci sono garanzie di latenza fissa durante i periodi di alta domanda.

  • Elaborazione sequenziale delle richieste
  • Latenza variabile in base al carico
  • Generazione audio in tempo reale per testi lunghi

Gestione timeout

Se la richiesta non viene evasa entro il tempo previsto dal tuo client, ricevi un errore. Le richieste fallite sono gratuite e il credito viene restituito integralmente. Implementa una logica di retry esponenziale per gestire i picchi di coda senza sovraccaricare l'API, rispettando i limiti di frequenza.

  • Errori di timeout non addebitati
  • Credito restituito automaticamente
  • Retry esponenziale consigliato

Monitoraggio

Consulta il dashboard per vedere l'utilizzo corrente e il saldo residuo. La trasparenza dei dati ti permette di ottimizzare le chiamate e pianificare i caricamenti del credito in base al volume effettivo dei tuoi voice assistant.

Gestione Errori

Illustrazione dell'onda sonora per: Gestione Errori

L'API restituisce codici HTTP standard per indicare lo stato della richiesta. Un errore 4xx segnala solitamente un problema con la chiave o i parametri inviati, mentre il 500 indica un errore interno temporaneo del server.

La trasparenza è fondamentale: se la sintesi non riesce, non vi è alcun addebito. Il credito viene restituito integralmente, permettendoti di testare la tua integrazione senza rischi economici.

Codici di errore comuni

Oltre ai classici 401 (chiave non valida) e 429 (rate limit superato), potresti incontrare errori di validazione se il testo supera i 4096 caratteri o se il formato audio non è supportato. Controlla sempre il corpo della risposta JSON per il messaggio di dettaglio.

  • 400: Parametri mancanti o invalidi
  • 401: Chiave API errata o scaduta
  • 429: Troppe richieste (rate limit)

Richieste fallite gratuite

Se il server non riesce a generare l'audio a causa di un errore interno, l'addebito viene annullato. Questo ti garantisce che paghi solo per i secondi di audio effettivamente consegnati al tuo voice assistant o chatbot.

Logica di retry

Implementa un backoff esponenziale semplice per gestire i picchi di carico. Se ricevi un 429, attendi qualche secondo prima di riprovare. Dato che le richieste vengono elaborate in coda, un retry immediato potrebbe essere rapidamente sovraccaricato.

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.

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. TRON developer hub: TRC-20
  3. ISO 639 language codes
  4. MDN: Web Speech API
  5. Python documentation
  6. IETF RFC 7845: Ogg Opus
  7. LibriVox public-domain audiobooks
  8. FFmpeg documentation
  9. LibriTTS-R paper (arXiv 2305.18802)
  10. W3C WAI: making audio and video accessible
  11. curl documentation
  12. Tether (USDT)

Altro su questo sito