> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensorstudio.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# WebSocket API
> Get started with Soket AI Realtime Speech API in minutes
## Introduction
The Soket's Realtime Speech API, built on OpenAI's protocol, enables implementation of conversational AI capabilities through [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API), a widely supported protocol optimized for real-time server-to-server data transfer. This guide demonstrates how to establish WebSocket connections and interact with Realtime models. WebRTC support for browser and mobile clients will be available in an upcoming release.
## Access Your API Key
1. Log in to your TensorStudio account.
2. Navigate to the [API Keys](https://app.tensorstudio.ai/studio/api-keys) section under manage.
3. Generate a new API key for your project.
**Note:** Keep your API key secure. Avoid sharing it publicly.
## Explore the Realtime Speech API
The Realtime Speech API lets you create responsive conversational applications powered by expressive voice-enabled models. It handles both text and audio in real-time, detects when users are speaking, and can execute custom functions - all with minimal latency.
### Connection details
Connecting via WebSocket requires the following connection information:
| | |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **URL** | `wss://api.soket.ai/v1/realtime` |
| **Query Parameters** | `model`
Realtime model ID to connect to, like `pragna-realtime` |
| **Headers** | `Authorization: Bearer YOUR_API_KEY`
Substitute `YOUR_API_KEY` with a standard API key on the server, or an ephemeral token on insecure clients (note that WebRTC `coming soon` is recommended for this use case). |
Below are several examples of using these connection details to initialize a WebSocket connection to the Realtime API.
```javascript NodeJS theme={"system"}
import WebSocket from "ws";
import 'dotenv/config';
const API_KEY = process.env.TENSOR_STUDIO_API_KEY;
const url = "wss://api.soket.ai/v1/realtime?model=pragna-realtime";
const ws = new WebSocket(url, {
headers: {
"Authorization": "Bearer " + process.env.TENSOR_STUDIO_API_KEY,
"OpenAI-Beta": "realtime=v1",
},
});
ws.on("open", function open() {
console.log("Connected to server.");
});
ws.on("message", function incoming(message) {
console.log(JSON.parse(message.data));
});
```
```python Python theme={"system"}
# example requires websocket-client library:
# pip install websocket-client
import os
import json
import websocket
TENSOR_STUDIO_API_KEY = os.environ.get("TENSOR_STUDIO_API_KEY")
url = "wss://api.soket.ai/v1/realtime?model=pragna-realtime"
headers = [
"Authorization: Bearer " + TENSOR_STUDIO_API_KEY,
"OpenAI-Beta: realtime=v1"
]
def on_open(ws):
print("Connected to server.")
def on_message(ws, message):
data = json.loads(message)
print("Received event:", json.dumps(data, indent=2))
ws = websocket.WebSocketApp(
url,
header=headers,
on_open=on_open,
on_message=on_message,
)
ws.run_forever()
```
```javascript JavaScript theme={"system"}
const ws = new WebSocket(
"wss://api.soket.ai/v1/realtime?model=pragna-realtime",
[
"realtime",
// Auth
"openai-insecure-api-key." + TENSOR_STUDIO_API_KEY
]
);
ws.on("open", function open() {
console.log("Connected to server.");
});
ws.on("message", function incoming(message) {
console.log(message.data);
});
```
## Sending and receiving events
Communication with Realtime models occurs through bidirectional message exchange over the WebSocket interface. The comprehensive documentation of available client and server messages can be found in the [OpenAI Realtime API reference](/docs/api-reference/realtime-client-events). Upon establishing a connection, the interface supports various event types including text messages, audio streams, tool calling, speech interruptions using [Voice Activity Detection (VAD)](/vad), and configuration modifications - enabling robust real-time interactions with the model.
Below, you'll find examples of how to send and receive events over the WebSocket interface in several programming environments.
```javascript NodeJS / JavaScript theme={"system"}
// Server-sent events will come in as messages...
ws.on("message", function incoming(message) {
// Message data payloads will need to be parsed from JSON:
const serverEvent = JSON.parse(message.data)
console.log(serverEvent);
});
// To send events, create a JSON-serializeable data structure that
// matches a client-side event (see API reference)
const event = {
type: "response.create",
response: {
modalities: ["audio", "text"],
instructions: "Give me a haiku about code.",
}
};
ws.send(JSON.stringify(event));
```
```python Python theme={"system"}
# To send a client event, serialize a dictionary to JSON
# of the proper event type
def on_open(ws):
print("Connected to server.")
event = {
"type": "response.create",
"response": {
"modalities": ["text"],
"instructions": "Please assist the user."
}
}
ws.send(json.dumps(event))
# Receiving messages will require parsing message payloads
# from JSON
def on_message(ws, message):
data = json.loads(message)
print("Received event:", json.dumps(data, indent=2))
```
## Need Help?
* **Community Support:** Join the TensorStudio's [Discord Community](https://discord.gg/daRQX4yF) for tips and discussions.
* **Customer Support:** Reach us at [support@tensorstudio.ai](mailto:support@tensorstudio.ai).