Come integrare Text to Speech nelle tue applicazioni

Per integrare Text to Speech nelle tue applicazioni, crea una chiave API, installa l'SDK di ElevenLabs, invia il testo all'endpoint TTS con una voce e un modello, quindi riproduci l'audio restituito.

Questa guida illustra ciascuno di questi passaggi in Python e TypeScript, mostra come scegliere il percorso di integrazione TTS più adatto a te e descrive le soluzioni agli errori più comuni.

Che cos'è un'API Text to Speech?

Un'API Text to Speech consente agli sviluppatori di convertire programmaticamente il testo scritto in audio dal suono naturale, senza dover fornire il proprio modello TTS. Dopo aver integrato un'API TTS in un'applicazione, gli sviluppatori devono semplicemente inviare una richiesta all'API e ricevere l'audio in risposta, aggiungendo facilmente un livello vocale alle applicazioni.

Le migliori API Text to Speech, come quella offerta da ElevenAPI, offrono un controllo granulare sul suono dell'audio finale, dalla scelta della voce che pronuncia un segmento di testo fino all'emozione che trasmette. In base al caso d'uso della tua applicazione, puoi anche scegliere tra opzioni di elaborazione batch e streaming per creare i tuoi campioni audio.

Come funziona una richiesta a un'API Text to Speech

Quando chiami un'API TTS, avvengono alcuni passaggi dietro le quinte per generare il tuo audio.

Ecco come funziona una richiesta a un'API Text to Speech:

1. La tua applicazione invia il testo all'endpoint Text to Speech insieme alla voce e al modello che hai scelto.
2. L'API genera il parlato e restituisce l'audio nel formato di output richiesto, ad esempio MP3.
3. La tua applicazione riproduce l'audio o lo salva come file.

Un'altra nota importante: se la tua applicazione viene eseguita in un browser, dovresti inviare la richiesta tramite il tuo server, in modo che la chiave API non appaia mai nel codice lato client.

Checklist: cosa ti serve prima di iniziare a integrare TTS nelle tue applicazioni

Prima di integrare Text to Speech nelle tue applicazioni, assicurati di avere quanto segue:

• Un account ElevenLabs. Puoi registrarti in pochi minuti.
• Un terminale e un editor di codice.
• Python 3 o Node.js installato sul computer da cui lavori.
• Un modo per riprodurre l'audio che ricevi.

Ora che hai tutto il necessario, sei pronto a integrare TTS nella tua app.

Come integrare Text to Speech nella tua applicazione

Con ElevenAPI, integrare un'API TTS nella tua applicazione richiede solo pochi minuti. Se hai già creato un account, puoi passare direttamente ai passaggi qui sotto. Altrimenti, ricordati di registrarti per iniziare.

I passaggi sono i seguenti:

1. Crea una chiave API
2. Installa l'SDK
3. Effettua la tua prima richiesta
4. Eseguilo

Vediamoli più nel dettaglio.

Crea una chiave API

Recupera una chiave API dalla dashboard API di ElevenLabs. Dopo aver fatto clic su "Create Key", potrai configurare il tipo di API che vuoi impostare. Per questo caso d'uso, assicurati che TTS sia abilitato con "Access".

Copia la chiave API e incollala come variabile d'ambiente in .env (oppure direttamente nella configurazione della tua app, in base alla sua architettura). Salvarla nel file .env è un modo efficace per mantenere segreta la chiave, consentendo allo script di caricarla a runtime.

ELEVENLABS_API_KEY=<your_api_key_here>

Preferisci affidare la configurazione al tuo coding agent? Incolla questo comando nel tuo agent: npx -y @elevenlabs/cli@latest onboard init. La CLI di ElevenLabs apre il browser per consentirti di accedere, salva la chiave nel file env del progetto e guida l'agent nei passaggi restanti. Per usare npx è necessario Node.js. Consulta il guida rapida per i dettagli.

Installa l'SDK

Per configurare un'API Text to Speech devi installare due pacchetti principali. Il primo è l'SDK di ElevenLabs, che gestisce per te la chiamata API. Il secondo è dotenv, che carica la chiave API dal file .env configurato nel passaggio 1.

Se lavori nella CLI, consulta la nostra documentazione dell'API TTS, dove trovi istruzioni più specifiche e le opzioni disponibili.

Ecco come installare l'SDK e dotenv per la tua API TTS sia in Python sia in TypeScript.

Python

pip install elevenlabs
pip install python-dotenv

TypeScript

npm install @elevenlabs/elevenlabs-js
npm install dotenv

Effettua la tua prima richiesta

Successivamente, crea il client. Il client è un oggetto che incapsula ElevenAPI. Crea un file .py o .mts, in base al linguaggio di programmazione che stai usando.

Quattro valori principali influenzeranno l'output:

• ID voce: ElevenLabs offre oltre 17.500 voci nella nostra Voice Library tra cui scegliere. Seleziona una voce che rappresenti al meglio la tua applicazione o abbinala al caso d'uso. Nei blocchi di codice del quickstart qui sotto usiamo "George", con ID voce "JBFqnCBsd6RMkjVDRZzb"
• Testo: La stringa di testo che vuoi far convertire in un file audio dal modello TTS di ElevenAPI.
• ID modello: Il modello specifico che scegli per generare l'audio. Nell'esempio qui sotto abbiamo usato eleven_v4, ma puoi anche selezionare uno qualsiasi dei nostri modelli Text to Speech se è più adatto al tuo caso d'uso. Ad esempio, potresti scegliere Eleven Flash v2.5 (eleven_flash_v2_5 nel campo ID modello) per la sua bassa latenza.
• Formato di output: Definisci la codifica audio che vuoi ricevere dall'API TTS. Per impostazione predefinita riceverai un mp3, ma puoi passare a formati come ulaw o pcm.

Ecco come sono strutturati questi file dell'API TTS in Python e TypeScript. Entrambi gli esempi qui sotto usano il modello eleven_v4.

Python

from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs
from elevenlabs.play import play
import os

load_dotenv()

elevenlabs = ElevenLabs(
  api_key=os.getenv("ELEVENLABS_API_KEY"),
)

audio = elevenlabs.text_to_speech.convert(
    text="The first move is what sets everything in motion.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",  # "George" - browse voices at elevenlabs.io/app/voice-library
    model_id="eleven_v4",
    output_format="mp3_44100_128",
)

play(audio)

TypeScript

import { ElevenLabsClient, play } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";

const elevenlabs = new ElevenLabsClient();
const audio = await elevenlabs.textToSpeech.convert(
	"JBFqnCBsd6RMkjVDRZzb", // "George" - browse voices at elevenlabs.io/app/voice-library
	{
		text: "The first move is what sets everything in motion.",
		modelId: "eleven_v4",
		outputFormat: "mp3_44100_128",
	},
);

await play(audio);

cURL

Puoi anche chiamare l'endpoint da qualsiasi linguaggio che effettui richieste HTTP. Questo esempio cURL invia lo stesso testo e salva l'audio in un file:

curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb?output_format=mp3_44100_128" --output speech.mp3 \
     -H "xi-api-key: $ELEVENLABS_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
  "text": "The first move is what sets everything in motion.",
  "model_id": "eleven_v4"
}'

Eseguilo

Ora sei pronto a eseguire il file dell'API TTS. Esegui uno dei comandi seguenti, in base al fatto che tu stia usando Python o TypeScript.

Python

python example.py

TypeScript

npx tsx example.mts

Dovresti sentire l'audio riprodotto dagli altoparlanti. Con l'esempio cURL, assicurati invece di aprire speech.mp3.

Risoluzione degli errori comuni di integrazione TTS

Se la tua prima richiesta non riesce, confronta il codice di stato ricevuto con questo elenco di possibili errori.

Per l'elenco completo degli errori, consulta la pagina Riferimento degli errori per i dettagli.

Vantaggi dell'integrazione di un'API Text to Speech

Aggiungere un'interfaccia vocale alla tua applicazione offre agli utenti un nuovo modo di interagire. Per alcune persone, come chi ha disabilità visive, potrebbe essere l'unico modo pratico per usare la tua applicazione.

Ecco i vantaggi dell'integrazione di un'API TTS nella tua applicazione:

• Accessibilità: L'audio parlato offre un nuovo modo di interagire con la tua applicazione, rendendola accessibile a chi non riesce a leggerla facilmente su uno schermo.
• Coinvolgimento: Le funzionalità di lettura ad alta voce e ascolto consentono agli utenti di fruire dei contenuti mentre fanno altro, un modo sempre più diffuso di esplorare i contenuti.
• Esperienze vocali: Le risposte vocali offrono ai chatbot e alle guide in-app un modo naturale per rispondere agli utenti.
• Portata multilingue: Eleven v4 copre oltre 90 lingue, consentendo alla tua integrazione di servire un pubblico in tutto il mondo.

Considerata anche la facilità di configurazione, integrare un'API TTS nella tua applicazione è un ottimo modo per renderla più interattiva ed espressiva.

Scegliere il giusto percorso di integrazione e il modello

Sebbene ElevenAPI sia uno dei modi più rapidi e semplici per aggiungere la voce a un'applicazione, puoi scegliere tra diversi altri percorsi in base alle tue esigenze.

Ecco alcuni metodi di integrazione TTS tra cui scegliere:

Se scegli ElevenAPI, dovrai anche selezionare il modello da includere nella richiesta. Ecco una breve guida ai modelli TTS di ElevenLabs disponibili:

Puoi anche scegliere tra oltre 17.500 voci nella nostra Voice Library. Ti basta sostituire l'ID di esempio in uno snippet di codice con quello che preferisci.

Casi d'uso comuni di un'API Text to Speech in un'applicazione

Quando la tua prima richiesta funziona, la stessa chiamata può alimentare numerose funzionalità.

Ecco alcuni esempi di utilizzo di un'API TTS in un'applicazione:

• Lettura in-app: Invia il testo in blocchi e riproduci l'audio in sequenza. Per maggiori informazioni, consulta la nostra guida all'integrazione del batching API.
• Risposte audio del chatbot: Invia ciascuna risposta del chatbot tramite l'API e trasmetti l'audio in streaming all'utente per un'esperienza più interattiva.
• Sistemi telefonici: Richiedi il formato di output ulaw_8000 per la telefonia. Segui la nostra guida all'integrazione TTS con Twilio per maggiori informazioni.

Se vuoi creare agent vocali capaci di sostenere conversazioni bidirezionali, ElevenAgents è pensato per questo. Configuri e distribuisci un agent nella piattaforma, anziché assemblare autonomamente l'intera pipeline vocale. Esplora ElevenAgents per saperne di più.

Integra l'API TTS nelle tue applicazioni con ElevenAPI

L'integrazione di Text to Speech si riduce a quattro passaggi principali: crea una chiave API, installa l'SDK, effettua la tua prima richiesta e poi eseguila. La stessa chiamata funziona in TypeScript, Python o in qualsiasi altro linguaggio in grado di effettuare una richiesta HTTP. Puoi anche scegliere il modello e la voce più adatti alla tua applicazione.

Se sei pronto a integrare TTS nelle tue applicazioni, registrati per effettuare oggi la tua prima richiesta con ElevenAPI oppure scopri di più sull'API Text to Speech.

Domande frequenti