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

JavaScript SDK रेफरेंस

स्पीच इंजन JavaScript SDK के लिए क्लासेस, मेथड्स और इवेंट्स।

यह पेज स्पीच इंजन JavaScript SDK (@elevenlabs/elevenlabs-js) के पब्लिक API की जानकारी देता है।

स्पीच इंजन रिसोर्स पाना

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

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const elevenlabs = new ElevenLabsClient();
const engine = await elevenlabs.speechEngine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6");

SpeechEngineResource

प्रॉपर्टीज़

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

attach

किसी मौजूदा Node.js HTTP सर्वर से जुड़ें और दिए गए पाथ पर स्पीच इंजन कनेक्शन स्वीकार करना शुरू करें। इसका इस्तेमाल तब करें जब आपके पास पहले से HTTP सर्वर हो (जैसे Express, Fastify या सामान्य http.createServer()), और आप अपने मौजूदा रूट्स के साथ स्पीच इंजन जोड़ना चाहते हों।

WebSocket अपग्रेड्स, पाथ रूटिंग और रिक्वेस्ट वेरिफ़िकेशन को अपने-आप हैंडल करता है। SpeechEngineAttachment लौटाता है, जिसका close() मेथड HTTP सर्वर को प्रभावित किए बिना कनेक्शन स्वीकार करना बंद कर देता है।

const attachment = engine.attach(httpServer, "/ws", {
  debug: true,
  onTranscript(transcript, signal, session) {
    session.sendResponse(stream);
  },
});
पैरामीटरटाइपविवरण
httpServerhttp.Serverइससे जुड़ने वाला Node.js HTTP सर्वर।
pathstringवह URL पाथ जिस पर WebSocket अपग्रेड्स हैंडल करने हैं।
handlerSpeechEngineCallbacksकॉलबैक ऑब्जेक्ट (कॉलबैक्स देखें)।

क्लाइंट पर सीधे एक शॉर्टकट उपलब्ध है, जो get() और attach() को एक ही कॉल में जोड़ता है:

await elevenlabs.speechEngine.attach("seng_8k3m9xr4hjnfg983brhmhkd98n6", httpServer, "/ws", {
  onTranscript(transcript, signal, session) {
    session.sendResponse(stream);
  },
});

verifyRequest

वेरिफ़ाई करें कि आने वाली रिक्वेस्ट ElevenLabs स्पीच इंजन API से आई है। आपके API की के SHA-256 हैश से साइन किए गए वैध JWT के लिए X-Elevenlabs-Speech-Engine-Authorization हेडर जाँचता है।

इसकी ज़रूरत सिर्फ़ तब होती है जब आप WebSocket अपग्रेड खुद मैनेज कर रहे हों। attach() या SpeechEngineServer इस्तेमाल करने पर वेरिफ़िकेशन अपने-आप हो जाता है।

const isValid = await engine.verifyRequest(req);
पैरामीटरटाइपविवरण
req{ headers: Record<string, string | string[] | undefined> }आने वाला HTTP रिक्वेस्ट ऑब्जेक्ट।

रिटर्न: Promise<boolean> — रिक्वेस्ट वैध होने पर true।

createSession

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

const session = engine.createSession(ws, { debug: true });
session.on("user_transcript", (transcript, signal) => {
  /* ... */
});
पैरामीटरटाइपडिफ़ॉल्टविवरण
wsWebSocketस्वीकार किया गया WebSocket कनेक्शन।
options.debugbooleanfalseडीबग लॉगिंग चालू करें।

रिटर्न: SpeechEngineSession

SpeechEngineServer

एक स्टैंडअलोन WebSocket सर्वर, जो मौजूदा HTTP सर्वर के बिना स्पीच इंजन कनेक्शन स्वीकार करता है। इसका इस्तेमाल तब करें जब आपके सर्वर का एकमात्र काम स्पीच इंजन कनेक्शन हैंडल करना हो।

मौजूदा HTTP सर्वर (जैसे Express, Fastify) के साथ इंटीग्रेशन के लिए, इसके बजाय engine.attach() का इस्तेमाल करें।

import { SpeechEngine } from "@elevenlabs/elevenlabs-js";
const server = new SpeechEngine.Server({
  port: 3001,
  debug: true,
  onTranscript(transcript, signal, session) {
    session.sendResponse(stream);
  },
});
server.start();

कंस्ट्रक्टर विकल्प

पैरामीटरटाइपडिफ़ॉल्टविवरण
portnumber3001सुनने के लिए पोर्ट।
apiKeystringकनेक्शन वेरिफ़ाई करने के लिए ElevenLabs API की। अगर नहीं दी गई है, तो ELEVENLABS_API_KEY एनवायरनमेंट वेरिएबल इस्तेमाल होता है। disableAuth के true होने पर ज़रूरी नहीं।
engineIdstringस्पीच इंजन ID। रिसोर्स से बनाने पर अपने-आप भर जाती है।
…SpeechEngineCallbacksसभी कॉलबैक विकल्प (onInit, onTranscript, onClose, onDisconnect, onError, debug, disableAuth)। कॉलबैक्स देखें।

start

कॉन्फ़िगर किए गए पोर्ट पर स्टैंडअलोन WebSocket सर्वर शुरू करें। कॉन्फ़िगर की गई API की का इस्तेमाल करके ElevenLabs API के साथ हर आने वाले कनेक्शन को वेरिफ़ाई करता है, जब तक disableAuth: true सेट न हो।

server.start();

stop

WebSocket सर्वर बंद करें और सभी सक्रिय कनेक्शन बंद करें।

await server.stop();

handleConnection

सर्वर के कॉलबैक्स वायर किए हुए किसी मौजूदा WebSocket को SpeechEngineSession में रैप करें। इसका इस्तेमाल तब करें जब आप अपना WebSocket सर्वर मैनेज करते हों और अलग-अलग कनेक्शन रैप करना चाहते हों।

const session = server.handleConnection(ws);
पैरामीटरटाइपविवरण
wsWebSocketस्वीकार किया गया WebSocket कनेक्शन।

रिटर्न: SpeechEngineSession

SpeechEngineSession

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

नया ट्रांसक्रिप्ट आने पर, पिछले ट्रांसक्रिप्ट हैंडलर का abort signal ट्रिगर होता है, जिससे चल रही कोई भी LLM कॉल रुक जाती है।

प्रॉपर्टीज़

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

on

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

session.on("user_transcript", (transcript, signal) => {
  /* ... */
});

off

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

session.off("user_transcript", listener);

once

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

session.once("init", (conversationId) => {
  /* ... */
});

sendResponse

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

// String response
session.sendResponse("Hello, how can I help?");
// Streamed response (OpenAI, Anthropic, or Gemini)
const stream = await openai.responses.create(
  { model: "gpt-4o", input: messages, stream: true },
  { signal }
);
session.sendResponse(stream);
पैरामीटरटाइपविवरण
responsestring | AsyncIterable<unknown>पूरी स्ट्रिंग या टेक्स्ट चंक्स / 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" }] } }] }

close

सेशन और उससे जुड़े WebSocket कनेक्शन को बंद करें।

session.close();

SpeechEngineAttachment

engine.attach() से लौटता है। जिस HTTP सर्वर से यह जुड़ा था, उसे प्रभावित किए बिना WebSocket सर्वर के लाइफ़साइकल को कंट्रोल करता है।

close

नए कनेक्शन स्वीकार करना बंद करें, HTTP सर्वर से अपग्रेड लिस्नर हटाएं और उससे जुड़े WebSocket सर्वर को बंद करें।

await attachment.close();

कॉलबैक्स

attach() या SpeechEngineServer को दिया गया कॉलबैक ऑब्जेक्ट। सभी कॉलबैक वैकल्पिक हैं।

कॉलबैकसिग्नेचरविवरण
onInit(conversationId: string, session: Session) => voidबातचीत ID के साथ सेशन शुरू हुआ।
onTranscript(transcript: TranscriptMessage[], signal: AbortSignal, session: Session) => voidयूज़र की आवाज़ ट्रांसक्राइब हुई।
onClose(session: Session) => voidElevenLabs से क्लीन डिस्कनेक्ट।
onDisconnect(session: Session) => voidWebSocket अनपेक्षित रूप से डिस्कनेक्ट हुआ।
onError(error: Error, session: Session) => voidप्रोटोकॉल या WebSocket एरर।
debugbooleanडीबग लॉगिंग चालू करें।
disableAuthbooleanआने वाले कनेक्शन पर JWT वेरिफ़िकेशन छोड़ें। ऑथेंटिकेशन बंद करना देखें।

onTranscript हैंडलर को AbortSignal मिलता है, जो यूज़र के रिस्पॉन्स के बीच में इंटरप्ट करने पर ट्रिगर होता है।

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

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

// Standalone — no apiKey required when disableAuth is true
new SpeechEngine.Server({ port: 3001, disableAuth: true, onTranscript }).start();
// Or on attach
elevenlabs.speechEngine.attach("seng_8k3m9xr4hjnfg983brhmhkd98n6", httpServer, "/ws", {
  disableAuth: true,
  onTranscript,
});

ऑथ बंद होने पर सर्वर, उस तक पहुंचने वाले किसी भी क्लाइंट को स्वीकार करता है और स्टार्टअप पर console.warn देता है।

disableAuth: true का इस्तेमाल सिर्फ़ तभी करें, जब सर्वर के सामने IP allowlist, कस्टम हेडर वैल्यू या इसी तरह का नेटवर्क-लेवल प्रतिबंध हो। इसके बिना, इंटरनेट पर कोई भी व्यक्ति सेशन खोल सकता है और आपके कंप्यूट तथा डाउनस्ट्रीम LLM कोटा का इस्तेमाल कर सकता है।

इवेंट्स

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

इवेंटहैंडलर सिग्नेचर
user_transcript(transcript: TranscriptMessage[], signal: AbortSignal)
init(conversationId: string)
close()
disconnected()
error(error: Error)

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

import { SpeechEngine } from "@elevenlabs/elevenlabs-js";
session.on(SpeechEngine.USER_TRANSCRIPT, (transcript, signal) => {
  /* ... */
});

TranscriptMessage

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

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

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

रेफरेंस के लिए, ये 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 का रिस्पॉन्स।