Hoppa till navigering
Handledningar

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 ihop en webbläsarklient så att användare kan föra röstsamtal 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, medan din server tillhandahåller LLM-logiken.

Varje WebSocket-anslutning representerar ett samtal. När användaren pratar transkriberar ElevenLabs ljudet och skickar transkriptionen till din server. Din server skickar den vidare till din LLM och strömmar sedan svaret tillbaka. ElevenLabs omvandlar texten till tal och spelar upp den i webbläsaren. SDK:t hanterar anslutningar, turordning och avbrottsdetektering.

Förutsättningar

Den här handledningen använder OpenAI:s API för LLM:en. Du behöver en OpenAI API-nyckel som anges 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 åtkomlig URL. Använd ngrok för att exponera din lokala server. Servern är inte byggd än, 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 skicka med 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. Den konfigurerar en server, ansluter Speech Engine på 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())

Återanropet onTranscript / on_transcript tar emot hela samtalshistoriken 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 ström från OpenAI, Anthropic eller Google Gemini. SDK:t extraherar textinnehållet automatiskt.

I exemplet ovan skickas användarens fullständiga transkription 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 manipulering.

6

Starta servern

python server.py

Klientkonfiguration

1

Installera klient-SDK:t

npm install @elevenlabs/react
2

Skapa en tokenslutpunkt

Lägg till en slutpunkt på serversidan som genererar en samtalstoken. Det håller din API-nyckel borta från webbläsaren och använder WebRTC 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 samtalsgränssnittet

Hämta samtalstoken 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 det

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 klientapplikationen i webbläsaren och klicka på Starta samtal. Ge åtkomst till mikrofonen när du uppmanas till det och börja sedan prata. Du bör höra agenten svara via dina högtalare.

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

Sessionshändelser

HändelseTypeScript-återanropPython-återanropBeskrivning
user_transcriptonTranscripton_transcriptAnvändarens tal har transkriberats. Inkluderar hela samtalshistoriken och en avbrottssignal.
initonIniton_initSessionen har initierats med ett samtals-ID.
closeonCloseon_closeRen frånkoppling från ElevenLabs.
disconnectedonDisconnecton_disconnectWebSocket-anslutningen bröts 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 på användaren när samtalet startar anger du ett första meddelande i alternativet overrides på klienten när du startar sessionen.

1

För att låta agenten prata först behöver vi uppdatera Speech Engine-resursen så att detta kan anges 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 återanropet onTranscript på din server – det hanteras helt på ElevenLabs sida.

Konfigurera maximal samtalslängd

Som standard avslutas ett samtal efter 600 sekunder (10 minuter). Speech Engine har stöd för samtal på upp till 2 400 sekunder (40 minuter). Om du vill tillåta längre samtal 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": 2400,
    },
)

Du kan även ange detta i kontrollpanelen: öppna din Speech Engine, gå till fliken Avancerat och ange Maximal samtalslängd under Samtalsbeteende.

Samtal som är längre än 40 minuter stöds inte och kan kopplas från, även om max_duration_seconds är inställt på ett högre värde. Om du behöver längre samtal kan du kontakta vårt team.

Nästa steg

JavaScript SDK-referens

Klasser, metoder och händelser för JavaScript SDK:t.

Python SDK-referens

Klasser, metoder och händelser för Python SDK:t.

API-referens

Utforska alla parametrar och svarsformat för Speech Engine.

Exempelapp för Next.js

Kör en komplett snabbstartsapp för Speech Engine lokalt.