BerriAI/litellm · error · ValueError

api_version is required for Azure OpenAI calls

Error message

api_version is required for Azure OpenAI calls

What it means

For the Azure Realtime API, when realtime_protocol is None or not 'GA'/'V1' (i.e. the beta protocol), Azure requires an explicit api_version query parameter in the WebSocket URL. This ValueError fires when api_version is None and the beta protocol is selected, before the connection attempt. Only the GA/V1 protocol omits the version from the URL.

Source

Thrown at litellm/llms/azure/realtime/handler.py:110

        api_base: str | None = None,
        api_key: str | None = None,
        api_version: str | None = None,
        azure_ad_token: str | None = None,
        client: Any | None = None,
        timeout: float | None = None,
        realtime_protocol: str | None = None,
        query_params: RealtimeQueryParams | None = None,
        user_api_key_dict: Any | None = None,
        litellm_metadata: dict | None = None,
    ):
        import websockets
        from websockets.asyncio.client import ClientConnection

        if api_base is None:
            raise ValueError("api_base is required for Azure OpenAI calls")
        backend_uses_beta_protocol: Final = realtime_protocol is None or realtime_protocol.upper() not in ("GA", "V1")
        if api_version is None and backend_uses_beta_protocol:
            raise ValueError("api_version is required for Azure OpenAI calls")

        url: Final = self._construct_url(
            api_base,
            model,
            api_version,
            realtime_protocol=realtime_protocol,
            query_params=query_params,
        )

        try:
            ssl_context: Final = get_shared_realtime_ssl_context()
            async with websockets.connect(
                url,
                additional_headers={
                    "api-key": api_key,
                },
                max_size=REALTIME_WEBSOCKET_MAX_MESSAGE_SIZE_BYTES,
                ssl=ssl_context,

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Pass an api_version your Azure resource supports, e.g. api_version='2024-10-01-preview'.
2. Or pass realtime_protocol='GA' (or 'V1') if your deployment is on the GA realtime endpoint, which does not need api_version.
3. Pin the api_version in config rather than relying on defaults across litellm upgrades.

Example fix

# before
await azure_realtime.connect(model='azure/voice', api_key=k, api_base=base)  # beta default, no version -> raises

# after (beta protocol, explicit version)
await azure_realtime.connect(model='azure/voice', api_key=k, api_base=base, api_version='2024-10-01-preview')

# after (GA protocol, version not required)
await azure_realtime.connect(model='azure/voice', api_key=k, api_base=base, realtime_protocol='GA')

def validate_realtime_version(api_version: str | None, realtime_protocol: str | None) -> None:
    beta = realtime_protocol is None or realtime_protocol.upper() not in ('GA', 'V1')
    if beta and not api_version:
        raise ValueError('pass api_version (e.g. 2024-10-01-preview) or use realtime_protocol="GA"')

try:
    await handler.connect(...)
except ValueError as e:
    if 'api_version is required' in str(e):
        raise ValueError('pin an Azure realtime api_version or switch to the GA protocol') from e
    raise

When it happens

Trigger: Connecting with realtime_protocol=None (default beta) and api_version unset; upgrading litellm after older previews defaulted a version; explicitly passing realtime_protocol='beta' without an api_version.

Common situations: Copy-pasted realtime examples that omit api_version; Azure preview API versions being retired so previously hardcoded values were removed; teams switching between GA and beta realtime endpoints and dropping the version argument.

Related errors

• api_base is required for Azure OpenAI calls
• api_base is required for Azure WebSocket
• max retries must be an int
• Azure OpenAI client is not initialized. Make sure api_key is
• api_base is required for Azure AI Studio. Please set the api

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/d18f94a9eb3fbafd. Report an issue: GitHub.