Domande frequenti
Come si ottiene la chiave API?
Registrati su /get-api-key/ con Google o email. Riceverai una chiave Bearer attiva immediatamente. Puoi emetterne una nuova in qualsiasi momento: la precedente cessa all’istante. Ogni account ha una sola chiave attiva per questo sito.
Qual è il formato base della richiesta?
Invia una POST a https://api.sp66.info/v1/audio/speech con corpo JSON. Specifica model, input (max 4096 caratteri), voice, response_format e opzionalmente speed e language. Riceverai il file audio generato direttamente nella risposta HTTP.
Posso usare la libreria OpenAI?
Sì, le SDK ufficiali funzionano cambiando il base_url su https://api.sp66.info/v1 e usando la tua chiave. La forma della richiesta è identica all’endpoint OpenAI, quindi non devi modificare la logica del tuo codice.
Quali codici di errore posso ricevere?
Se la sintesi fallisce, la richiesta è gratuita e il credito viene restituito integralmente. I codici HTTP standard (es. 400, 401, 429) indicano errori di sintassi, autenticazione o rate limit.
Come si imposta la velocità?
Usa il campo speed nella richiesta JSON, accettato tra 0.25 e 4.0. Questo permette di accelerare o rallentare la voce sintetica in base alle esigenze del tuo progetto di doppiaggio, mantenendo la qualità audio originale.
Le lingue sono obbligatorie?
No, sono facoltative. Se non imposti il campo language, il sistema lo indovina dal testo (il latino predefinisce l’inglese). Per testi latini non inglesi, imposta esplicitamente il codice ISO per evitare errori di pronuncia.
Quali modelli sono disponibili?
Sono disponibili due modelli: "tts-1" e "tts-1-hd". Entrambi utilizzano lo stesso motore di sintesi e hanno lo stesso prezzo. Puoi scegliere l’uno o l’altro in base alle tue preferenze senza variazioni di costo.
È supportato lo streaming audio?
No, non offriamo streaming WebSocket o audio parziale in tempo reale. Riceverai il file audio completo dopo la generazione. Per testi lunghi, dovrai gestire la suddivisione e l’unione dei file.
Prima richiesta
curl
curl https://api.sp66.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.sp66.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.sp66.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 |
Endpoint Principali
Per le agenzie di animazione, l'API REST di VoceAnimata offre tre endpoint fondamentali per automatizzare il doppiaggio. La generazione audio avviene tramite POST, mentre i metadati sulle voci e i modelli sono accessibili in lettura.
Questa struttura permette di integrare rapidamente la sintesi vocale nei workflow di produzione, garantendo accesso diretto alle 8 voci preimpostate e ai formati audio necessari per il montaggio.
POST /v1/audio/speech per la generazione
Invia il testo dello script e ricevi il file audio. Questo endpoint processa fino a 4096 caratteri per richiesta, restituendo l'audio nel formato selezionato. È il cuore della tua pipeline di produzione.
La risposta contiene direttamente il flusso audio binario o i metadati necessari per il download immediato dei clip generati.
- Endpoint: POST https://api.sp66.info/v1/audio/speech
- Input: testo JSON fino a 4096 caratteri
- Output: file audio (mp3, wav, opus, flac, pcm)
GET /v1/voices per la lista delle voci
Recupera la lista completa delle 8 voci disponibili, incluse le informazioni su lingua e formato. Utile per popolare i menu a tendina nella tua interfaccia di gestione dei progetti.
Le voci includono opzioni femminili come Aria e Nova, e maschili come Felix e Milo, tutte capaci di parlare in 23 lingue.
- Endpoint: GET https://api.sp66.info/v1/voices
- Restituisce: ID voce, nome, genere, lingue supportate
- Utilizzo: mappatura ID voce per le chiamate POST
GET /v1/models per i dettagli sui modelli
Ottieni i dettagli tecnici sui modelli tts-1 e tts-1-hd. Entrambi utilizzano lo stesso motore di sintesi e hanno lo stesso prezzo, offrendo flessibilità nella scelta in base alla qualità audio desiderata.
Questo endpoint aiuta a verificare la disponibilità dei modelli e a configurare correttamente le richieste di generazione audio.
- Endpoint: GET https://api.sp66.info/v1/models
- Modelli: tts-1, tts-1-hd
- Prezzo: identico per entrambi i modelli
Autenticazione e Chiave API
Per autenticare le richieste alla nostra API TTS, devi includere l'intestazione Authorization: Bearer tts-... in ogni richiesta JSON. La chiave API è l'unico mezzo per identificare il tuo account e gestire il consumo dei caratteri e il rate limiting.
Header Authorization: Bearer tts-...
Utilizza sempre il formato standard Bearer. Assicurati che la chiave inizi con tts- e sia copiata esattamente dalla dashboard, senza spazi aggiuntivi.
Gestione della chiave attiva
Ogni account mantiene una sola chiave attiva alla volta. Puoi visualizzare e copiare la tua chiave corrente direttamente nella dashboard dopo il login con Google o email.
Revoca e rinnovo istantaneo
Quando generi una nuova chiave dalla dashboard, quella precedente viene revoca immediatamente. Questo garantisce che solo l'API key più recente possa essere utilizzata per le richieste, migliorando la sicurezza senza bisogno di attesa.
Campi della Richiesta JSON
Ogni richiesta POST richiede un corpo JSON con i parametri essenziali per la generazione audio. Il campo input accetta il testo da convertire, limitato a 4096 caratteri per singola richiesta. Spazi e punteggiatura contano come caratteri; per testi più lunghi, è necessario suddividere lo script e unire i file audio risultanti.
La generazione è sincrona: invii il JSON e ricevi il file audio. Questo flusso semplice si integra perfettamente nei pipeline di animazione, permettendo di automatizzare la creazione di doppiaggi partendo direttamente da script testuali senza complessità tecniche aggiuntive.
Campo 'input' per il testo
Il campo input contiene la stringa di testo da sintetizzare. Il limite è rigorosamente fissato a 4096 caratteri per richiesta. Se la sceneggiatura supera questa lunghezza, il sistema non gestisce automaticamente la suddivisione: è responsabilità del chiamante dividere il testo in parti più piccole e concatenare i file audio restituiti.
I caratteri includono spazi e punteggiatura. Questo conteggio è fondamentale per calcolare i costi, poiché la fatturazione è basata sui caratteri inviati (1 milione di caratteri = $10).
- Max 4096 caratteri per richiesta
- Spazi e punteggiatura contano come caratteri
- Nessun supporto per SSML o tag personalizzati
Campo 'voice' con i 8 preset
Il campo voice richiede uno degli otto preset disponibili, scelti in base al tono del personaggio animato. Le voci coprono uno spettro che va dalle narratrici calde come Aria alle voci profonde e documentary come Orion, fino alle voci amichevoli e conversazionali come Milo.
Ogni voce può parlare in tutte le 23 lingue supportate. Se il campo language non è specificato, il sistema tenta di indovinarlo basandosi sullo script (il testo latino predefinito è l'inglese). Per testi in altre lingue latine, è consigliato impostare esplicitamente il codice ISO.
- Aria (narratrice calda e chiara)
- Nova (voce luminosa e vivace)
- Luna (morbida, per storytelling)
- Sage (calma, istruzionale)
- Felix (energetica, promozionale)
- Milo (amichevole e conversazionale)
- Atlas (neutrale, stile notiziario)
- Orion (profonda, documentaristica)
Campo 'model' tts-1 o tts-1-hd
Il campo model accetta solo due valori: tts-1 o tts-1-hd. Entrambi utilizzano lo stesso motore di sintesi vocale e hanno lo stesso identico prezzo. La scelta tra i due non influisce sulla qualità percepita o sui costi, ma serve a mantenere la compatibilità con le SDK ufficiali.
Puoi scegliere il modello che meglio si integra con la tua configurazione esistente senza dover modificare la logica di fatturazione o la gestione delle richieste nel tuo codice di animazione.
- Valori accettati: 'tts-1', 'tts-1-hd'
- Stesso motore e stesso prezzo per entrambi
- Compatibilità con SDK OpenAI
Formati Audio Supportati
La API restituisce l'audio nel formato richiesto direttamente nella risposta, eliminando la necessità di conversioni successive. Scegliere il formato giusto ottimizza il bilanciamento tra qualità audio e larghezza di banda per i tuoi progetti di doppiaggio.
MP3 per compatibilità web
Il formato MP3 è la scelta standard per la riproduzione web e la maggior parte dei player video. Offre una compressione efficiente che riduce i tempi di caricamento senza sacrificare la chiarezza della voce narrante per contenuti web.
WAV e FLAC per alta qualità
Se stai producendo contenuti broadcast o necessiti di file lossless per il mastering, WAV e FLAC sono ideali. Questi formati preservano ogni dettaglio della sintesi vocale, garantendo la massima fedeltà sonora per le tue produzioni animation.
OPUS e PCM per streaming e editing
PCM fornisce dati audio grezzi non compressi, essenziali per elaborazioni post-produzione precise. OPUS è un formato audio supportato. La nostra API non supporta lo streaming in tempo reale (WebSocket o audio parziale); ricevi il file audio completo dopo la generazione.
Parametri di Controllo
Controlla la prosodia e il ritmo dei tuoi doppiaggi ajustando il parametro speed tra 0.25 e 4.0. Questo consente di adattare la voce ai tempi di scena delle animazioni, dal rallentatore onomatopeico alla voce veloce per le scene action.
Il campo language accetta codici ISO per forzare la pronuncia. Se omesso, il sistema indovina la lingua basandosi sullo script; per testi latini non inglesi, impostalo esplicitamente per evitare errori.
Velocità: da 0.25 a 4.0
La velocità influisce direttamente sulla durata dell'audio generato. Un valore di 1.0 corrisponde al ritmo naturale. Ridurre a 0.25 allunga significativamente la traccia, utile per voci robotiche o narrazioni lente, mentre 4.0 comprime il tempo, ideale per dialoghi frenetici o annunci rapidi nei cartoni.
Lingua: codice ISO opzionale
Specificare la lingua garantisce una pronuncia precisa, specialmente per nomi propri o termini tecnici nei testi italiani, francesi o spagnoli. Il supporto copre 23 lingue, consentendo di mescolare dialoghi multilingua nello stesso progetto senza ambiguità.
- Codici ISO standard (es. 'it', 'en', 'de').
- Supporto completo per tutte le 23 lingue elencate.
- Nessun supporto per vietnamita, thailandese o ucraino.
Gestione automatica del linguaggio
Se non specifichi la language, l'API rileva automaticamente lo script. Il testo in caratteri latini viene di default interpretato come inglese. Per testi latini in altre lingue, è necessario impostare il parametro per evitare letture anglófone.

Limiti e Rate Limiting
La generazione audio è un processo sequenziale che richiede risorse di calcolo. Per garantire stabilità al servizio, ogni chiave API è soggetta a limiti di velocità (rate limiting) che variano in base allo stato del tuo account e alla disponibilità di fondi.
60 richieste al minuto per chiave
Una volta effettuato il primo top-up, il tuo account può elaborare fino a 60 richieste al minuto. Questo limite garantisce che le code di elaborazione non si accumulino eccessivamente, mantenendo tempi di generazione prevedibili anche durante picchi di utilizzo.
10 richieste/min prima del primo pagamento
Per gli account nuovi o in fase di trial, il limite iniziale è di 10 richieste al minuto. Effettua un top-up in USDT (TRC-20) per aumentare la quota e sbloccare la velocità massima. Questo garantisce che le code di elaborazione non si accumulino eccessivamente durante le prime fasi.
Max 4096 caratteri per richiesta
Ogni singola chiamata API può contenere al massimo 4096 caratteri. Per script più lunghi, è necessario dividere il testo in parti più piccole e unire i file audio risultanti. Questo limite è strutturale e garantisce la coerenza vocale per ogni segmento generato.
Gestione Errori e Codici Status
Quando la API restituisce un errore, la risposta JSON indica il problema specifico per consentirti di correggere rapidamente la richiesta o l'account.
La gestione degli errori è fondamentale per mantenere il flusso di produzione audio delle aggie di animazione stabile e prevedibile.
Errori di sintassi
Si verificano quando il corpo JSON è malformato o mancano campi obbligatori come input o voice. Il sistema restituisce un codice 400 Bad Request con un messaggio descrittivo che indica il campo errato.
- Verifica la struttura JSON inviata.
- Controlla che
inputsia una stringa valida.
Errori di autenticazione
L'errore 401 Unauthorized appare se la chiave API è inesistente o revocata. Poiché ogni nuovo rinnovo inattiva istantaneamente la chiave precedente, assicurati di utilizzare sempre la chiave più recente nella intestazione Authorization.
- Aggiorna la chiave se ne hai emessa una nuova.
Errori di limite o quota
L'errore 429 Too Many Requests indica che hai superato i 60 richieste al minuto (o 10 prima del primo top-up). Il servizio restituisce un messaggio chiaro: aspetta che il counter si resetti o effettua un pagamento per sbloccare il limite standard (60 richieste/min).
- Monitora il rate limit nelle dashboard.
- Effettua un top-up USTRC-20 per aumentare la quota.
Esempio con cURL e OpenAI SDK
La documentazione API TTS fornisce gli endpoint e i limiti tecnici necessari per integrare la sintesi vocale nei flussi di lavoro delle agenzie di animazione.
Utilizzare gli esempi qui sotto per generare audio partendo da script di doppiaggio, gestendo formati e autenticazione in modo efficiente.
Snippet cURL pronto all'uso
Invia una richiesta POST a https://api.sp66.info/v1/audio/speech con il corpo JSON contenente model, input e voice. Specifica il formato desiderato con response_format.
Le richieste fallite sono gratuite. Il testo deve rispettare il limite di 4096 caratteri per chiamata.
Configurazione base_url OpenAI
Le SDK ufficiali OpenAI sono compatibili modificando il base_url su https://api.sp66.info/v1. Usa la tua chiave API con il prefisso tts- nell'header Authorization: Bearer.
Questo approccio semplifica l'integrazione senza richiedere librerie custom o nuovi client HTTP.
Gestione della risposta audio
La risposta contiene il file audio binario o il percorso, pronto per essere salvato o inviato al motore di rendering video.
Per testi lunghi, dividi lo script in blocchi inferiori a 4096 caratteri e unisci i file audio risultanti.
Ascolta le 8 voci
Ogni campione sottostante è stato generato da questa API utilizzando la stessa frase. Estendi la tua portata globale con lingue spesso trascurate.
23 lingue
Ogni voce può parlare in una di queste lingue.
