Speech Engine-snelstart | ElevenLabs Documentation

In deze handleiding bouw je een spraakgestuurde agent met Speech Engine. Je zet een server op die je LLM met ElevenLabs verbindt en koppelt vervolgens een browserclient, zodat gebruikers spraakgesprekken met je agent kunnen voeren.

Gebruik de ElevenLabs Speech Engine-skill om spraak aan je chatagent toe te voegen:

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

Hoe Speech Engine werkt

Speech Engine verbindt je LLM met ElevenLabs, zodat gebruikers met je agent kunnen praten en het antwoord kunnen horen. ElevenLabs verzorgt spraak-naar-tekst en tekst-naar-spraak; je server levert de LLM-logica.

Elke WebSocket-verbinding vertegenwoordigt één gesprek. Wanneer de gebruiker spreekt, transcribeert ElevenLabs de audio en stuurt het transcript naar je server. Je server geeft dit door aan je LLM en streamt vervolgens het antwoord terug. ElevenLabs zet de tekst om in spraak en speelt deze af in de browser. De SDK verwerkt verbindingsbeheer, beurtwisseling en detectie van onderbrekingen.

Vereisten

Deze tutorial gebruikt de API van OpenAI voor de LLM. Je hebt een OpenAI API-sleutel nodig die is ingesteld in de omgevingsvariabele OPENAI_API_KEY.

Server instellen

Een API-sleutel maken

Maak hier een API-sleutel in het dashboard, die je gebruikt om veilig toegang te krijgen tot de API.

Sla de sleutel op als een beheerd geheim en geef deze aan de SDK’s door, naar keuze als omgevingsvariabele via een .env-bestand of rechtstreeks in de configuratie van je app.

.env

ELEVENLABS_API_KEY=<your_api_key_here>

Afhankelijkheden installeren

pip install elevenlabs openai python-dotenv

De server beschikbaar maken

Speech Engine heeft een openbaar bereikbare URL nodig. Gebruik ngrok om je lokale server beschikbaar te maken. De server is nog niet gebouwd, maar ngrok moet eerst actief zijn zodat je de URL voor de volgende stap hebt.

ngrok http 3001

Kopieer de forwarding-URL (bijvoorbeeld https://abc123.ngrok.io).

Een Speech Engine-instantie maken

Gebruik de SDK om een Speech Engine-instantie te maken en geef je ngrok-URL met het toegevoegde pad /ws door als 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())

Voer dit script uit en kopieer de Speech Engine-ID (bijvoorbeeld seng_8k3m9xr4hjnfg983brhmhkd98n6) voor de volgende stap.

De server maken

Maak een bestand met de naam server.py of server.mts met de volgende inhoud. Hiermee stel je een server in, koppel je Speech Engine aan het pad /ws en gebruik je OpenAI om antwoorden te genereren.

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

De callback onTranscript / on_transcript ontvangt de volledige gespreksgeschiedenis en de huidige sessie. De TypeScript SDK biedt ook een AbortSignal die wordt geactiveerd als de gebruiker tijdens een antwoord onderbreekt. Door signal door te geven aan de OpenAI-call wordt de LLM-request bij een onderbreking automatisch geannuleerd.

sendResponse() / send_response() accepteert een string, een async iterable of een stream van OpenAI, Anthropic of Google Gemini. De SDK haalt de tekstinhoud automatisch op.

In het bovenstaande voorbeeld wordt het volledige transcript van de gebruiker doorgegeven aan de LLM. Voeg in een productieomgeving guardrails toe om pogingen tot prompt injection of manipulatie te voorkomen.

De server starten

python server.py

Client instellen

De client-SDK installeren

React

JavaScript

npm install @elevenlabs/react

Een tokenendpoint maken

Voeg een endpoint aan de serverzijde toe dat een gesprekstoken genereert. Zo blijft je API-sleutel uit de browser en gebruik je WebRTC voor de beste audiokwaliteit.

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)

De gespreks-UI bouwen

Haal het gesprekstoken op van je server en gebruik het om een sessie te starten.

React

JavaScript

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>
  );
}

Probeer het

Zorg dat er drie processen actief zijn:

ngrok - forwarding naar poort 3001
Je Speech Engine-server - python server.py of npx tsx server.mts
De tokenserver - npx tsx token-server.mts of python token_server.py

Open je clientapplicatie in de browser en klik op Gesprek starten. Geef toegang tot je microfoon wanneer daarom wordt gevraagd en spreek vervolgens. Je hoort de agent via je speakers antwoorden.

Als je debug: true op de server hebt ingeschakeld, zie je binnenkomende transcripts en uitgaande antwoorden in de console gelogd.

Sessie-events

Event	TypeScript-callback	Python-callback	Beschrijving
`user_transcript`	`onTranscript`	`on_transcript`	Spraak van gebruiker getranscribeerd. Bevat volledige gespreksgeschiedenis en een abortsignaal.
`init`	`onInit`	`on_init`	Sessie geïnitialiseerd met een gespreks-ID.
`close`	`onClose`	`on_close`	Verbinding met ElevenLabs netjes gesloten.
`disconnected`	`onDisconnect`	`on_disconnect`	WebSocket onverwacht verbroken.
`error`	`onError`	`on_error`	Protocol- of WebSocket-fout.

Het eerste bericht van de agent configureren

Standaard wacht de agent tot de gebruiker als eerste spreekt. Als je wilt dat de agent de gebruiker begroet wanneer het gesprek begint, stel je bij het starten van de sessie een eerste bericht in via de optie overrides op de client.

Om de agent als eerste te laten spreken, moeten we de Speech Engine-resource bijwerken zodat dit vanuit de client kan worden ingesteld.

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

Vervolgens configureren we het eerste bericht in de client-SDK.

React

JavaScript

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

Het eerste bericht wordt door de agent uitgesproken zodra de verbinding tot stand is gebracht. Het activeert niet de callback onTranscript op je server: het wordt volledig aan de kant van ElevenLabs afgehandeld.

De maximale gespreksduur configureren

Standaard eindigt een gesprek na 600 seconden (10 minuten). Speech Engine ondersteunt gesprekken van maximaal 7.200 seconden (2 uur). Werk de Speech Engine-resource bij met een hogere max_duration_seconds om langere gesprekken toe te staan:

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

Je kunt dit ook instellen in het dashboard: open je Speech Engine, ga naar het tabblad Geavanceerd en stel Maximale gespreksduur in onder Gespreksgedrag.

Volgende stappen

JavaScript SDK-referentie

Klassen, methoden en events voor de JavaScript SDK.

Python SDK-referentie

Klassen, methoden en events voor de Python SDK.

API-referentie

Bekijk alle Speech Engine-parameters en responseformaten.

Next.js-voorbeeldapp

Voer lokaal een volledige Speech Engine-snelstartapp uit.