> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# JavaScript SDK रेफरेंस

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

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

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

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();
const engine = await elevenlabs.speechEngine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6");
```

## SpeechEngineResource

### प्रॉपर्टीज़

| प्रॉपर्टी  | टाइप     | विवरण             |
| ---------- | -------- | ----------------- |
| `engineId` | `string` | स्पीच इंजन की ID। |

### attach

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

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

```typescript
const attachment = engine.attach(httpServer, "/ws", {
  debug: true,
  onTranscript(transcript, signal, session) {
    session.sendResponse(stream);
  },
});
```

| पैरामीटर     | टाइप                    | विवरण                                                 |
| ------------ | ----------------------- | ----------------------------------------------------- |
| `httpServer` | `http.Server`           | इससे जुड़ने वाला Node.js HTTP सर्वर।                  |
| `path`       | `string`                | वह URL पाथ जिस पर WebSocket अपग्रेड्स हैंडल करने हैं। |
| `handler`    | `SpeechEngineCallbacks` | कॉलबैक ऑब्जेक्ट ([कॉलबैक्स](#callbacks) देखें)।       |

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

```typescript
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` इस्तेमाल करने पर वेरिफ़िकेशन अपने-आप हो जाता है।

```typescript
const isValid = await engine.verifyRequest(req);
```

| पैरामीटर | टाइप                                                           | विवरण                             |
| -------- | -------------------------------------------------------------- | --------------------------------- |
| `req`    | `{ headers: Record<string, string \| string[] \| undefined> }` | आने वाला HTTP रिक्वेस्ट ऑब्जेक्ट। |

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

### createSession

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

```typescript
const session = engine.createSession(ws, { debug: true });
session.on("user_transcript", (transcript, signal) => {
  /* ... */
});
```

| पैरामीटर        | टाइप      | डिफ़ॉल्ट | विवरण                               |
| --------------- | --------- | -------- | ----------------------------------- |
| `ws`            | WebSocket |          | स्वीकार किया गया WebSocket कनेक्शन। |
| `options.debug` | `boolean` | `false`  | डीबग लॉगिंग चालू करें।              |

**रिटर्न:** `SpeechEngineSession`

## SpeechEngineServer

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

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

```typescript
import { SpeechEngine } from "@elevenlabs/elevenlabs-js";

const server = new SpeechEngine.Server({
  port: 3001,
  debug: true,
  onTranscript(transcript, signal, session) {
    session.sendResponse(stream);
  },
});

server.start();
```

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

| पैरामीटर   | टाइप                    | डिफ़ॉल्ट | विवरण                                                                                                                                                                         |
| ---------- | ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `port`     | `number`                | `3001`   | सुनने के लिए पोर्ट।                                                                                                                                                           |
| `apiKey`   | `string`                |          | कनेक्शन वेरिफ़ाई करने के लिए ElevenLabs API की। अगर नहीं दी गई है, तो `ELEVENLABS_API_KEY` एनवायरनमेंट वेरिएबल इस्तेमाल होता है। `disableAuth` के `true` होने पर ज़रूरी नहीं। |
| `engineId` | `string`                |          | स्पीच इंजन ID। रिसोर्स से बनाने पर अपने-आप भर जाती है।                                                                                                                        |
| ...        | `SpeechEngineCallbacks` |          | सभी कॉलबैक विकल्प (`onInit`, `onTranscript`, `onClose`, `onDisconnect`, `onError`, `debug`, `disableAuth`)। [कॉलबैक्स](#callbacks) देखें।                                     |

### start

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

```typescript
server.start();
```

### stop

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

```typescript
await server.stop();
```

### handleConnection

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

```typescript
const session = server.handleConnection(ws);
```

| पैरामीटर | टाइप        | विवरण                               |
| -------- | ----------- | ----------------------------------- |
| `ws`     | `WebSocket` | स्वीकार किया गया WebSocket कनेक्शन। |

**रिटर्न:** `SpeechEngineSession`

## SpeechEngineSession

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

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

### प्रॉपर्टीज़

| प्रॉपर्टी        | टाइप      | विवरण                                             |
| ---------------- | --------- | ------------------------------------------------- |
| `conversationId` | `string`  | API द्वारा दी गई बातचीत ID। `init` के बाद उपलब्ध। |
| `isOpen`         | `boolean` | सेशन अभी भी खुला है या नहीं।                      |

### on

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

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

### off

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

```typescript
session.off("user_transcript", listener);
```

### once

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

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

### sendResponse

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

```typescript
// 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);
```

| पैरामीटर   | टाइप                                 | विवरण                                                                   |
| ---------- | ------------------------------------ | ----------------------------------------------------------------------- |
| `response` | `string` \| `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 कनेक्शन को बंद करें।

```typescript
session.close();
```

## SpeechEngineAttachment

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

### close

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

```typescript
await attachment.close();
```

## कॉलबैक्स

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

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

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

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

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

```typescript
// 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` देता है।

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

## इवेंट्स

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

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

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

```typescript
import { SpeechEngine } from "@elevenlabs/elevenlabs-js";

session.on(SpeechEngine.USER_TRANSCRIPT, (transcript, signal) => {
  /* ... */
});
```

## TranscriptMessage

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

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

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

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

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

| मैसेज टाइप        | फ़ील्ड्स                                                   | विवरण                                |
| ----------------- | ---------------------------------------------------------- | ------------------------------------ |
| `init`            | `conversation_id: string`                                  | सेशन शुरू हुआ।                       |
| `user_transcript` | `user_transcript: TranscriptMessage[]`, `event_id: number` | यूज़र की आवाज़ ट्रांसक्राइब हुई।     |
| `ping`            |                                                            | कीप-अलाइव। SDK pong से जवाब देता है। |
| `close`           |                                                            | क्लीन डिस्कनेक्ट।                    |
| `error`           | `message: string`                                          | API से एरर।                          |

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

| मैसेज टाइप       | फ़ील्ड्स                                                   | विवरण                                  |
| ---------------- | ---------------------------------------------------------- | -------------------------------------- |
| `agent_response` | `content: string`, `event_id: number`, `is_final: boolean` | TTS सिंथेसिस के लिए LLM रिस्पॉन्स चंक। |
| `pong`           |                                                            | ping का रिस्पॉन्स।                     |