Hoppa till navigering

Snabbstart för Speech Engine

Lägg till röst i din chattagent med ElevenLabs SDK.

Den här guiden visar hur du bygger en röststyrd agent med Speech Engine. Du konfigurerar en server som ansluter din LLM till ElevenLabs och kopplar sedan in en webbläsarklient så att användare kan ha röstkonversationer med din agent.

Använd ElevenLabs Speech Engine-skill för att lägga till röst i din chattagent:

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

Så fungerar Speech Engine

Speech Engine ansluter din LLM till ElevenLabs så att användare kan prata med din agent och höra den svara. ElevenLabs hanterar tal-till-text och text-till-tal; din server tillhandahåller LLM-logiken.

Varje WebSocket-anslutning representerar en konversation. När användaren pratar transkriberar ElevenLabs ljudet och skickar transkriberingen till din server. Din server skickar den till din LLM och strömmar sedan svaret tillbaka. ElevenLabs omvandlar texten till tal och spelar upp den i webbläsaren. SDK:t hanterar anslutningshantering, turordning och avbrottsidentifiering.

Förutsättningar

Den här handledningen använder OpenAI:s API för LLM:en. Du behöver en OpenAI API-nyckel som är inställd i miljövariabeln OPENAI_API_KEY.

Serverkonfiguration

1

Skapa en API-nyckel

Skapa en API-nyckel i dashboarden här, som du använder för att säkert få åtkomst till API:t.

Spara nyckeln som en hanterad hemlighet och skicka den till SDK:erna antingen som en miljövariabel via en .env-fil eller direkt i appens konfiguration, beroende på vad du föredrar.

.env
ELEVENLABS_API_KEY=<your_api_key_here>
2

Installera beroenden

pip install elevenlabs openai python-dotenv
3

Exponera servern

Speech Engine behöver en offentligt tillgänglig URL. Använd ngrok för att exponera din lokala server. Servern är inte byggd ännu, men ngrok måste köras först så att du har URL:en för nästa steg.

ngrok http 3001

Kopiera vidarebefordrings-URL:en (t.ex. https://abc123.ngrok.io).

4

Skapa en Speech Engine-instans

Använd SDK:t för att skapa en Speech Engine-instans och ange din ngrok-URL med sökvägen /ws tillagd som WebSocket-URL.

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())

Kör det här skriptet och kopiera Speech Engine-ID:t (t.ex. seng_8k3m9xr4hjnfg983brhmhkd98n6) till nästa steg.

5

Skapa servern

Skapa en fil med namnet server.py eller server.mts med följande innehåll. Detta konfigurerar en server, kopplar Speech Engine till sökvägen /ws och använder OpenAI för att generera svar.

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())

Callback-funktionen onTranscript / on_transcript tar emot hela konversationshistoriken och den aktuella sessionen. TypeScript SDK:t tillhandahåller även en AbortSignal som utlöses om användaren avbryter mitt i ett svar. Om du skickar signal till OpenAI-anropet avbryts LLM-begäran automatiskt vid avbrott.

sendResponse() / send_response() accepterar en sträng, en asynkron itererbar eller en stream från OpenAI, Anthropic eller Google Gemini. SDK:t extraherar textinnehållet automatiskt.

I exemplet ovan skickas hela transkriberingen från användaren till LLM:en. I en produktionsmiljö bör du lägga till skyddsåtgärder för att förhindra försök till promptinjektion eller manipulation.

6

Starta servern

python server.py

Klientkonfiguration

1

Installera klient-SDK:t

npm install @elevenlabs/react
2

Skapa en tokenändpunkt

Lägg till en serverändpunkt som genererar en konversationstoken. Då hålls din API-nyckel utanför webbläsaren och WebRTC används för bästa ljudkvalitet.

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

Bygg konversationsgränssnittet

Hämta konversationstoken från din server och använd den för att starta en session.

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

Prova

Kontrollera att tre processer körs:

  1. ngrok - vidarebefordrar till port 3001
  2. Din Speech Engine-server - python server.py eller npx tsx server.mts
  3. Tokenservern - npx tsx token-server.mts eller python token_server.py

Öppna din klientapplikation i webbläsaren och klicka på Starta konversation. Ge mikrofonåtkomst när du uppmanas och börja sedan prata. Du bör höra agentens svar via dina högtalare.

Om du har aktiverat debug: true på servern visas inkommande transkriberingar och utgående svar i konsolen.

Sessionshändelser

HändelseTypeScript-callbackPython-callbackBeskrivning
user_transcriptonTranscripton_transcriptAnvändartal transkriberat. Inkluderar full konversationshistorik och en avbrottssignal.
initonIniton_initSession initierad med ett konversations-ID.
closeonCloseon_closeRen frånkoppling från ElevenLabs.
disconnectedonDisconnecton_disconnectWebSocket kopplades ned oväntat.
erroronErroron_errorProtokoll- eller WebSocket-fel.

Konfigurera agentens första meddelande

Som standard väntar agenten på att användaren ska prata först. Om du vill att agenten ska hälsa användaren när konversationen startar anger du ett första meddelande i alternativet overrides på klienten när sessionen startas.

1

För att agenten ska kunna prata först måste vi uppdatera Speech Engine-resursen så att detta kan ställas in från klienten.

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

Sedan konfigurerar vi det första meddelandet i klient-SDK:t.

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

Det första meddelandet uttalas av agenten så snart anslutningen har upprättats. Det utlöser inte callback-funktionen onTranscript på din server – det hanteras helt på ElevenLabs sida.

Konfigurera maximal konversationslängd

Som standard avslutas en konversation efter 600 sekunder (10 minuter). Speech Engine stöder konversationer på upp till 7 200 sekunder (2 timmar). Om du vill tillåta längre konversationer uppdaterar du Speech Engine-resursen med ett högre max_duration_seconds:

engine = await elevenlabs.speech_engine.update(
speech_engine_id="seng_8k3m9xr4hjnfg983brhmhkd98n6",
conversation={
"max_duration_seconds": 7200,
},
)

Du kan också ställa in detta på kontrollpanelen: öppna din Speech Engine, gå till fliken Avancerat och ange Maximal konversationslängd under Konversationsbeteende.

Nästa steg