BerriAI/litellm · error · ValueError

api_base is required for Azure AVA TTS. Format: https://{reg

Error message

api_base is required for Azure AVA TTS. Format: https://{region}.api.cognitive.microsoft.com or https://{region}.tts.speech.microsoft.com

What it means

LiteLLM's Azure AVA (Azure Speech) text-to-speech provider builds the TTS endpoint URL from the api_base you pass. If api_base is None it cannot construct https://{region}.tts.speech.microsoft.com/cognitiveservices/v1 and raises a ValueError telling you the two accepted endpoint formats. This is a configuration error thrown before any network request is made.

Source

Thrown at litellm/llms/azure/text_to_speech/transformation.py:325

        # User-Agent
        validated_headers["User-Agent"] = "litellm"

        return validated_headers

    def get_complete_url(
        self,
        model: str,
        api_base: str | None,
        litellm_params: dict,
    ) -> str:
        """
        Get the complete URL for Azure AVA TTS request

        Azure TTS endpoint format:
        https://{region}.tts.speech.microsoft.com/cognitiveservices/v1
        """
        if api_base is None:
            raise ValueError(
                f"api_base is required for Azure AVA TTS. "
                f"Format: https://{{region}}.{self.COGNITIVE_SERVICES_DOMAIN} or "
                f"https://{{region}}.{self.TTS_SPEECH_DOMAIN}"
            )

        # Remove trailing slash and parse URL
        api_base = api_base.rstrip("/")
        parsed_url: Final = urlparse(api_base)
        hostname: Final = parsed_url.hostname or ""

        # Check if it's a Cognitive Services endpoint (convert to TTS endpoint)
        if self._is_cognitive_services_endpoint(hostname=hostname):
            region: Final = self._extract_region_from_hostname(hostname=hostname, domain=self.COGNITIVE_SERVICES_DOMAIN)
            return self._build_tts_url(region=region)

        # Check if it's already a TTS endpoint
        if self._is_tts_endpoint(hostname=hostname):
            if not api_base.endswith(self.TTS_ENDPOINT_PATH):

View on GitHub (pinned to 6c2dcb801b)

Solutions

Pass api_base explicitly, e.g. litellm.tts(model='azure/<voice>', api_base='https://eastus.tts.speech.microsoft.com', api_key=..., input=...).
Or use the Cognitive Services form https://eastus.api.cognitive.microsoft.com — LiteLLM detects it and rewrites it to the TTS host.
If set via env, confirm AZURE_API_BASE (or the documented AZURE_AI_API_BASE for this route) is exported in the process running litellm, not just your shell.
Copy the exact endpoint value from the Azure Speech resource's Keys and Endpoint page; the {region} placeholder must be replaced with a real region like westeurope.

Example fix

# before
resp = litellm.tts(model='azure/ava-Ash', api_key=AZURE_KEY, input='hello')

# after
resp = litellm.tts(
    model='azure/ava-Ash',
    api_key=AZURE_KEY,
    api_base='https://eastus.tts.speech.microsoft.com',
    input='hello',
)

Defensive patterns

Strategy: validation

Validate before calling

import os

def azure_tts_config_ok(api_base: str | None) -> bool:
    base = api_base or os.getenv('AZURE_API_BASE')
    return base is not None and base.startswith('https://')

Try / catch

try:
    litellm.tts(model=..., api_base=base, api_key=key, input=text)
except ValueError as e:
    if 'api_base is required for Azure AVA TTS' in str(e):
        raise ConfigurationError('Set AZURE_API_BASE to https://<region>.tts.speech.microsoft.com') from e
    raise

Prevention

Keep Azure provider config (api_base + api_key) in one typed settings object validated at app startup.
Add a startup assertion for AZURE_API_BASE whenever TTS routes are enabled.
Document the exact endpoint format next to the config so {region} placeholders never reach production.

When it happens

Trigger: Calling litellm.tts() or the speech endpoint with model='azure/<tts-model>' (or an AVA voice) without api_base in the request and without AZURE_API_BASE/AZURE_AI_API_BASE set in the environment; or passing api_key only and relying on a deployment name, which works for Azure OpenAI but not for the Azure Speech TTS route.

Common situations: Reusing Azure OpenAI chat config (api_key + api_version, no api_base) for TTS; forgetting that the Speech service needs a region-specific endpoint from the Azure Portal ('Resource management > Keys and Endpoint'); typo'ing the env var name; setting api_base in provider_config instead of the top-level call.

Related errors

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