BerriAI/litellm · error · ValueError

api_base is required for Azure OpenAI calls

Error message

api_base is required for Azure OpenAI calls

What it means

The Azure Realtime API handler opens a WebSocket to Azure OpenAI, which requires the resource endpoint URL; unlike chat calls there is no default base to fall back on. If api_base is None this ValueError is raised before websockets.connect is attempted. Azure realtime endpoints look like wss://<resource>.openai.azure.com/openai/realtime?... and cannot be guessed from the model name.

Source

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

        model: str,
        websocket: Any,
        logging_obj: LiteLLMLogging,
        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,

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Pass api_base='https://<resource>.openai.azure.com' (the handler converts the scheme for WebSocket use).
2. Set api_base in the model's litellm_params so it flows through to the realtime handler.
3. Also ensure api_version is set when not using the GA/V1 realtime protocol (see the companion api_version check).
4. Verify the deployment has realtime enabled on the Azure resource.

Example fix

# before
await azure_realtime.connect(model='azure/my-voice-deployment', api_key=key)  # raises

# after
await azure_realtime.connect(
    model='azure/my-voice-deployment',
    api_key=key,
    api_base='https://myresource.openai.azure.com',
    api_version='2024-10-01-preview',
)

def validate_realtime_config(api_base: str | None, api_version: str | None, realtime_protocol: str | None) -> None:
    if not api_base:
        raise ValueError('Azure realtime requires api_base (https://<resource>.openai.azure.com)')
    beta = realtime_protocol is None or realtime_protocol.upper() not in ('GA', 'V1')
    if beta and not api_version:
        raise ValueError('Azure realtime beta protocol requires api_version')

try:
    async with azure_realtime_session(...) as s:
        ...
except ValueError as e:
    if 'api_base is required' in str(e):
        raise ValueError('configure the Azure resource endpoint for realtime') from e
    raise

When it happens

Trigger: Calling the Azure realtime handler with model='azure/<deployment>' but no api_base argument and no resolved litellm_params api_base; audio streaming setups that configure only the key and deployment.

Common situations: Voice-agent integrations that copy OpenAI realtime examples (wss://api.openai.com) and swap only the model prefix; missing AZURE_API_BASE in containerized audio services; configs where api_base was added to the wrong model entry.

Related errors

• api_version is required for Azure OpenAI calls
• api_base is required for Azure WebSocket
• api_base is required for Azure AI Studio. Please set the api
• API base is required for OpenAI image variations
• max retries must be an int

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