रेफरेंसलाइब्रेरीज़ और SDKsस्पीच इंजन

Python SDK रेफ़रेंस

Speech Engine Python SDK के लिए क्लास, तरीके और इवेंट्स।

यह पेज Speech Engine Python SDK (elevenlabs) के सार्वजनिक API का दस्तावेज़ है।

Speech Engine रिसोर्स पाना

इंजन ID से SpeechEngineResource पाएं। रिटर्न किया गया ऑब्जेक्ट सर्वर शुरू करने, अनुरोधों को सत्यापित करने या अलग-अलग सेशन बनाने के तरीके देता है।

from elevenlabs import AsyncElevenLabs
elevenlabs = AsyncElevenLabs()
engine = await elevenlabs.speech_engine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6")

SpeechEngineResource

प्रॉपर्टीज़

प्रॉपर्टीटाइपविवरण
engine_idstrस्पीच इंजन की ID।

serve

एक स्टैंडअलोन WebSocket सर्वर शुरू करें। रुकने तक ब्लॉक करता है।

await engine.serve(
    port=3001,
    path="/ws",
    debug=True,
    on_transcript=handle_transcript,
)
पैरामीटरटाइपडिफ़ॉल्टविवरण
portint3001सुनने के लिए पोर्ट।
pathstrNoneकनेक्शन को इस पाथ तक सीमित करें। None सभी को स्वीकार करता है।
debugboolFalsestdout पर डीबग लॉगिंग चालू करें।
disable_authboolFalseआने वाले कनेक्शन पर JWT सत्यापन छोड़ें। ऑथेंटिकेशन बंद करना देखें।
on_initcallableसेशन शुरू होने पर कॉल होता है।
on_transcriptcallableयूज़र ट्रांसक्रिप्ट आने पर कॉल होता है।
on_closecallableकनेक्शन सही तरीके से बंद होने पर कॉल होता है।
on_disconnectcallableWebSocket के अनपेक्षित रूप से डिस्कनेक्ट होने पर कॉल होता है।
on_errorcallableप्रोटोकॉल या WebSocket त्रुटियों पर कॉल होता है।

ऑथेंटिकेशन बंद करना

डिफ़ॉल्ट रूप से serve() हर आने वाले कनेक्शन पर X-Elevenlabs-Speech-Engine-Authorization हेडर सत्यापित करता है। अगर आपका सर्वर ऐसी इन्फ्रास्ट्रक्चर लेयर के पीछे है जो पहले से आने वाले ट्रैफ़िक को ElevenLabs तक सीमित करती है (आमतौर पर ElevenLabs की egress रेंज तक सीमित IP allowlist), तो disable_auth=True देकर JWT सत्यापन छोड़ सकते हैं:

# No api_key required when disable_auth is True
await engine.serve(port=3001, disable_auth=True, on_transcript=on_transcript)
# Or directly on SpeechEngineServer
from elevenlabs.speech_engine import SpeechEngineServer
server = SpeechEngineServer(port=3001, disable_auth=True, on_transcript=on_transcript)
await server.serve()

ऑथ बंद होने पर सर्वर तक पहुंच सकने वाला कोई भी क्लाइंट स्वीकार किया जाता है और शुरू होने पर UserWarning जारी होता है।

disable_auth=True का इस्तेमाल केवल तब करें जब सर्वर के सामने IP allowlist, कस्टम हेडर वैल्यू या नेटवर्क स्तर की ऐसी ही कोई पाबंदी हो। इनके बिना, इंटरनेट पर कोई भी व्यक्ति सेशन खोल सकता है और आपका कंप्यूट तथा डाउनस्ट्रीम LLM कोटा इस्तेमाल कर सकता है।

verify_request

सत्यापित करें कि आने वाला अनुरोध ElevenLabs Speech Engine API से आया है। आपके API key के SHA-256 हैश से साइन किए गए वैध JWT के लिए X-Elevenlabs-Speech-Engine-Authorization हेडर जांचता है।

इसकी ज़रूरत केवल तब है जब आप WebSocket अपग्रेड खुद मैनेज करते हैं। serve() इस्तेमाल करने पर सत्यापन अपने-आप हो जाता है (disable_auth=True सेट होने के अलावा)।

is_valid = engine.verify_request(headers)
पैरामीटरटाइपविवरण
headersdictअनुरोध हेडर डिक्शनरी।

रिटर्न: bool — अनुरोध वैध होने पर True।

create_session

स्वीकार किए गए WebSocket को SpeechEngineSession में रैप करें। कस्टम सर्वर इंटीग्रेशन (जैसे FastAPI, Starlette या मैन्युअल WebSocket हैंडलिंग) के लिए इसका इस्तेमाल करें।

session = engine.create_session(websocket, debug=True)
session.on("user_transcript", handle_transcript)
await session.run()
पैरामीटरटाइपडिफ़ॉल्टविवरण
wsWebSocketस्वीकार किया गया WebSocket कनेक्शन।
debugboolFalseडीबग लॉगिंग चालू करें।

रिटर्न: SpeechEngineSession

SpeechEngineSession

एक WebSocket कनेक्शन को रैप करता है। हर कनेक्शन एक बातचीत दर्शाता है। सेशन ट्रांसक्रिप्ट और लाइफ़साइकल बदलावों के लिए इवेंट जारी करता है और LLM रिस्पॉन्स वापस भेजने के तरीके देता है।

नया ट्रांसक्रिप्ट आने पर, पिछले ट्रांसक्रिप्ट हैंडलर को अपने-आप रद्द कर दिया जाता है, जिससे चल रही LLM कॉल बाधित हो जाती है।

प्रॉपर्टीज़

प्रॉपर्टीटाइपविवरण
conversation_idOptional[str]API द्वारा असाइन की गई बातचीत ID। init के बाद उपलब्ध।
is_openboolसेशन अभी भी खुला है या नहीं।

on

किसी इवेंट के लिए हैंडलर रजिस्टर करें। चेनिंग के लिए सेशन रिटर्न करता है।

session.on("user_transcript", handler)

off

पहले रजिस्टर किया गया हैंडलर हटाएं।

session.off("user_transcript", handler)

once

ऐसा हैंडलर रजिस्टर करें जो एक बार चले और फिर खुद को हटा दे।

session.once("init", handler)

send_response

टेक्स्ट-टू-स्पीच सिंथेसिस के लिए Speech Engine API को LLM रिस्पॉन्स वापस भेजें। इसे on_transcript हैंडलर के अंदर कॉल करना ज़रूरी है। हैंडलर के बाहर कॉल करने पर चेतावनी जारी होती है और बिना भेजे रिटर्न हो जाता है।

# String response
await session.send_response("Hello, how can I help?")
# Streamed response (OpenAI, Anthropic, or Gemini)
stream = await openai_client.responses.create(model="gpt-4o", input=messages, stream=True)
await session.send_response(stream)
पैरामीटरटाइपविवरण
responsestr | async iterableपूरी स्ट्रिंग या टेक्स्ट चंक्स / LLM स्ट्रीम इवेंट का async iterable।

SDK नीचे दिए गए LLM स्ट्रीम फ़ॉर्मैट से टेक्स्ट को अपने-आप पहचानकर निकालता है:

प्रोवाइडरइवेंट फ़ॉर्मैट
OpenAI Responses API{ type: "response.output_text.delta", delta: "text" }
OpenAI Chat Completions{ choices: [{ delta: { content: "text" } }] }
Anthropic Messages API{ type: "content_block_delta", delta: { type: "text_delta", text: "text" } }
Google Gemini API{ candidates: [{ content: { parts: [{ text: "text" }] } }] }

run

WebSocket बंद होने तक रिसीव लूप चलाएं। create_session() से मैन्युअल रूप से सेशन बनाने के बाद यही मुख्य एंट्री पॉइंट है।

session = engine.create_session(websocket)
session.on("user_transcript", handle_transcript)
await session.run()

close

सेशन और उसके WebSocket कनेक्शन को बंद करें।

session.close()

कॉलबैक

serve() को दिए गए keyword arguments। सभी कॉलबैक वैकल्पिक हैं। हैंडलर सिंक्रोनस या एसिंक्रोनस (coroutine) फ़ंक्शन हो सकते हैं।

कॉलबैकसिग्नेचरविवरण
on_init(conversation_id: str, session) -> Noneबातचीत ID के साथ सेशन शुरू हुआ।
on_transcript(transcript: list, session) -> Noneयूज़र की स्पीच ट्रांसक्राइब हुई।
on_close(session) -> NoneElevenLabs से सही तरीके से डिस्कनेक्ट हुआ।
on_disconnect(session) -> NoneWebSocket अनपेक्षित रूप से डिस्कनेक्ट हुआ।
on_error(error: Exception, session) -> Noneप्रोटोकॉल या WebSocket त्रुटि।

इवेंट्स

कॉलबैक की जगह सीधे session.on() इस्तेमाल करने पर, ये इवेंट नाम और उनके हैंडलर सिग्नेचर हैं।

इवेंटहैंडलर सिग्नेचर
user_transcript(transcript: list[ConversationMessage])
init(conversation_id: str)
close()
disconnected()
error(error: Exception)

टाइप-सुरक्षित इस्तेमाल के लिए इवेंट नाम कॉन्स्टेंट उपलब्ध हैं:

from elevenlabs.speech_engine import USER_TRANSCRIPT, INIT, CLOSE, DISCONNECTED, ERROR
session.on(USER_TRANSCRIPT, handle_transcript)

ConversationMessage

बातचीत के इतिहास में एक संदेश। हर टर्न पर पूरा ट्रांसक्रिप्ट on_transcript को दिया जाता है।

प्रॉपर्टीटाइपविवरण
role"user" | "agent"संदेश किसने भेजा।
contentstrसंदेश का टेक्स्ट कॉन्टेंट।

वायर प्रोटोकॉल

रेफ़रेंस के लिए, ये WebSocket कनेक्शन पर एक्सचेंज होने वाले JSON संदेश हैं। SDK सीरियलाइज़ेशन और डिसीरियलाइज़ेशन अपने-आप संभालता है।

इनकमिंग (ElevenLabs API से डेवलपर सर्वर)

संदेश टाइपफ़ील्ड्सविवरण
initconversation_id: stringसेशन शुरू हुआ।
user_transcriptuser_transcript: TranscriptMessage[], event_id: numberयूज़र की स्पीच ट्रांसक्राइब हुई।
pingकनेक्शन सक्रिय रखने के लिए। SDK pong से जवाब देता है।
closeसही तरीके से डिस्कनेक्ट।
errormessage: stringAPI से त्रुटि।

आउटगोइंग (डेवलपर सर्वर से ElevenLabs API)

संदेश टाइपफ़ील्ड्सविवरण
agent_responsecontent: string, event_id: number, is_final: booleanTTS सिंथेसिस के लिए LLM रिस्पॉन्स चंक।
pongping का जवाब।