fix(responses-ws): append ?model= to backend WebSocket URL

[joereyna]

Summary

• OpenAI's WebSocket responses endpoint requires the model as a query parameter (wss://.../v1/responses?model=gpt-4o-mini), matching the Realtime API convention
• Without it the handshake succeeds but OpenAI never sends events, causing the client to time out after 15s
• Fixes test_responses_websocket_proxy_basic and test_responses_websocket_proxy_multi_turn in e2e_openai_endpoints CI

Test plan

• e2e_openai_endpoints CI passes
• TestNativeWebSocketUrlConstruction unit tests pass locally

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Apr 9, 2026 7:43pm

[codspeed-hq]

Merging this PR will not alter performance

✅ 16 untouched benchmarks

---

_{Comparing joereyna:litellm_fix_responses_websocket_model_query_param (3ac4333) with main (3a6db70)}

[greptile-apps]

Greptile Summary

This PR fixes OpenAI's WebSocket responses endpoint handshake by appending ?model=<model> to the backend WebSocket URL, matching the Realtime API convention. The handler change is well-implemented using urllib.parse to safely append the parameter while preserving any existing query params (e.g. api-version). Both new tests genuinely exercise the URL-building path inside the handler by capturing the URL passed to the mocked websockets.connect.

Confidence Score: 5/5

Safe to merge — the handler fix is correct and the tests genuinely verify URL construction.

All prior P1 concerns (missing model param, existing query params being dropped) are addressed by the urllib.parse-based implementation. The only remaining finding is a P2 style issue (inline imports in test methods). No blocking issues remain.

No files require special attention.

Vulnerabilities

No security concerns identified.

Important Files Changed

Filename	Overview
litellm/llms/custom_httpx/llm_http_handler.py	Adds module-level urllib.parse imports and correctly appends ?model= to the WebSocket URL using parse_qs/urlunparse, preserving existing query params.
tests/test_litellm/responses/test_responses_websocket_all_providers.py	Adds TestNativeWebSocketUrlConstruction with two tests that mock websockets.connect to capture the actual URL; imports are inlined inside test methods contrary to project style guide.

Sequence Diagram

sequenceDiagram
    participant Client
    participant LiteLLM as BaseLLMHTTPHandler
    participant URLBuilder as urllib.parse
    participant OpenAI as OpenAI WSS Backend

    Client->>LiteLLM: async_responses_websocket(model="gpt-4o-mini", ...)
    LiteLLM->>LiteLLM: get_complete_url() → "https://api.openai.com/v1/responses"
    LiteLLM->>LiteLLM: replace https→wss
    LiteLLM->>URLBuilder: urlparse(ws_url)
    URLBuilder-->>LiteLLM: ParseResult (query="")
    LiteLLM->>URLBuilder: parse_qs("") → {}
    Note over LiteLLM: "model" not in qs → append it
    LiteLLM->>URLBuilder: urlunparse(parsed._replace(query="model=gpt-4o-mini"))
    URLBuilder-->>LiteLLM: "wss://api.openai.com/v1/responses?model=gpt-4o-mini"
    LiteLLM->>OpenAI: websockets.connect("wss://...?model=gpt-4o-mini", headers=...)
    OpenAI-->>LiteLLM: WebSocket connection established
    LiteLLM->>Client: bidirectional_forward() stream

Loading

_{Reviews (2): Last reviewed commit: "fix(responses-ws): use urllib.parse to a..." | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!