Tutoriais

Guia de início rápido do Speech Engine

Adicione voz ao seu agente de chat usando o SDK da ElevenLabs.

Este guia mostra como criar um agente de voz com o Speech Engine. Você configura um servidor que conecta seu LLM à ElevenLabs e, em seguida, integra um cliente de navegador para que os usuários possam ter conversas por voz com seu agente.

Use a skill do ElevenLabs Speech Engine para adicionar voz ao seu agente de chat:

npx skills add elevenlabs/skills --skill speech-engine

Como o Speech Engine funciona

O Speech Engine conecta seu LLM à ElevenLabs para que os usuários possam falar com seu agente e ouvir suas respostas. A ElevenLabs gerencia a conversão de fala em texto e de texto em fala; seu servidor fornece a lógica do LLM.

Cada conexão WebSocket representa uma conversa. Quando o usuário fala, a ElevenLabs transcreve o áudio e envia a transcrição ao seu servidor. Seu servidor a encaminha ao LLM e transmite a resposta de volta. A ElevenLabs converte o texto em fala e o reproduz no navegador. O SDK gerencia as conexões, as trocas de turno e a detecção de interrupções.

Pré-requisitos

Este tutorial usa a API da OpenAI para o LLM. Você precisa ter uma chave de API da OpenAI definida na variável de ambiente OPENAI_API_KEY.

Configuração do servidor

1

Crie uma chave de API

Crie uma chave de API no painel aqui, que você usará para acessar a API com segurança.

Armazene a chave como um segredo gerenciado e passe-a aos SDKs como uma variável de ambiente por meio de um arquivo .env ou diretamente na configuração do seu app, conforme sua preferência.

.env
ELEVENLABS_API_KEY=<your_api_key_here>
2

Instale as dependências

pip install elevenlabs openai python-dotenv
3

Exponha o servidor

O Speech Engine precisa de uma URL acessível publicamente. Use o ngrok para expor seu servidor local. O servidor ainda não foi criado, mas o ngrok precisa estar em execução primeiro para que você tenha a URL para a próxima etapa.

ngrok http 3001

Copie a URL de encaminhamento (por exemplo, https://abc123.ngrok.io).

4

Crie uma instância do Speech Engine

Use o SDK para criar uma instância do Speech Engine, passando sua URL do ngrok com o caminho /ws adicionado como URL do WebSocket.

import asyncio
from dotenv import load_dotenv
from elevenlabs import AsyncElevenLabs
load_dotenv()
elevenlabs = AsyncElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)
async def main():
    engine = await elevenlabs.speech_engine.create(
        name="My Speech Engine",
        speech_engine={
            # Note we use the wss protocol instead of https
            "ws_url": "wss://abc123.ngrok.io/ws",
        },
    )
    print(f"Speech Engine ID: {engine.engine_id}")
if __name__ == "__main__":
    asyncio.run(main())

Execute este script e copie o ID do Speech Engine (por exemplo, seng_8k3m9xr4hjnfg983brhmhkd98n6) para a próxima etapa.

5

Crie o servidor

Crie um arquivo chamado server.py ou server.mts com o conteúdo a seguir. Ele configura um servidor, conecta o Speech Engine no caminho /ws e usa a OpenAI para gerar respostas.

import asyncio
import os
from dotenv import load_dotenv
from openai import AsyncOpenAI
from elevenlabs import AsyncElevenLabs
load_dotenv()
# Replace with your Speech Engine ID from step 4
SPEECH_ENGINE_ID = "seng_8k3m9xr4hjnfg983brhmhkd98n6"
openai = AsyncOpenAI(
  api_key=os.getenv("OPENAI_API_KEY"),
)
elevenlabs = AsyncElevenLabs(
  api_key=os.getenv("ELEVENLABS_API_KEY"),
)
def on_init(conversation_id, session):
    print(f"Session started: {conversation_id}")
async def on_transcript(transcript, session):
    stream = await openai.responses.create(
        model="gpt-4o",
        instructions="You are a helpful voice assistant. Keep responses concise and conversational.",
        input=[
            {"role": "assistant" if m.role == "agent" else m.role, "content": m.content}
            for m in transcript
        ],
        stream=True,
    )
    await session.send_response(stream)
def on_close(session):
    print(f"Session ended: {session.conversation_id}")
def on_error(err, session):
    print(f"Error: {err}")
async def main():
    engine = await elevenlabs.speech_engine.get(SPEECH_ENGINE_ID)
    await engine.serve(
        port=3001,
        path="/ws",
        debug=True,
        on_init=on_init,
        on_transcript=on_transcript,
        on_close=on_close,
        on_error=on_error,
    )
if __name__ == "__main__":
    asyncio.run(main())

O callback onTranscript / on_transcript recebe todo o histórico da conversa e a sessão atual. O SDK TypeScript também fornece um AbortSignal que é acionado se o usuário interromper durante uma resposta. Passar signal para a chamada da OpenAI cancela automaticamente a solicitação ao LLM em caso de interrupção.

sendResponse() / send_response() aceita uma string, um iterável assíncrono ou um stream da OpenAI, Anthropic ou Google Gemini. O SDK extrai o conteúdo de texto automaticamente.

No exemplo acima, a transcrição completa do usuário é enviada ao LLM. Em um ambiente de produção, você deve adicionar proteções para evitar tentativas de injeção ou manipulação de prompt.

6

Inicie o servidor

python server.py

Configuração do cliente

1

Instale o SDK do cliente

npm install @elevenlabs/react
2

Crie um endpoint de token

Adicione um endpoint do lado do servidor que gere um token de conversa. Isso mantém sua chave de API fora do navegador e usa WebRTC para oferecer a melhor qualidade de áudio.

import os
from dotenv import load_dotenv
from flask import Flask, jsonify
from elevenlabs import ElevenLabs
load_dotenv()
app = Flask(__name__)
elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)
@app.route("/api/token")
def get_token():
    # Replace with your Speech Engine ID from step 4 of the server setup
    speech_engine_id = "seng_8k3m9xr4hjnfg983brhmhkd98n6"
    response = elevenlabs.conversational_ai.conversations.get_webrtc_token(
        agent_id=speech_engine_id,
    )
    return jsonify(token=response.token)
if __name__ == "__main__":
    app.run(port=3002)
3

Crie a interface da conversa

Busque o token de conversa no seu servidor e use-o para iniciar uma sessão.

App.tsx
import { useConversation } from "@elevenlabs/react";
import { useCallback } from "react";
async function getToken(): Promise<string> {
  const response = await fetch("/api/token");
  if (!response.ok) {
    throw Error("Failed to get conversation token");
  }
  const data = await response.json();
  return data.token;
}
export default function App() {
  const conversation = useConversation({
    onConnect: () => console.log("Connected"),
    onDisconnect: () => console.log("Disconnected"),
    onError: (error: Error) => console.error("Error:", error),
  });
  const startConversation = useCallback(async () => {
    await navigator.mediaDevices.getUserMedia({ audio: true });
    const token = await getToken();
    await conversation.startSession({ conversationToken: token });
  }, [conversation]);
  const stopConversation = useCallback(async () => {
    await conversation.endSession();
  }, [conversation]);
  return (
    <div>
      <p>Status: {conversation.status}</p>
      <button onClick={startConversation} disabled={conversation.status === "connected"}>
        Start conversation
      </button>
      <button onClick={stopConversation} disabled={conversation.status !== "connected"}>
        End conversation
      </button>
    </div>
  );
}
4

Experimente

Verifique se há três processos em execução:

  1. ngrok - encaminhando para a porta 3001
  2. Seu servidor Speech Engine - python server.py ou npx tsx server.mts
  3. O servidor de tokens - npx tsx token-server.mts ou python token_server.py

Abra sua aplicação cliente no navegador e clique em Iniciar conversa. Quando solicitado, conceda acesso ao microfone e fale. Você deverá ouvir a resposta do agente pelos alto-falantes.

Se debug: true estiver ativado no servidor, você verá as transcrições recebidas e as respostas enviadas registradas no console.

Eventos de sessão

EventoCallback TypeScriptCallback PythonDescrição
user_transcriptonTranscripton_transcriptFala do usuário transcrita. Inclui todo o histórico da conversa e um sinal de cancelamento.
initonIniton_initSessão inicializada com um ID de conversa.
closeonCloseon_closeDesconexão limpa da ElevenLabs.
disconnectedonDisconnecton_disconnectWebSocket desconectado inesperadamente.
erroronErroron_errorErro de protocolo ou WebSocket.

Configurando a primeira mensagem do agente

Por padrão, o agente espera o usuário falar primeiro. Para que o agente cumprimente o usuário quando a conversa começar, defina uma primeira mensagem na opção overrides do cliente ao iniciar a sessão.

1

Para permitir que o agente fale primeiro, precisamos atualizar o recurso Speech Engine para permitir essa configuração pelo cliente.

engine = await elevenlabs.speech_engine.update(
    speech_engine_id="seng_8k3m9xr4hjnfg983brhmhkd98n6",
    overrides={
      "first_message": True,
    },
)
2

Depois, configuramos a primeira mensagem no SDK do cliente.

conversation.startSession({
  conversationToken: token,
  overrides: {
    agent: {
      firstMessage: "Hello! How can I help you today?",
    },
  },
});

A primeira mensagem é falada pelo agente assim que a conexão é estabelecida. Ela não aciona o callback onTranscript no seu servidor — é processada inteiramente pela ElevenLabs.

Próximas etapas

Referência do SDK JavaScript

Classes, métodos e eventos do SDK JavaScript.

Referência do SDK Python

Classes, métodos e eventos do SDK Python.

Referência da API

Explore todos os parâmetros e formatos de resposta do Speech Engine.

Aplicativo de exemplo Next.js

Execute localmente um aplicativo completo de início rápido do Speech Engine.