Speech Engine – Schnellstart

API-Schlüssel erstellen

Erstellen Sie hier im Dashboard einen API-Schlüssel, den Sie für den sicheren Zugriff auf die API verwenden.

Speichern Sie den Schlüssel als verwaltetes Secret und übergeben Sie ihn je nach Präferenz an die SDKs entweder als Umgebungsvariable über eine .env-Datei oder direkt in der Konfiguration Ihrer App.

ELEVENLABS_API_KEY=<your_api_key_here>

Abhängigkeiten installieren

pip install elevenlabs openai python-dotenv

Server öffentlich erreichbar machen

Speech Engine benötigt eine öffentlich erreichbare URL. Verwenden Sie ngrok, um Ihren lokalen Server öffentlich erreichbar zu machen. Der Server ist noch nicht erstellt, aber ngrok muss bereits laufen, damit Sie die URL für den nächsten Schritt haben.

ngrok http 3001

Kopieren Sie die Weiterleitungs-URL, z. B. https://abc123.ngrok.io.

Speech-Engine-Instanz erstellen

Verwenden Sie das SDK, um eine Speech-Engine-Instanz zu erstellen. Übergeben Sie dabei Ihre ngrok-URL mit angehängtem Pfad /ws 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())

Führen Sie dieses Skript aus und kopieren Sie die Speech-Engine-ID, z. B. seng_8k3m9xr4hjnfg983brhmhkd98n6, für den nächsten Schritt.

Server erstellen

Erstellen Sie eine Datei namens server.py oder server.mts mit folgendem Inhalt. Dadurch wird ein Server eingerichtet, Speech Engine an den Pfad /ws angebunden und OpenAI zum Generieren von Antworten verwendet.

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

Der Callback onTranscript / on_transcript empfängt den vollständigen Gesprächsverlauf und die aktuelle Sitzung. Das TypeScript SDK stellt außerdem ein AbortSignal bereit, das ausgelöst wird, wenn der Nutzer die Antwort unterbricht. Wenn Sie signal an den OpenAI-Aufruf übergeben, wird die LLM-Anfrage bei einer Unterbrechung automatisch abgebrochen.

sendResponse() / send_response() akzeptiert einen String, ein asynchrones Iterable oder einen Stream von OpenAI, Anthropic oder Google Gemini. Das SDK extrahiert den Textinhalt automatisch.

Server starten

python server.py

Client-SDK installieren

npm install @elevenlabs/react

Token-Endpunkt erstellen

Fügen Sie einen serverseitigen Endpunkt hinzu, der ein Gesprächs-Token generiert. So bleibt Ihr API-Schlüssel außerhalb des Browsers, und WebRTC sorgt für die beste Audioqualität.

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)

Gesprächs-UI erstellen

Rufen Sie das Gesprächs-Token von Ihrem Server ab und verwenden Sie es, um eine Sitzung zu starten.

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

Ausprobieren

Stellen Sie sicher, dass drei Prozesse laufen:

1. ngrok – Weiterleitung an Port 3001
2. Ihr Speech-Engine-Server – python server.py oder npx tsx server.mts
3. Der Token-Server – npx tsx token-server.mts oder python token_server.py

Öffnen Sie Ihre Client-Anwendung im Browser und klicken Sie auf Gespräch starten. Erteilen Sie bei Aufforderung Mikrofonzugriff und sprechen Sie dann. Sie sollten die Antwort des Agenten über Ihre Lautsprecher hören.

Wenn auf dem Server debug: true aktiviert ist, sehen Sie eingehende Transkripte und ausgehende Antworten in der Konsole.

Damit der Agent zuerst sprechen kann, müssen wir die Speech-Engine-Ressource aktualisieren, um diese Einstellung vom Client aus zuzulassen.

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

Anschließend konfigurieren wir die erste Nachricht im Client SDK.

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