Domande frequenti
Come si ottiene la chiave API?
Registra un account alla pagina /get-api-key/ di 11lab.info utilizzando Google o email e password. Il pannello visualizza la chiave attiva, il saldo e un esempio curl. È disponibile una sola chiave attiva per account, emessa automaticamente al primo accesso.
Qual è la struttura della richiesta JSON?
Invia una richiesta POST a https://api.11lab.info/v1/audio/speech con il campo Authorization: Bearer tts-... Il corpo JSON include model, input, voice, response_format, speed e language opzionale. Il formato è identico all'endpoint OpenAI Speech.
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. La selezione del modello non influisce sulla qualità o sui costi, ma solo sull'identificazione tecnica dell'endpoint.
Posso usare l'SDK ufficiale OpenAI?
Sì, gli SDK ufficiali OpenAI funzionano modificando il base_url in https://api.11lab.info/v1. Utilizza la tua chiave API VoceBlog invece di quella OpenAI. Non esiste un SDK proprietario nostro; l'interfaccia è compatibile con lo standard OpenAI.
Quali formati audio posso scegliere?
Puoi selezionare mp3, wav, opus, flac o pcm tramite il campo response_format. Questi sono gli unici formati supportati. La scelta influenza la dimensione del file e la compatibilità con i player, ma non la qualità della voce generata.
Qual è il limite massimo di caratteri?
Ogni richiesta può contenere fino a 4096 caratteri. Per testi più lunghi, devi dividere l'input in parti e unire i file audio risultanti. Spazi e punteggiatura contano come caratteri nel calcolo del limite e del prezzo.
Cosa succede se supero il rate limit?
Il limite è di 60 richieste al minuto per chiave (10 prima del primo carico). Se superi il limite, le richieste potrebbero essere rifiutate o accodate. I processi sono sequenziali; sotto carico, le richieste possono attendere in coda.
Come cambio la velocità di lettura?
Utilizza il parametro speed nella richiesta JSON, con valori tra 0.25 e 4.0. Il valore predefinito è 1.0. Questo parametro regola la velocità di sintesi senza alterare il tono della voce selezionata nel campo voice.
È possibile specificare la lingua?
Sì, usa il campo language con un codice ISO. Se omesso, la lingua è dedotta dallo script (il latino predefinisce l'inglese). Specifica la lingua per testi in latino non inglesi per garantire una pronuncia corretta nei 23 linguaggi supportati.
Come si gestisce la voce predefinita?
Non esiste una voce predefinita obbligatoria. Devi specificare esplicitamente il campo voice con uno degli 8 preset (es. aria, nova, felix).
Quali sono i codici di errore comuni?
Gli errori comuni includono chiavi non valide o rate limit superati. Se la sintesi fallisce, la richiesta è gratuita e il credito viene restituito. Controlla lo stato HTTP della risposta per identificare problemi di autenticazione o parametri mancanti.
I file audio vengono salvati dal server?
No, i file audio generati vengono restituiti nella risposta e non vengono memorizzati sul server. Solo i metadati della richiesta (tempo, caratteri, stato) sono conservati per fini di fatturazione. L'input text è usato solo per la generazione e non è usato per il training.
Posso usare più chiavi contemporaneamente?
Un account ha una sola chiave attiva per sito. Puoi emettere una nuova chiave in qualsiasi momento, ma quella vecchia viene revocata istantaneamente. Non è possibile utilizzare due chiavi attive simultaneamente con lo stesso account VoceBlog.
Come si revoca una chiave API?
Genera una nuova chiave dalla dashboard /get-api-key/. La chiave precedente viene revocata immediatamente. Non esiste un pulsante di revoca manuale; la sostituzione è l'unico metodo per invalidare la chiave corrente e garantirne la sicurezza.
Prima richiesta
curl
curl https://api.11lab.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.11lab.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.11lab.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 e chiavi API
L'autenticazione alla API richiede l'inclusione dell'intestazione Authorization: Bearer <tts-...> in ogni richiesta HTTP. La chiave API è univoca per account e deve essere trasmessa come token Bearer standardizzato per garantire la corretta identificazione del cliente e il conteggio dei crediti.
La gestione delle chiavi è centralizzata nel pannello di controllo. Ogni account dispone di una singola chiave attiva valida per tutte le chiamate API, semplificando la configurazione nei plugin WordPress o negli script di automazione dei blog.
Formato header Authorization
Ogni richiesta al endpoint POST /v1/audio/speech deve includere l'intestazione HTTP Authorization. Il formato è rigorosamente Bearer <chiave>, dove <chiave> inizia per tts- e viene generata al momento della registrazione.
Gestione chiactive
È disponibile una sola chiave attiva per account. La chiave viene visualizzata nella dashboard e può essere utilizzata indifferentemente per richieste standard o HD, poiché condividono lo stesso motore di sintesi.
Revoca immediata nuova chiave
La generazione di una nuova chiave comporta la revoca istantanea di quella precedente. Non esiste un periodo di transizione: la vecchia chiave smette di funzionare immediatamente, garantendo che solo la chiave più recente sia operativa per le chiamate API.
Endpoint principale per la sintesi
L'endpoint principale gestisce la conversione del testo in audio. Si utilizza il metodo POST per inviare la richiesta al server, il quale restituisce il file audio sintetizzato in risposta. Questo è il punto centrale dell'integrazione per l'automazione dei contenuti blog.
Metodo POST
La comunicazione avviene esclusivamente tramite richieste POST. Questo metodo garantisce che i dati del corpo della richiesta vengano inviati correttamente al server per l'elaborazione della sintesi vocale.
Percorso /v1/audio/speech
La URL base è https://api.11lab.info/v1. L'endpoint specifico per la generazione audio è /audio/speech. La combinazione completa da utilizzare nelle chiamate è https://api.11lab.info/v1/audio/speech.
Corpo della richiesta JSON
Il corpo della richiesta deve essere in formato JSON. Deve contenere i campi obbligatori come model, input e voice. Il testo inserito non deve superare i 4096 caratteri per singola richiesta.
- model: "tts-1" o "tts-1-hd"
- input: il testo da sintetizzare
- voice: identificativo della voce selezionata
- response_format: mp3, wav, opus, flac o pcm
Parametri della richiesta
La struttura della richiesta POST prevede parametri specifici per controllare la sintesi. Il campo model accetta i valori tts-1 o tts-1-hd, che condividono lo stesso motore e lo stesso prezzo di $0,01 per 1.000 caratteri. La scelta non influisce sulla logica di fatturazione.
I parametri voice, response_format e speed definiscono le caratteristiche tecniche dell'audio generato. È possibile specificare la lingua tramite language se il testo non è in inglese, garantendo una pronuncia corretta anche per testi in alfabeto latino. Ogni richiesta è limitata a 4096 caratteri.
Model tts-1 e tts-1-hd
Entrambi i modelli utilizzano lo stesso motore di sintesi e lo stesso costo. La selezione avviene tramite il campo model nel corpo JSON della richiesta.
Input testo e limiti
Il campo input accetta stringhe di testo fino a 4.096 caratteri per richiesta. Spazi e punteggiatura contano come caratteri ai fini del calcolo del costo.
Per testi più lunghi, è necessario suddividere l'input in parti più piccole e unire i file audio risultanti. La lunghezza massima è un vincolo tecnico della singola richiesta API.
- Limite: 4.096 caratteri per richiesta
Voce, formato e velocità
Il parametro voice seleziona uno degli otto preset disponibili (es. nova, felix, atlas). Il formato audio è controllato da response_format (mp3, wav, opus, flac, pcm). La velocità di riproduzione è regolabile tra 0,25 e 4,0 tramite il campo speed.
Se il campo language non è impostato, il sistema tenta di indurre la lingua dal testo; per testi in lingue diverse dall'inglese con alfabeto latino, si consiglia di impostarlo esplicitamente.
- Velocità: 0,25 – 4,0
Integrazione con SDK OpenAI
L'API è compatibile con le librerie ufficiali OpenAI. Per utilizzare le SDK, modifica il parametro base_url da https://api.openai.com/v1 a https://api.11lab.info/v1. L'autenticazione richiede l'intestazione Authorization: Bearer <chiave>.
È possibile inviare richieste di sintesi audio utilizzando gli stessi client ufficiali, adattando semplicemente il punto di accesso. Questo garantisce una transizione rapida per gli sviluppatori familiari con l'ecosistema OpenAI.
Modifica base_url
Imposta base_url su https://api.11lab.info/v1 nelle configurazioni del client. Questo reindirizza le chiamate HTTP verso la nostra infrastruttura invece di quella di OpenAI.
- Punto di accesso:
https://api.11lab.info/v1 - Struttura richiesta identica allo standard OpenAI
- Nessuna modifica necessaria ai nomi dei parametri
Utilizzo librerie ufficiali
Le librerie ufficiali funzionano modificando il base_url. Installa la SDK standard e configura la chiave API fornita nella dashboard. Il flusso di generazione audio rimane invariato.
- Compatibilità con Python, Node.js e altre SDK ufficiali
- Nessuna dipendenza da pacchetti proprietari aggiuntivi
- Gestione automatica della serializzazione JSON
Compatibilità richiesta
Il corpo della richiesta rispetta lo schema standard. Supporta i parametri model, input, voice, response_format e speed. La chiave API deve essere valida e associata a un saldo attivo.
- Supporto per modelli tts-1 e tts-1-hd
- Formati audio: mp3, wav, opus, flac, pcm
- Limiti caratteri: 4096 per richiesta
Formati audio disponibili
La scelta del formato influisce direttamente sulla dimensione del file e sulla compatibilità con i player audio integrati nei CMS WordPress. È fondamentale selezionare l'encoding appropriato per garantire una riproduzione fluida nei blog dei clienti senza sovraccaricare le risorse di hosting condivise.
MP3 e WAV standard
Il formato MP3 offre un buon compromesso tra qualità e dimensione, ideale per l'embed nei contenuti web. Il WAV garantisce l'integrità lossless, utile per archiviazione o editing successivo, ma occupa più spazio di memorizzazione.
Opus e FLAC compressi
Opus e FLAC riducono il peso del file. Questi formati sono ottimi per ottimizzare i tempi di caricamento nelle pagine dei blog, soprattutto su connessioni mobili.
PCM grezzo
PCM restituisce dati audio non compressi. È consigliato solo per pipeline di elaborazione tecnica dove la compressione potrebbe introdurre artefatti indesiderati prima di un successivo encoding.

Limiti e rate limiting
La quota standard permette 60 richieste al minuto per chiave API. Questo limite è sufficiente per la maggior parte dei siti WordPress e dei flussi di automazione freelance, garantendo un throughput coerente senza congestioni.
60 richieste al minuto
Ogni chiave attiva supporta fino a 60 chiamate API al minuto. Questo valore è costante e non varia in base al piano, poiché non esistono piani fissi.
Limite pre-ricarica
Prima della prima ricarica, il limite è ridotto a 10 richieste al minuto. Questo garantisce che il credito iniziale gratuito non venga esaurito in modo incontrollato durante le fasi di test iniziali.
Gestione coda richieste
Le richieste vengono elaborate in sequenza. Se il server è sotto carico, le richieste in eccesso vengono accodate. Non vi è garanzia di latenza fissa, ma la coda evita la perdita di richieste.
Gestione errori e risposte
L'API restituisce codici HTTP specifici per indicare lo stato della richiesta. Una risposta 200 conferma il successo, mentre errori come 429 (rate limit) o 401 (auth) richiedono un intervento immediato sull'account o sulla chiave.
In caso di sintesi fallita, il credito viene restituito integralmente. La struttura JSON standardizza la risposta, facilitando il parsing automatico nei plugin WordPress o nei workflow freelance senza necessità di librerie personalizzate.
Codici HTTP di errore
I codici 4xx indicano errori di richiesta non risolvibili con la sola ritenzione. Il 429 segnala il superamento dei 60 richieste al minuto o il limite iniziale di 10 rpm. Il 401 indica una chiave invalidata o inesistente.
Il 400 segnala parametri mancanti o invalidi, come un modello non riconosciuto o un input superiore a 4096 caratteri.
- 400: Bad Request
- 401: Unauthorized
- 429: Too Many Requests
Struttura risposta JSON
Le risposte di successo contengono l'audio binario. Le risposte di errore includono un oggetto JSON con il codice di errore e un messaggio descrittivo.
Questa struttura è compatibile con i client HTTP standard utilizzati negli ambienti server-side per l'automazione dei blog.
Casi di fallimento sintesi
Se la sintesi fallisce per un errore interno, il costo viene rimborsato automaticamente. Non viene applicato alcun addebito per le richieste non completate con successo.
I tempi di attesa in coda possono prolungare la risposta, ma non alterano la struttura finale del JSON di errore.
Esempio rapido con cURL
Questo comando cURL dimostra la sintassi minima per generare un file audio. Utilizza le credenziali API nel header Authorization e invia un testo breve al modello tts-1-hd. È il primo passo per verificare che la connessione con l'endpoint sia attiva prima di integrare il codice nel sito WordPress o nel blog.
Comando base
Invia una richiesta POST a https://api.11lab.info/v1/audio/speech. Sostituisci YOUR_API_KEY con la tua chiave attiva. Il testo deve essere inferiore a 4096 caratteri.
- Metodo: POST
- Endpoint: /v1/audio/speech
- Content-Type: application/json
Parametri inclusi
Specifica il modello tts-1-hd per una qualità superiore. Imposta la voce 'nova' e il formato mp3. Il parametro input contiene il testo da sintetizzare. Non sono necessari altri campi per una generazione di base.
Output file audio
Il comando restituisce il file audio binario direttamente nello stream. Utilizza l'opzione -o per salvare il file localmente con il nome desiderato. Verifica che la lunghezza del file corrisponda alla durata stimata del testo.
Ascolta le 8 voci
Ogni campione sottostante è stato generato da questa API utilizzando la stessa frase. Utilizza un conteggio preciso per prevedere il costo esatto della sintesi audio.
23 lingue
Ogni voce può parlare in una di queste lingue.
