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

# OpenAI Realtime Connector

> Bridge the OpenAI Realtime API with LiveAvatar for real-time avatar video

The OpenAI Realtime Connector bridges the [OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime) with LiveAvatar. OpenAI handles speech-to-speech orchestration while LiveAvatar renders the avatar video.

## Requirements

* OpenAI API key with access to the Realtime API
* Optional [Context](/docs/core-concepts/contexts) for system prompt / instructions

## Setup

**1. Register your OpenAI API key as a secret:**

```bash theme={null}
curl -X POST https://api.liveavatar.com/v1/secrets \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "secret_type": "OPENAI_API_KEY",
    "secret_value": "<openai_api_key>",
    "secret_name": "OpenAI Realtime Key"
  }'
```

**2. Start a session with the connector:**

```json theme={null}
{
  "mode": "LITE",
  "avatar_id": "<avatar_id>",
  "openai_realtime_config": {
    "secret_id": "<secret_id>",
    "context_id": "<context_id>",
    "voice": "alloy",
    "model": "gpt-realtime",
    "temperature": 0.8
  }
}
```

## Configuration

| Field         | Type   | Default        | Description                                                                         |
| ------------- | ------ | -------------- | ----------------------------------------------------------------------------------- |
| `secret_id`   | uuid   | required       | Secret ID referencing your `OPENAI_API_KEY` secret.                                 |
| `context_id`  | uuid   | —              | [Context](/docs/core-concepts/contexts) that supplies system prompt / instructions. |
| `voice`       | enum   | `alloy`        | OpenAI Realtime voice. See [voices](#voices).                                       |
| `model`       | string | `gpt-realtime` | OpenAI Realtime model identifier.                                                   |
| `temperature` | number | `0.8`          | Sampling temperature. Range: `0.6` – `1.2`.                                         |

### Voices

Supported voices currently accepted by the connector: `alloy`, `ash`, `ballad`, `coral`, `echo`, `fable`, `onyx`, `nova`, `shimmer`, `sage`, `verse`, `marin`, `cedar`. See OpenAI's [Realtime voices reference](https://platform.openai.com/docs/guides/realtime) for the authoritative list and characteristics.

## How it works

* A WebRTC room is created by LiveAvatar on your behalf (no WebSocket endpoint returned)
* LiveAvatar bridges your session to the OpenAI Realtime API using your credentials
* User audio is streamed to OpenAI Realtime; the model's audio drives avatar lip sync

```mermaid theme={null}
sequenceDiagram
    participant User
    participant LiveAvatar
    participant OpenAI as OpenAI Realtime

    User->>LiveAvatar: Start LITE session with openai_realtime_config
    LiveAvatar->>OpenAI: Open Realtime session (model + voice)
    User->>LiveAvatar: Audio input (speech)
    LiveAvatar->>OpenAI: Forward audio
    OpenAI-->>LiveAvatar: Model audio + transcript
    LiveAvatar->>User: Avatar video stream with lip sync
```

<Note>
  For protocol-level details — turn detection, tool calls, input/output modalities — see the [OpenAI Realtime API docs](https://platform.openai.com/docs/guides/realtime).
</Note>

## Billing

* **LiveAvatar**: 1 credit per session minute (avatar video only)
* **OpenAI**: charged separately against your OpenAI account for Realtime API usage