Speech Engine Quickstart

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 zuerst laufen, damit Sie die URL für den nächsten Schritt haben.

ngrok http 3001

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

Speech-Engine-Instanz erstellen

Erstellen Sie mit dem SDK eine Speech-Engine-Instanz. Ü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, beispielsweise seng_8k3m9xr4hjnfg983brhmhkd98n6, für den nächsten Schritt.

Server erstellen

Erstellen Sie eine Datei namens server.py oder server.mts mit folgendem Inhalt. Damit richten Sie einen Server ein, binden Speech Engine unter dem Pfad /ws an und verwenden OpenAI zum Generieren von Antworten.

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 erhält 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 eine 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 Unterhaltungstoken generiert. So bleibt Ihr API-Schlüssel außerhalb des Browsers, und Sie nutzen WebRTC 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)

Unterhaltungs-UI erstellen

Rufen Sie das Unterhaltungstoken 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 Unterhaltung starten. Erteilen Sie bei Aufforderung Mikrofonzugriff und sprechen Sie dann. Sie sollten den Agenten über Ihre Lautsprecher antworten hören.

Wenn Sie debug: true auf dem Server aktiviert haben, werden eingehende Transkripte und ausgehende Antworten in der Konsole protokolliert.

Damit der Agent zuerst sprechen kann, müssen wir die Speech-Engine-Ressource aktualisieren, damit dies vom Client festgelegt werden kann.

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

Konfigurieren Sie dann die erste Nachricht im Client-SDK.

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