WebSocket Realtime API crashes with "additional_headers" error

[RedaBenh]

Please read this first

• Have you read the docs? Yes, LiteLLM Proxy docs and OpenAI Realtime API documentation
• Have you searched for related issues? Yes, no similar issues found for WebSocket Realtime API

Describe the bug

LiteLLM proxy crashes when forwarding WebSocket connections to OpenAI's Realtime API (/v1/realtime). The connection is accepted by LiteLLM but immediately closes with error code 1011 and the message:

Internal server error: create_connection() got an unexpected keyword argument 'additional_headers'

All other LiteLLM endpoints (/v1/chat/completions, /v1/embeddings, etc.) work correctly. Only the WebSocket Realtime endpoint is affected.

Debug information

• LiteLLM version: v1.80.11 (Docker image: ghcr.io/berriai/litellm:main-v1.80.11)
• Python version: Python 3.13 (in Docker container)
• websockets version: 13.1
• Deployment: Docker Compose on Linux server

Repro steps

1. LiteLLM Configuration (litellm_config.yaml):

model_list:
  - model_name: gpt-realtime-mini
    litellm_params:
      model: openai/gpt-4o-realtime-preview
      api_key: os.environ/OPENAI_API_KEY

files_settings:
  - custom_llm_provider: openai
    api_key: os.environ/OPENAI_API_KEY

2. Docker Compose setup:

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-v1.80.11
    environment:
      - LITELLM_MASTER_KEY=${LITELLM_MASTER_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    ports:
      - "4000:4000"
    volumes:
      - ./litellm_config.yaml:/app/config.yaml

3. Minimal Python script to reproduce:

import asyncio
import websockets
import json

async def test_realtime():
    # Virtual user key created via LiteLLM UI
    api_key = "sk-litellm-virtual-key-xxx"

    url = "wss://your-litellm-server.com/v1/realtime?model=gpt-realtime-mini"

    headers = {
        "Authorization": f"Bearer {api_key}",
        "OpenAI-Beta": "realtime=v1"
    }

    try:
        async with websockets.connect(url, extra_headers=headers) as ws:
            print("Connected!")
            # Wait for response
            response = await ws.recv()
            print(f"Received: {response}")
    except Exception as e:
        print(f"Error: {e}")

asyncio.run(test_realtime())

4. Observe the error in LiteLLM logs:

INFO: ('10.0.0.3', 42410) - "WebSocket /v1/realtime?model=gpt-realtime-mini" [accepted]
INFO: connection open
INFO: connection closed

Client receives WebSocket close event with:

code: 1011
reason: 'Internal server error: create_connection() got an unexpected keyword argument 'additional_headers''

Expected behavior

LiteLLM should successfully proxy the WebSocket connection to OpenAI's Realtime API (wss://api.openai.com/v1/realtime) and maintain a bidirectional stream for real-time audio communication.

The connection should:

1. ✅ Accept the client WebSocket connection (this works)
2. ❌ Forward the connection to OpenAI with proper authentication (fails here)
3. Relay messages bidirectionally between client and OpenAI
4. Track usage and apply quota management

Additional context

Root cause analysis:

The error message suggests LiteLLM is trying to pass additional_headers to Python's asyncio.create_connection() function, which doesn't accept this parameter. This appears to be in LiteLLM's internal WebSocket forwarding code when establishing the upstream connection to OpenAI.

What works:

• ✅ Standard chat completions (/v1/chat/completions)
• ✅ Streaming chat with SSE
• ✅ Embeddings API
• ✅ All REST API endpoints

What doesn't work:

• ❌ WebSocket Realtime API (/v1/realtime)

Workaround

Currently, the only workaround i have is to bypass LiteLLM and connect directly to OpenAI's Realtime API endpoint, but this defeats the purpose of using LiteLLM for centralized management.

---

Environment Details:

• OS: Linux (Docker container based on Python 3.13)

[ihower]

@RedaBenh I took a look at this issue, and it doesn’t appear to be related to the OpenAI Agents SDK.
Your repro steps don’t use agents at all, and the failure happens entirely in the LiteLLM proxy.
I’d suggest reporting this in the LiteLLM repo instead of here.

[RedaBenh]

hi @ihower thank you for your answer, i will report this bug in LiteLLM repo.