Snelstartgids voor Speech Engine

Een API-sleutel maken

Maak hier een API-sleutel in het dashboard, die je gebruikt voor veilige toegang tot de API.

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

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 draaien zodat je de URL voor de volgende stap hebt.

ngrok http 3001

Kopieer de doorstuur-URL (bijv. https://abc123.ngrok.io).

Een Speech Engine-instance maken

Gebruik de SDK om een Speech Engine-instance 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 (bijv. 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 conversatiegeschiedenis en de huidige sessie. De TypeScript SDK biedt ook een AbortSignal dat wordt geactiveerd als de gebruiker midden in een antwoord onderbreekt. Door signal door te geven aan de OpenAI-aanroep, wordt de LLM-request bij 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 tekstcontent automatisch op.

De server starten

python server.py

De client SDK installeren

npm install @elevenlabs/react

Een tokenendpoint maken

Voeg een endpoint aan de serverkant toe dat een conversatietoken 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 conversatie-UI bouwen

Haal het conversatietoken op van je server en gebruik het om een sessie te 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>
  );
}

Probeer het

Zorg dat er drie processen draaien:

1. ngrok - stuurt door naar poort 3001
2. Je Speech Engine-server - python server.py of npx tsx server.mts
3. 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 de microfoon wanneer daarom wordt gevraagd en begin vervolgens te praten. Je hoort de agent via je speakers antwoorden.

Als je debug: true op de server hebt ingeschakeld, zie je inkomende transcripties en uitgaande antwoorden in de console.

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.

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