> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dgrid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Realtime

> Build OpenAI-compatible Realtime API sessions on DGrid for low-latency text and audio conversations over WebSocket with streaming voice models.

The Realtime API exposes OpenAI-compatible low-latency text and audio conversations through websocket sessions plus an HTTP endpoint for short-lived client tokens.

## WebSocket Connection

Open a realtime websocket session directly when your backend can securely hold the DGrid API key.

```http theme={null}
WSS wss://api.dgrid.ai/v1/realtime?model={model}
```

| | |
| - | - |
| **Authorization** | `Authorization: Bearer <DGRID_API_KEY>; OpenAI-Beta: realtime=v1` |
| **Request** | `websocket` |
| **Response** | `websocket events` |

### Query Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `model` | string | Yes | Realtime model ID, such as `gpt-4o-realtime-preview`. |

### Client Events

| Event Type | Description |
| - | - |
| `session.update` | Update session-level options. |
| `input_audio_buffer.append` | Stream audio chunks to the server. |
| `input_audio_buffer.commit` | Commit the current buffered audio. |
| `response.create` | Trigger a new assistant response. |
| `conversation.item.create` | Insert a conversation item. |

### Server Events

| Event Type | Description |
| - | - |
| `session.created` | Session was successfully created. |
| `session.updated` | Session settings were updated. |
| `response.text.delta` | Streamed text token delta. |
| `response.audio.delta` | Streamed audio chunk delta. |
| `response.done` | Response has completed. |
| `error` | Error payload. |

```javascript JavaScript Example theme={null}
const ws = new WebSocket(
  'wss://api.dgrid.ai/v1/realtime?model=gpt-4o-realtime-preview',
  [],
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'OpenAI-Beta': 'realtime=v1'
    }
  }
)

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'session.update',
    session: {
      modalities: ['text', 'audio'],
      voice: 'alloy'
    }
  }))
}

ws.onmessage = (event) => {
  const data = JSON.parse(event.data)
  console.log('received event:', data)
}
```

```http Realtime Notes theme={null}
Authorization: Bearer <DGRID_API_KEY>
OpenAI-Beta: realtime=v1
```

## Create Realtime Session Token

Use the realtime endpoint example shown below when you need an authenticated GET request against the realtime HTTP entrypoint.

```http theme={null}
GET /v1/realtime
```

| | |
| - | - |
| **Authorization** | `Authorization: Bearer <DGRID_API_KEY>` |
| **Request** | `none` |
| **Response** | `101 · application/json` |

### Request Headers

| Field | Type | Required | Description |
| - | - | - | - |
| `Authorization` | string | Yes | Bearer token used to authenticate the realtime request. |

### Response Body

| Field | Type | Description |
| - | - | - |
| `101` | text | Successful upgrade response with no JSON body. |
| `error` | object | Error payload returned when the request fails. |

```bash cURL theme={null}
curl -X GET "https://api.dgrid.ai/v1/realtime" \
  -H "Authorization: Bearer "
```

```javascript JavaScript theme={null}
fetch("https://api.dgrid.ai/v1/realtime", {
  method: "GET",
  headers: {
    "Authorization": "Bearer "
  }
})
```

```go Go theme={null}
package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {
  url := "https://api.dgrid.ai/v1/realtime"

  req, _ := http.NewRequest("GET", url, nil)
  req.Header.Add("Authorization", "Bearer ")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}
```

```python Python theme={null}
import requests

url = "https://api.dgrid.ai/v1/realtime"

response = requests.request("GET", url, headers = {
  "Authorization": "Bearer "
})

print(response.text)
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.time.Duration;

HttpClient client = HttpClient.newBuilder()
  .connectTimeout(Duration.ofSeconds(10))
  .build();

HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
  .uri(URI.create("https://api.dgrid.ai/v1/realtime"))
  .header("Authorization", "Bearer ")
  .GET()
  .build();

try {
  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());
  System.out.println("Status code: " + response.statusCode());
  System.out.println("Response body: " + response.body());
} catch (Exception e) {
  e.printStackTrace();
}
```

```csharp C# theme={null}
using System;
using System.Net.Http;
using System.Text;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer ");
var response = await client.GetAsync("https://api.dgrid.ai/v1/realtime");
var responseBody = await response.Content.ReadAsStringAsync();
```

```text 101 theme={null}
Empty
```

```json 400 theme={null}
{
  "error": {
    "message": "string",
    "type": "string",
    "param": "string",
    "code": "string"
  }
}
```

## WebSocket Events

Plan your client around a small set of request and response event types for low-latency conversational streaming.

```http theme={null}
WSS wss://api.dgrid.ai/v1/realtime?model={model}
```

| | |
| - | - |
| **Authorization** | `Authorization: Bearer <DGRID_API_KEY>; OpenAI-Beta: realtime=v1` |
| **Request** | `websocket` |
| **Response** | `event stream` |

### Core Client Events

| Event Type | Description |
| - | - |
| `session.update` | Update modalities, voice, or other session preferences. |
| `input_audio_buffer.append` | Send encoded audio fragments. |
| `input_audio_buffer.commit` | Mark the buffered audio as ready. |
| `response.create` | Ask the server to begin generating a response. |
| `conversation.item.create` | Add a conversation turn or tool result. |

### Core Server Events

| Event Type | Description |
| - | - |
| `session.created` | Initial confirmation that the websocket session exists. |
| `session.updated` | Confirmation that session settings changed. |
| `response.text.delta` | Incremental text output. |
| `response.audio.delta` | Incremental audio output. |
| `response.done` | Final event for a completed response. |
| `error` | Recoverable or fatal error payload. |

### Integration Guidance

1. Buffer client-side audio in small chunks and use `input_audio_buffer.commit` to signal turn boundaries.
2. Listen for both `response.text.delta` and `response.audio.delta` if the session supports multimodal output.
3. Use the HTTP session token endpoint for browser clients so the long-lived API key never reaches the client.

```json response.text.delta theme={null}
{
  "type": "response.text.delta",
  "response_id": "resp_123",
  "delta": "Hello"
}
```

```json response.done theme={null}
{
  "type": "response.done",
  "response": {
    "id": "resp_123",
    "status": "completed"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.