> 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.

# Python SDK रेफ़रेंस

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

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

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

```python
from elevenlabs import AsyncElevenLabs

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

## SpeechEngineResource

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

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

### serve

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

```python
await engine.serve(
    port=3001,
    path="/ws",
    debug=True,
    on_transcript=handle_transcript,
)
```

| पैरामीटर        | टाइप       | डिफ़ॉल्ट | विवरण                                                                                           |
| --------------- | ---------- | -------- | ----------------------------------------------------------------------------------------------- |
| `port`          | `int`      | `3001`   | सुनने के लिए पोर्ट।                                                                             |
| `path`          | `str`      | `None`   | कनेक्शन को इस पाथ तक सीमित करें। `None` सभी को स्वीकार करता है।                                 |
| `debug`         | `bool`     | `False`  | stdout पर डीबग लॉगिंग चालू करें।                                                                |
| `disable_auth`  | `bool`     | `False`  | आने वाले कनेक्शन पर JWT सत्यापन छोड़ें। [ऑथेंटिकेशन बंद करना](#disabling-authentication) देखें। |
| `on_init`       | `callable` |          | सेशन शुरू होने पर कॉल होता है।                                                                  |
| `on_transcript` | `callable` |          | यूज़र ट्रांसक्रिप्ट आने पर कॉल होता है।                                                         |
| `on_close`      | `callable` |          | कनेक्शन सही तरीके से बंद होने पर कॉल होता है।                                                   |
| `on_disconnect` | `callable` |          | WebSocket के अनपेक्षित रूप से डिस्कनेक्ट होने पर कॉल होता है।                                   |
| `on_error`      | `callable` |          | प्रोटोकॉल या WebSocket त्रुटियों पर कॉल होता है।                                                |

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

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

```python
# 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` जारी होता है।

> **Warning**
>
> `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` सेट होने के अलावा)।

```python
is_valid = engine.verify_request(headers)
```

| पैरामीटर  | टाइप   | विवरण                 |
| --------- | ------ | --------------------- |
| `headers` | `dict` | अनुरोध हेडर डिक्शनरी। |

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

### create_session

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

```python
session = engine.create_session(websocket, debug=True)
session.on("user_transcript", handle_transcript)
await session.run()
```

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

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

## SpeechEngineSession

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

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

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

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

### on

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

```python
session.on("user_transcript", handler)
```

### off

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

```python
session.off("user_transcript", handler)
```

### once

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

```python
session.once("init", handler)
```

### send_response

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

```python
# 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)
```

| पैरामीटर   | टाइप                    | विवरण                                                                 |
| ---------- | ----------------------- | --------------------------------------------------------------------- |
| `response` | `str` \| 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()` से मैन्युअल रूप से सेशन बनाने के बाद यही मुख्य एंट्री पॉइंट है।

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

### close

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

```python
session.close()
```

## कॉलबैक

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

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

## इवेंट्स

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

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

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

```python
from elevenlabs.speech_engine import USER_TRANSCRIPT, INIT, CLOSE, DISCONNECTED, ERROR

session.on(USER_TRANSCRIPT, handle_transcript)
```

## ConversationMessage

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

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

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

रेफ़रेंस के लिए, ये 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 का जवाब।                          |