नेविगेशन पर जाएँ

स्पीच इंजन क्विकस्टार्ट

ElevenLabs SDK का इस्तेमाल करके अपने चैट एजेंट में वॉइस जोड़ें।

इस गाइड में बताया गया है कि स्पीच इंजन के साथ वॉइस-सक्षम एजेंट कैसे बनाएं। आप एक सर्वर सेट अप करेंगे जो आपके LLM को ElevenLabs से कनेक्ट करता है, फिर एक ब्राउज़र क्लाइंट जोड़ेंगे ताकि यूज़र आपके एजेंट के साथ वॉइस बातचीत कर सकें।

अपने चैट एजेंट में वॉइस जोड़ने के लिए ElevenLabs स्पीच इंजन स्किल का इस्तेमाल करें:

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

स्पीच इंजन कैसे काम करता है

स्पीच इंजन आपके LLM को ElevenLabs से कनेक्ट करता है, ताकि यूज़र आपके एजेंट से बात कर सकें और उसका जवाब सुन सकें। ElevenLabs स्पीच-टू-टेक्स्ट और टेक्स्ट-टू-स्पीच संभालता है; आपका सर्वर LLM लॉजिक देता है।

हर WebSocket कनेक्शन एक बातचीत को दर्शाता है। जब यूज़र बोलता है, ElevenLabs ऑडियो को ट्रांसक्राइब करके ट्रांसक्रिप्ट आपके सर्वर को भेजता है। आपका सर्वर इसे आपके LLM को भेजता है, फिर जवाब को वापस स्ट्रीम करता है। ElevenLabs टेक्स्ट को स्पीच में बदलता है और उसे ब्राउज़र में चलाता है। SDK कनेक्शन मैनेजमेंट, बारी-बारी से बोलना और इंटरप्शन डिटेक्शन संभालता है।

ज़रूरी शर्तें

इस ट्यूटोरियल में LLM के लिए OpenAI का API इस्तेमाल होता है। आपके पास OPENAI_API_KEY एनवायरनमेंट वेरिएबल में सेट की हुई OpenAI API कुंजी होनी चाहिए।

सर्वर सेटअप

1

API कुंजी बनाएं

डैशबोर्ड में यहां API key बनाएं, जिसका इस्तेमाल आप API एक्सेस करने के लिए सुरक्षित रूप से करेंगे।

key को मैनेज्ड सीक्रेट के रूप में स्टोर करें और अपनी पसंद के अनुसार इसे SDKs को .env फ़ाइल के ज़रिए एनवायरनमेंट वेरिएबल के रूप में या सीधे अपने ऐप के कॉन्फ़िगरेशन में पास करें।

.env
ELEVENLABS_API_KEY=<your_api_key_here>
2

डिपेंडेंसी इंस्टॉल करें

pip install elevenlabs openai python-dotenv
3

सर्वर एक्सपोज़ करें

स्पीच इंजन को सार्वजनिक रूप से उपलब्ध URL चाहिए। अपने लोकल सर्वर को एक्सपोज़ करने के लिए ngrok का इस्तेमाल करें। सर्वर अभी बना नहीं है, लेकिन ngrok को पहले चलाना ज़रूरी है ताकि अगले चरण के लिए आपके पास URL हो।

ngrok http 3001

फॉरवर्डिंग URL कॉपी करें (जैसे https://abc123.ngrok.io)।

4

स्पीच इंजन इंस्टेंस बनाएं

SDK का इस्तेमाल करके स्पीच इंजन इंस्टेंस बनाएं। WebSocket URL के रूप में अपने ngrok URL में /ws पाथ जोड़कर दें।

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

इस स्क्रिप्ट को चलाएं और अगले चरण के लिए स्पीच इंजन ID कॉपी करें (जैसे seng_8k3m9xr4hjnfg983brhmhkd98n6)।

5

सर्वर बनाएं

server.py या server.mts नाम की फ़ाइल बनाएं और उसमें नीचे दिया गया कंटेंट डालें। यह एक सर्वर सेट अप करता है, /ws पाथ पर स्पीच इंजन अटैच करता है और जवाब बनाने के लिए OpenAI का इस्तेमाल करता है।

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

onTranscript / on_transcript कॉलबैक को बातचीत का पूरा इतिहास और मौजूदा सेशन मिलता है। TypeScript SDK एक AbortSignal भी देता है, जो यूज़र के जवाब के बीच में इंटरप्ट करने पर ट्रिगर होता है। OpenAI कॉल में signal पास करने से इंटरप्शन होने पर LLM रिक्वेस्ट अपने-आप रद्द हो जाती है।

sendResponse() / send_response() एक स्ट्रिंग, async iterable या OpenAI, Anthropic या Google Gemini की स्ट्रीम स्वीकार करता है। SDK टेक्स्ट कंटेंट को अपने-आप एक्सट्रैक्ट कर लेता है।

ऊपर दिए गए उदाहरण में, यूज़र का पूरा ट्रांसक्रिप्ट LLM को भेजा जाता है। प्रोडक्शन एनवायरनमेंट में आपको किसी भी प्रॉम्प्ट इंजेक्शन या मैनिपुलेशन की कोशिश को रोकने के लिए गार्डरेल्स जोड़ने चाहिए।

6

सर्वर शुरू करें

python server.py

क्लाइंट सेटअप

1

क्लाइंट SDK इंस्टॉल करें

npm install @elevenlabs/react
2

टोकन एंडपॉइंट बनाएं

ऐसा सर्वर-साइड एंडपॉइंट जोड़ें जो बातचीत का टोकन जनरेट करता हो। इससे आपकी API कुंजी ब्राउज़र से बाहर रहती है और बेहतरीन ऑडियो क्वालिटी के लिए WebRTC इस्तेमाल होता है।

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

बातचीत का UI बनाएं

अपने सर्वर से बातचीत का टोकन फ़ेच करें और उससे सेशन शुरू करें।

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

इसे आज़माएं

पक्का करें कि ये तीन प्रोसेस चल रहे हों:

  1. ngrok - पोर्ट 3001 पर फॉरवर्ड कर रहा हो
  2. आपका स्पीच इंजन सर्वर - python server.py या npx tsx server.mts
  3. टोकन सर्वर - npx tsx token-server.mts या python token_server.py

अपनी क्लाइंट एप्लिकेशन को ब्राउज़र में खोलें और बातचीत शुरू करें पर क्लिक करें। प्रॉम्प्ट आने पर माइक्रोफ़ोन एक्सेस दें, फिर बोलें। आपको एजेंट का जवाब अपने स्पीकर्स से सुनाई देना चाहिए।

अगर सर्वर पर debug: true सक्षम है, तो आपको कंसोल में आने वाले ट्रांसक्रिप्ट और भेजे जाने वाले जवाब लॉग होते दिखेंगे।

सेशन इवेंट्स

इवेंटTypeScript कॉलबैकPython कॉलबैकविवरण
user_transcriptonTranscripton_transcriptयूज़र की स्पीच ट्रांसक्राइब हुई। इसमें बातचीत का पूरा इतिहास और abort signal शामिल है।
initonIniton_initबातचीत ID के साथ सेशन शुरू हुआ।
closeonCloseon_closeElevenLabs से कनेक्शन सही तरीके से बंद हुआ।
disconnectedonDisconnecton_disconnectWebSocket अनपेक्षित रूप से डिस्कनेक्ट हुआ।
erroronErroron_errorप्रोटोकॉल या WebSocket एरर।

एजेंट के पहले संदेश को कॉन्फ़िगर करना

डिफ़ॉल्ट रूप से एजेंट यूज़र के पहले बोलने का इंतज़ार करता है। बातचीत शुरू होने पर एजेंट से यूज़र का अभिवादन करवाने के लिए, सेशन शुरू करते समय क्लाइंट के overrides विकल्प में पहला संदेश सेट करें।

1

एजेंट को पहले बोलने देने के लिए, हमें क्लाइंट से यह सेट करने की अनुमति देने हेतु स्पीच इंजन रिसोर्स अपडेट करना होगा।

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

फिर हम क्लाइंट SDK में पहला संदेश कॉन्फ़िगर करेंगे।

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

कनेक्शन बनते ही एजेंट पहला संदेश बोलता है। इससे आपके सर्वर पर onTranscript कॉलबैक ट्रिगर नहीं होता—इसे पूरी तरह ElevenLabs की ओर से संभाला जाता है।

बातचीत की अधिकतम अवधि कॉन्फ़िगर करना

डिफ़ॉल्ट रूप से, बातचीत 600 सेकंड (10 मिनट) बाद खत्म हो जाती है। स्पीच इंजन 2,400 सेकंड (40 मिनट) तक की बातचीत सपोर्ट करता है। लंबी बातचीत की अनुमति देने के लिए, स्पीच इंजन रिसोर्स में ज़्यादा max_duration_seconds सेट करें:

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

आप इसे डैशबोर्ड में भी सेट कर सकते हैं: अपना स्पीच इंजन खोलें, Advanced टैब पर जाएं और Conversational behavior में Max conversation duration सेट करें।

40 मिनट से लंबी बातचीत सपोर्ट नहीं की जाती और डिस्कनेक्ट हो सकती है, भले ही max_duration_seconds को इससे ज़्यादा वैल्यू पर सेट किया गया हो। अगर आपको लंबी बातचीत चाहिए, तो हमारी टीम से संपर्क करें।

अगले चरण