# Realtime API (/docs/realtime)


Overview [#overview]

The Realtime API provides WebSocket-based bidirectional communication for applications requiring ultra-low latency, such as voice assistants and interactive agents.

Connection [#connection]

<WsUrl suffix="/v1/realtime" />

Authentication [#authentication]

Pass the API key as a query parameter or in the initial handshake:

```javascript
const ws = new WebSocket(
  "wss://api.yuhuanstudio.com/v1/realtime?api_key=YOUR_API_KEY"
);
```

Message Protocol [#message-protocol]

All messages are JSON-encoded:

Send Input [#send-input]

```json
{
  "type": "input_audio_buffer.append",
  "audio": "<base64-encoded-audio>"
}
```

Receive Output [#receive-output]

```json
{
  "type": "response.audio.delta",
  "delta": "<base64-encoded-audio-chunk>"
}
```

Example: Voice Chat [#example-voice-chat]

```javascript
const ws = new WebSocket(
  "wss://api.yuhuanstudio.com/v1/realtime?api_key=YOUR_API_KEY"
);

ws.onopen = () => {
  // Configure session
  ws.send(JSON.stringify({
    type: "session.update",
    session: {
      model: "model-id",
      modalities: ["text", "audio"],
      voice: "alloy"
    }
  }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  switch (message.type) {
    case "response.text.delta":
      process.stdout.write(message.delta);
      break;
    case "response.audio.delta":
      // Play audio chunk
      playAudio(message.delta);
      break;
    case "response.done":
      console.log("\n--- Response complete ---");
      break;
  }
};
```

Event Types [#event-types]

Client Events [#client-events]

| Event                       | Description                  |
| --------------------------- | ---------------------------- |
| `session.update`            | Configure session parameters |
| `input_audio_buffer.append` | Send audio data              |
| `input_audio_buffer.commit` | Finalize audio input         |
| `conversation.item.create`  | Send text message            |
| `response.create`           | Trigger response generation  |

Server Events [#server-events]

| Event                  | Description            |
| ---------------------- | ---------------------- |
| `session.created`      | Session initialized    |
| `response.text.delta`  | Partial text response  |
| `response.audio.delta` | Partial audio response |
| `response.done`        | Response complete      |
| `error`                | Error occurred         |

<Callout type="info">
  The Realtime API requires models that support real-time interaction. Check model capabilities for `realtime` support.
</Callout>