openai/openai-python · error · OpenAIError

`model` is required for Azure Realtime API

Error message

`model` is required for Azure Realtime API

What it means

Raised by the async Realtime connect path when the client is an AzureOpenAI client and no `model` argument was supplied. Azure requires the deployment/model name to build the correct realtime URL and auth via _configure_realtime, so the SDK refuses to proceed without it.

Source

Thrown at src/openai/resources/realtime/realtime.py:698

    enter = __aenter__

    async def _connect_ws(self, extra_query: Query, extra_headers: Headers) -> AsyncWebSocketConnection:
        try:
            from ...lib._websocket import _WebSocketConnect as connect
        except ImportError as exc:
            raise OpenAIError("You need to install `openai[realtime]` to use this method") from exc

        await self.__client._refresh_api_key()
        auth_headers = self.__client.auth_headers
        if self.__call_id is not omit:
            extra_query = {**extra_query, "call_id": self.__call_id}
        if is_async_azure_client(self.__client):
            from ...lib._azure_websocket import _AzureWebSocketConnect as connect

            model = self.__model
            if not model:
                raise OpenAIError("`model` is required for Azure Realtime API")
            else:
                url, auth_headers = await self.__client._configure_realtime(model, extra_query)
        else:
            url = self._prepare_url().copy_with(
                params={
                    **self.__client.base_url.params,
                    **({"model": self.__model} if self.__model is not omit else {}),
                    **extra_query,
                },
            )
        log.debug("Connecting to WebSocket API")
        if self.__websocket_connection_options:
            log.debug("Custom WebSocket connection options provided")

        return await connect(
            str(url),
            user_agent_header=self.__client.user_agent,
            additional_headers=_merge_mappings(

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Pass the Azure deployment name explicitly: client.beta.realtime.connect(model="my-deployment", ...)
2. Ensure the name matches the deployment created in Azure OpenAI Studio, not necessarily the underlying model id
3. If using multiple deployments, resolve the model per session before connecting

Example fix

# before
async with azure_client.beta.realtime.connect() as conn: ...
# after
async with azure_client.beta.realtime.connect(model="gpt-4o-realtime-deploy") as conn: ...

if is_azure and not (model and model.strip()):
    raise ValueError("model (Azure deployment name) is required for Realtime")

def has_model(v: str | None) -> bool:
    return bool(v and v.strip())

try:
    async with azure_client.beta.realtime.connect(model=model) as conn: ...
except OpenAIError as e:
    if "`model` is required" in str(e):
        model = resolve_deployment_name()
        # retry with model

When it happens

Trigger: `async with AsyncOpenAI-style AzureOpenAI().beta.realtime.connect(...)` (or azure_monitor-style realtime connect) without passing model=..., or passing model=NOT_GIVEN/None.

Common situations: Porting OpenAI-first code to Azure and relying on a default_model set on the client (the Realtime path requires the per-call model), or forgetting that Azure uses deployment names.

Related errors

• Configure `provider` on `AsyncOpenAI`, not on `AsyncAzureOpe
• WebSocket connection closed with unsent messages
• WebSocket error: {event}
• You need to install `openai[realtime]` to use this method
• max_retries cannot be None. If you want to disable retries,

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/0f5f0645ecf0f9d8. Report an issue: GitHub.