Domande frequenti
Come si ottiene la chiave API per la prima volta?
Accedi alla pagina /get-api-key/ registrandoti con Google o con email e password. Il sistema genera una chiave attiva istantaneamente. I nuovi account email non ricevono il credito di prova iniziale, disponibile solo con l'accesso Google. La chiave è unica per account e visibile immediatamente nella dashboard.
Qual è la lunghezza massima del testo per richiesta?
Il campo input accetta fino a 4096 caratteri per singola richiesta. Questo limite include spazi e punteggiatura. Per testi più lunghi, è necessario suddividere il contenuto in parti inferiori a questa soglia e unire i file audio risultanti durante il processo di generazione per ottenere il file finale completo.
È possibile usare l'SDK Python di OpenAI?
Sì, poiché il formato della richiesta è identico a quello di OpenAI. Puoi utilizzare le librerie ufficiali di OpenAI modificando il campo base_url verso https://api.bs222.info/v1. Questo permette di integrare la nostra API TTS nelle tue applicazioni Python senza dover scrivere client personalizzati da zero.
Quali formati audio sono supportati?
Il parametro response_format supporta mp3, wav, opus, flac e pcm. Questi formati coprono le esigenze standard per la riproduzione web e lo sviluppo di videogiochi. Puoi selezionare il formato più adatto alle tue esigenze di bandwidth o qualità direttamente nel corpo della richiesta POST verso l'endpoint speech.
Cosa significa il codice di errore 429?
Il codice 429 indica che hai superato il limite di rate limiting. Il tuo account è limitato a 60 richieste al minuto per chiave API. Se hai appena creato l'account senza ricariche, il limite è di 10 richieste al minuto. Riduci la frequenza delle chiamate o attendi il reset del finestra temporale.
È possibile impostare una lingua specifica?
Sì, puoi usare il campo facoltativo language con un codice ISO. Se non impostato, la lingua viene dedotta dallo script del testo. Per testi in latino non inglesi, è consigliato impostare esplicitamente il campo language per evitare che il sistema selezioni erroneamente l'inglese come lingua predefinita.
Qual è la differenza tra tts-1 e tts-1-hd?
Non esiste differenza nel prezzo o nel motore tra i due modelli. Entrambi utilizzano lo stesso motore e hanno lo stesso costo. Puoi scegliere l'uno o l'altro in base alle tue preferenze di denominazione del modello senza impatti economici o qualitativi rilevanti sulla generazione.
Come si gestiscono testi superiori a 4096 caratteri?
Devi suddividere manualmente il testo in segmenti da massimo 4096 caratteri ciascuno. Invia richieste separate per ogni segmento e unisci i file audio restituiti. Questo approccio garantisce che ogni parte del testo venga elaborata correttamente entro i limiti della API, mantenendo la coerenza audio tra le diverse sezioni generate.
Le richieste fallite consumano credito?
No, le richieste che falliscono sono gratuite. Se la sintesi non riesce, il credito viene restituito integralmente. Solo le richieste completate con successo vengono addebitate in base ai caratteri elaborati. Questo garantisce che tu paghi esclusivamente per il contenuto audio effettivamente generato e disponibile per il download.
È possibile vedere il log delle richieste?
I metadati delle richieste, inclusi tempo, caratteri e stato, sono conservati per la fatturazione. La dashboard mostra l'utilizzo corrente e il credito residuo. Non è specificata un'interfaccia dettagliata per il log storico avanzato delle singole chiamate, ma i dati necessari per verificare i consumi sono disponibili nell'area account.
Come si revoca una chiave API?
Puoi emettere una nuova chiave API in qualsiasi momento dalla dashboard. Quando ne viene generata una nuova, quella precedente viene disattivata immediatamente. Non esiste un pulsante di 'revoca' separato; il meccanismo di sostituzione della chiave assicura che la vecchia credenziale smetta di funzionare istantaneamente dopo la nuova generazione.
Qual è il limite di richieste al minuto?
Il limite standard è di 60 richieste al minuto per chiave attiva. Per gli account nuovi senza ricariche, il limite è di 10 richieste al minuto. Superato il limite, le richieste successive riceveranno un errore 429. Il limite si resetta ogni minuto e si applica per chiave, non per IP.
È necessario un account per usare l'API?
Sì, è necessario un account per ottenere una chiave API Bearer. La registrazione avviene tramite Google o email/password. Ogni account è legato al sito specifico e fornisce una chiave unica necessaria per l'autenticazione nelle richieste POST. Non è possibile utilizzare l'API in modo anonimo senza credenziali.
Come si esporta l'audio generato?
L'audio viene restituito direttamente nella risposta HTTP della richiesta POST. Non viene memorizzato sul server, quindi devi salvare il file ricevuto immediatamente. Puoi scegliere il formato di output (mp3, wav, opus, flac, pcm) specificandolo nel campo response_format della richiesta per ottenere il file pronto per l'uso nei tuoi progetti.
Prima richiesta
curl
curl https://api.bs222.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.bs222.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.bs222.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 |
Configurazione iniziale e chiave API
Per iniziare a integrare l'API di VoceNPC, registrati su bs222.info/get-api-key/ scegliendo tra accesso con Google o email e password. Il registro crea un account specifico per questo sito, permettendoti di ottenere immediatamente una chiave API attiva.
Registrazione e accesso
La registrazione è il primo passo per accedere alla dashboard dove vengono gestiti credito e utilizzo. Gli account creati con email e password partono senza credito gratuito, mentre l'accesso tramite Google include un trial di 0,50 $ valido per 7 giorni.
Generazione chiave API
Una volta registrato, la dashboard visualizza la tua chiave API personale (formato tts-...). Questa credenziale è necessaria per autenticare tutte le richieste JSON inviate all'endpoint https://api.bs222.info/v1.
Gestione delle chiavi
Ogni account mantiene una sola chiave attiva. Puoi generarne una nuova in qualsiasi momento dalla dashboard; la chiave precedente verrà disattivata istantaneamente, garantendo che solo l'ultima emessa sia valida per le chiamate all'API.
Prima richiesta con curl
Per iniziare a generare voci per i tuoi NPC, la via più diretta è utilizzare curl per inviare una richiesta HTTP POST al nostro endpoint. Questo metodo permette di testare rapidamente la configurazione senza dover scrivere codice complesso o installare librerie aggiuntive, ma richiede curl.
Struttura della richiesta JSON
La richiesta deve contenere un corpo JSON con i campi essenziali. Il testo da convertire non può superare i 4096 caratteri per richiesta. Se il tuo dialogo è più lungo, dovrai suddividerlo e unire i file audio risultanti.
Parametri obbligatori
Oltre al corpo JSON, è necessario impostare l'intestazione Authorization con la tua chiave API (formato Bearer tts-...). Specifica il modello (tts-1 o tts-1-hd), la voce desiderata tra le 8 disponibili e il formato audio di output.
Esempio di comando curl
Ecco un esempio minimale per generare un file MP3 con la voce 'nova'. Sostituisci YOUR_API_KEY con la tua chiave attiva e YOUR_TEXT con il dialogo del tuo gioco.
- curl -X POST https://api.bs222.info/v1/audio/speech \
- -H "Authorization: Bearer YOUR_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{"model": "tts-1", "input": "Hello world", "voice": "nova", "response_format": "mp3"}'
Integrazione con SDK OpenAI
L'API è compatibile con le librerie ufficiali OpenAI nel formato della richiesta. Basterà sostituire l'endpoint di base nel client SDK per utilizzare lo stesso formato di richiesta.
Questo approccio semplifica l'integrazione, permettendo di riutilizzare il codice esistente con minime modifiche strutturali.
Modifica del base_url
Per indirizzare il servizio VoceNPC, impostare base_url su https://api.bs222.info/v1. Questo percorso rimane valido per tutte le chiamate API.
La configurazione richiede solo la modifica dell'URL di base, mantenendo invariata la struttura del payload JSON.
- Impostare
base_urlahttps://api.bs222.info/v1 - Utilizzare la chiave API valida per l'autenticazione
Utilizzo delle librerie ufficiali
È possibile impiegare le librerie client ufficiali OpenAI, poiché il formato della richiesta è identico.
Questo garantisce una compatibilità immediata senza la necessità di sviluppare wrapper personalizzati per il protocollo.
Gestione delle risposte
Le risposte JSON restituite seguono lo standard atteso, contenendo i dati necessari per elaborare l'audio generato.
I client SDK gestiscono automaticamente l'autenticazione e la serializzazione dei parametri inviati.
Parametri avanzati e limiti
La generazione audio richiede una gestione precisa dei parametri tecnici per integrarsi efficacemente nei pipeline delle startup di videogiochi. La lunghezza del testo e la velocità influenzano direttamente la latenza e il costo, fattori critici per l'esperienza di gioco in tempo reale.
Conoscere i limiti di velocità e le soglie di richieste al minuto permette di evitare code di elaborazione e di ottimizzare l'allocazione delle risorse durante il lancio o eventi live.
Lunghezza massima del testo
Ogni richiesta API accetta al massimo 4096 caratteri. Il testo include spazi e punteggiatura nel conteggio. Per dialoghi NPC più lunghi, è necessario suddividere la stringa in parti e unire i file audio risultanti.
Questa limitazione si applica a entrambi i modelli tts-1 e tts-1-hd. La gestione della suddivisione deve avvenire a livello di applicazione per garantire la continuità del suono.
- Max 4096 caratteri per richiesta JSON
- Spazi e punteggiatura contano come caratteri
- Richiede split manuale per testi lunghi
Velocità di lettura
Il parametro speed accetta valori tra 0.25 e 4.0. Il valore predefinito è 1.0. Velocità superiori a 1.0 riducono la durata dell'audio.
Testare le combinazioni di voce e velocità è essenziale per i dialoghi di gioco. Una velocità di 2.0 può essere utile per le notizie in gioco o per NPC che parlano rapidamente, mentre valori bassi migliorano la leggibilità in contesti immersivi.
- Intervallo supportato: 0.25–4.0
- Valore predefinito: 1.0
- Impatto sulla chiarezzza del discorso
Rate limit per minuto
Il limite standard è di 60 richieste al minuto per chiave API. Prima del primo caricamento del saldo, il limite è di 10 richieste al minuto. Le richieste sono elaborate in coda una alla volta, quindi sotto carico i tempi di attesa aumentano.
Il prezzo è di $0.01 per 1.000 caratteri. Con una velocità di generazione approssimativa di 25 caratteri al secondo, le richieste brevi completano in pochi secondi, ma le code possono formarsi durante picchi di generazione simultanea per NPC multipli.
- Standard: 60 req/min
- Trial: 10 req/min
- Elaborazione in coda sequenziale
Formattazione e formati audio
La nostra API restituisce file audio in diversi formati: MP3, WAV, OPUS, FLAC o PCM. La scelta dipende dall'uso finale nel tuo gioco. Per la streaming in tempo reale su WebGL, OPUS o MP3 sono ideali per il bilanciamento tra qualità e dimensione. Per registrazioni locali o post-produzione, WAV o FLAC garantiscono la massima fedeltà senza compressione lossy.
Supporto MP3, WAV, OPUS
Scegli il formato in base alla pipeline audio del tuo engine. MP3 e OPUS riducono la banda, mentre WAV e FLAC preservano l'integrità del segnale. Tutti i formati sono supportati nativamente dalle librerie standard.
Qualità audio variabile
La qualità percepita è identica tra i modelli tts-1 e tts-1-hd. Entrambi utilizzano lo stesso motore di sintesi e hanno lo stesso prezzo. La differenza risiede solo nell'efficienza di codifica, non nel contenuto vocico generato.
Scelta del formato ottimale
Per NPC con dialoghi brevi, usa MP3 per risparmiare memoria. Per narrazioni lunghe o effetti sonori ambianti, valuta FLAC se la banda non è un vincolo. Il formato PCM è utile per debug immediati senza decodifica.
- MP3/OPUS: ideali per streaming e web.
- WAV/FLAC: massima fedeltà per archiviazione.
- PCM: dati grezzi per elaborazione immediata.

Gestione errori e stato API
L'API restituisce errori specifici per identificare rapidamente problemi di autenticazione o limiti di quota. Le richieste fallite non vengono addebitate, garantendo che il credito venga restituito integralmente in caso di sintesi non completata.
È fondamentale monitorare lo stato HTTP per distinguere tra errori temporanei e problemi definiti del testo inviato.
Codici di errore comuni
I codici 401 indicano una chiave API non valida o scaduta, mentre il 429 segnala il superamento del limite di 60 richieste al minuto. Verificare la quota disponibile nel pannello utente.
Un errore 400 può derivare da un formato JSON non valido o da un testo superiore a 4096 caratteri. Controllare la struttura del corpo della richiesta prima di inviare dati complessi.
- 401: Chiave mancante o non valida
- 429: Limite di frequenza superato
- 400: Parametri JSON errati
Gestione timeout
Le richieste vengono elaborate in coda; tempi di attesa variabili sono normali sotto carico. Impostare un timeout client adeguato per evitare interruzioni premature durante la generazione audio.
Non ritentare immediatamente in caso di 503; attendere qualche secondo prima di inviare la stessa richiesta per non saturare la coda del server.
Log delle richieste fallite
I metadati della richiesta (ora, caratteri, stato) vengono conservati per la fatturazione. Utilizzare questi log per identificare pattern di errore e ottimizzare i volumi di generazione senza costi extra per i fallimenti.
Endpoint disponibili e dettagli
Questa sezione descrive i punti di accesso principali dell'API VoceNPC, ottimizzati per l'integrazione nei motori di gioco e nelle applicazioni interattive delle startup.
La struttura è compatibile con gli standard OpenAI, permettendo di sfruttare librerie esistenti con un semplice cambiamento del base_url.
Speech endpoint principale
Invia una richiesta POST a https://api.bs222.info/v1/audio/speech con un corpo JSON contenente il testo e i parametri vocali. Riceverai un file audio binario direttamente nella risposta, pronto per essere memorizzato o riprodotto dal tuo client.
Lista voci e lingue
Query GET su /v1/voices restituisce i 8 preset vocali e le 23 lingue supportate. Ogni voce può parlare tutte le lingue elencate; specifica il language ISO per evitare ambiguità con il testo in latino.
Consulta /v1/models per verificare la disponibilità corrente dei motori di sintesi in tempo reale.
- 8 voci preset (es. aria, nova, atlas)
- 23 lingue supportate
- Nessuna clonazione voce personalizzata
Modello tts-1 e tts-1-hd
Scegli tra tts-1 e tts-1-hd nel campo model. Entrambi utilizzano lo stesso motore di sintesi e hanno lo stesso prezzo di $10 per milione di caratteri, offrendo la stessa qualità audio per le esigenze standard dei giochi.
La differenza risiede solo nel nome del modello, poiché utilizzano lo stesso motore e prezzo.
- Prezzo identico per entrambi i modelli
- Stesso motore di sintesi
Best practices per l'integrazione
L'API accetta un massimo di 4096 caratteri per richiesta. Per dialoghi più lunghi, è necessario segmentare il testo in parti inferiori a questo limite e unire i file audio generati. Questo approccio evita errori di truncation e mantiene la coerenza audio.
Il caching delle risposte può ottimizzare i costi per voci NPC ripetute. Memorizzando i file audio generati, si riducono le chiamate API ridondanti. Monitorare l'utilizzo tramite la dashboard aiuta a controllare i consumi e prevenire esaurimenti del credito.
Gestione testi lunghi
Il limite di 4096 caratteri per richiesta è fisso. Suddividere i testi in parti inferiori a questo limite e unire i file audio generati è la pratica consigliata.
La velocità di generazione è circa reale: 25 caratteri al secondo per testi lunghi. Le brevi frasi richiedono pochi secondi, ma le richieste vengono elaborate in coda sotto carico.
- Dividere il testo in chunk < 4096 caratteri
- Unire i file audio risultanti nel client
Caching delle risposte
Memorizzare i file audio generati riduce i costi per voci NPC ripetute. Poiché i testi sono statici, il caching evita chiamate API ridondanti.
I file audio non vengono archiviati sul server, quindi il caching deve avvenire a livello client o nel proprio storage.
- Implementare cache lato client per voci fisse
- Usare chiavi uniche basate su voce, testo e velocità
Monitoraggio utilizzo
La dashboard mostra credito, caratteri rimanenti e storico richieste. Monitorare i consumi aiuta a prevenire esaurimenti del credito durante lo sviluppo.
I metadati delle richieste (tempo, caratteri, stato) sono conservati per la fatturazione. Usare questi dati per ottimizzare i flussi di generazione.
- Verificare il saldo nella dashboard
- Analizzare i log per ottimizzare le chiamate
Ascolta le 8 voci
Ogni campione sottostante è stato generato da questa API utilizzando la stessa frase. Ogni richiesta fallita non viene addebitata e non conta nel limite di rate.
23 lingue
Ogni voce può parlare in una di queste lingue.
