Como integrar Text to Speech aos seus aplicativos

Para integrar Text to Speech aos seus aplicativos, crie uma chave de API, instale o SDK da ElevenLabs, envie seu texto ao endpoint de TTS com uma voz e um modelo e reproduza o áudio retornado.

Este guia explica cada uma dessas etapas em Python e TypeScript, mostra como escolher a melhor forma de integrar TTS para você e apresenta soluções para erros comuns.

O que é uma API de Text to Speech?

Uma API de Text to Speech permite que desenvolvedores convertam texto escrito em áudio natural de forma programática, sem precisar hospedar seu próprio modelo de TTS. Depois de integrar uma API de TTS a um aplicativo, basta enviar uma solicitação à API e receber o áudio de volta, adicionando facilmente uma camada de voz aos aplicativos.

As melhores APIs de Text to Speech, como a oferecida pela ElevenAPI, oferecem controle detalhado sobre o som do áudio final, desde a escolha da voz que fala um trecho de texto até a emoção que ela transmite. Dependendo do caso de uso do seu aplicativo, você também poderá escolher entre opções de processamento em lote e por streaming para criar suas amostras de áudio.

Como funciona uma solicitação a uma API de Text to Speech

Quando você chama uma API de TTS, algumas etapas acontecem nos bastidores para entregar seu áudio.

Veja como funciona uma solicitação a uma API de Text to Speech:

1. Seu aplicativo envia o texto ao endpoint de Text to Speech junto com a voz e o modelo escolhidos.
2. A API gera a fala e retorna o áudio no formato de saída solicitado, como MP3.
3. Seu aplicativo reproduz o áudio ou o armazena como arquivo.

Vale observar que, se seu aplicativo roda em um navegador, você deve enviar a solicitação pelo seu próprio servidor para que sua chave de API nunca apareça no código do lado do cliente.

Checklist do que você precisa antes de começar a integrar TTS aos seus aplicativos

Antes de integrar Text to Speech aos seus aplicativos, primeiro verifique se você tem o seguinte:

• Uma conta da ElevenLabs. Você pode criar uma conta em poucos minutos.
• Um terminal e um editor de código.
• Python 3 ou Node.js instalado no computador que você está usando.
• Uma forma de reproduzir o áudio recebido.

Com tudo isso pronto, você já pode incorporar TTS ao seu aplicativo.

Como integrar Text to Speech ao seu aplicativo

Com a ElevenAPI, integrar uma API de TTS ao seu aplicativo deve levar apenas alguns minutos. Se você já criou uma conta, pode ir direto para as etapas abaixo. Caso contrário, lembre-se de criar uma conta para começar.

As etapas são:

1. Criar uma chave de API
2. Instalar o SDK
3. Fazer sua primeira solicitação
4. Executar

Vamos detalhar cada uma delas.

Criar uma chave de API

Obtenha uma chave de API no painel da API da ElevenLabs. Depois de clicar em “Create Key”, você poderá configurar o tipo de API que quer criar. Para este caso de uso, verifique se TTS está habilitado com “Access”.

Copie a chave de API e cole-a como uma variável de ambiente no .env (ou diretamente na configuração do seu aplicativo, dependendo da arquitetura). Armazená-la no arquivo .env é uma forma eficaz de manter sua chave em segredo e, ao mesmo tempo, permitir que seu script a carregue durante a execução.

ELEVENLABS_API_KEY=<your_api_key_here>

Prefere deixar a configuração por conta do seu agente de programação? Cole isto no seu agente: npx -y @elevenlabs/cli@latest onboard init. A CLI da ElevenLabs abre o navegador para você fazer login, salva a chave no arquivo env do projeto e orienta o agente nas etapas restantes. O npx requer Node.js. Consulte o guia de início rápido para saber mais.

Instalar o SDK

Há dois pacotes principais que você precisa instalar ao configurar uma API de Text to Speech. O primeiro é o SDK da ElevenLabs, que fará a chamada de API para você. O segundo é o dotenv, que carregará sua chave de API a partir do arquivo .env configurado na etapa 1.

Se você estiver trabalhando na CLI, consulte nossa documentação da API de TTS, onde encontrará instruções e opções mais específicas que pode usar.

Veja como instalar o SDK e o dotenv em Python e TypeScript para sua API de TTS.

Python

pip install elevenlabs
pip install python-dotenv

TypeScript

npm install @elevenlabs/elevenlabs-js
npm install dotenv

Faça sua primeira solicitação

Em seguida, crie o cliente. O cliente é um objeto que encapsula a ElevenAPI. Crie um arquivo .py ou .mts, dependendo da linguagem de programação que você estiver usando.

Há quatro valores principais que influenciam a saída:

• ID da voz: A ElevenLabs tem mais de 17.500 vozes na nossa Voice Library para você escolher. Selecione uma voz que melhor represente seu aplicativo ou combine a voz ao caso de uso. Nos blocos de código do início rápido abaixo, usamos “George”, cujo ID de voz é “JBFqnCBsd6RMkjVDRZzb”
• Texto: A string de texto que você quer que o modelo de TTS da ElevenAPI converta em um arquivo de áudio.
• ID do modelo: O modelo específico escolhido para gerar áudio. No exemplo abaixo, usamos eleven_v4, mas você também pode selecionar qualquer um dos nossos modelos de Text to Speech caso algum deles seja mais adequado ao seu caso de uso. Por exemplo, você pode optar pelo Eleven Flash v2.5 (eleven_flash_v2_5 no campo de ID do modelo) por sua baixa latência.
• Formato de saída: Defina a codificação de áudio que gostaria de receber da API de TTS. Por padrão, ela fornecerá um mp3, mas você pode mudar para formatos como ulaw ou pcm.

Veja como ficam esses arquivos da API de TTS em Python e TypeScript. Os dois exemplos abaixo usam o modelo 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

Você também pode chamar o endpoint em qualquer linguagem que faça solicitações HTTP. Este exemplo em cURL envia o mesmo texto e salva o áudio em um arquivo:

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"
}'

Execute

Agora você já pode executar o arquivo da API de TTS. Execute um dos comandos a seguir, dependendo de estar usando Python ou TypeScript.

Python

python example.py

TypeScript

npx tsx example.mts

Você deverá ouvir o áudio pelos alto-falantes. No exemplo em cURL, abra speech.mp3.

Solução de erros comuns na integração de TTS

Se sua primeira solicitação falhar, compare o código de status recebido com esta lista de possíveis erros.

Para ver a lista completa de erros, consulte a página de referência de erros para mais detalhes.

Benefícios de integrar uma API de Text to Speech

Adicionar uma interface de fala ao seu aplicativo cria uma nova forma de interação para os usuários. Para algumas pessoas, como indivíduos com deficiência visual, essa pode ser a única maneira prática de usar seu aplicativo.

Estes são os benefícios de integrar uma API de TTS ao seu aplicativo:

• Acessibilidade: O áudio falado oferece uma nova forma de interagir com seu aplicativo, tornando-o acessível para quem não consegue lê-lo facilmente em uma tela.
• Engajamento: Recursos de leitura e audição permitem que os usuários consumam conteúdo enquanto fazem outra coisa, algo que vem se tornando uma das principais formas de navegar.
• Experiências centradas em voz: Respostas faladas dão aos chatbots e guias no aplicativo uma forma natural de responder aos usuários.
• Alcance multilíngue: O Eleven v4 abrange mais de 90 idiomas, permitindo que sua integração atenda públicos do mundo todo.

Principalmente considerando como é fácil configurá-la, integrar uma API de TTS ao seu aplicativo é uma ótima forma de torná-lo mais interativo e expressivo.

Escolha da melhor forma de integração e do modelo

Embora a ElevenAPI seja uma das formas mais rápidas e simples de adicionar voz a um aplicativo, há várias outras opções que você pode escolher conforme suas necessidades.

Veja alguns métodos de integração de TTS:

Se optar pela ElevenAPI, você também precisará escolher qual modelo incluir na solicitação. Veja um guia rápido dos modelos de TTS da ElevenLabs disponíveis:

Você também pode escolher entre mais de 17.500 vozes na nossa Voice Library. Basta substituir o ID de exemplo em um trecho de código pelo que você preferir.

Casos de uso comuns de uma API de Text to Speech em um aplicativo

Depois que sua primeira solicitação funciona, a mesma chamada pode viabilizar diversos recursos.

Veja alguns exemplos de uso de uma API de TTS em um aplicativo:

• Leitura no aplicativo: Envie o texto em partes e reproduza o áudio na ordem correta. Para mais informações, leia nosso guia de integração para processamento em lote com API.
• Respostas de áudio de chatbots: Passe cada resposta do seu chatbot pela API e transmita o áudio por streaming ao usuário para uma experiência mais interativa.
• Sistemas telefônicos: Solicite o formato de saída ulaw_8000 para telefonia. Siga nosso guia de integração de TTS com Twilio para mais informações.

Se você quer criar agentes de voz que conduzem conversas bidirecionais, o ElevenAgents foi criado para isso. Você configura e implanta um agente na plataforma em vez de montar todo o pipeline de fala por conta própria. Explore o ElevenAgents para saber mais.

Incorpore a API de TTS aos seus aplicativos com a ElevenAPI

Integrar Text to Speech se resume a quatro etapas principais: criar uma chave de API, instalar o SDK, fazer sua primeira solicitação e executá-la. A mesma chamada funciona em TypeScript, Python ou qualquer outra linguagem que possa fazer uma solicitação HTTP. Você também pode escolher o modelo e a voz adequados ao seu aplicativo.

Se você está pronto para incorporar TTS aos seus aplicativos, crie uma conta para fazer hoje sua primeira solicitação com a ElevenAPI ou saber mais sobre a API de Text to Speech.

Perguntas frequentes