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.mp3Python (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 | |
|---|---|
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 |
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
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
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
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
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à
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
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-1otts-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 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
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
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.
23 lingue
Ogni voce può parlare in una di queste lingue.
