BerriAI/litellm · error · ValueError

api_base is required for Azure AI Studio. Please set the api

Error message

api_base is required for Azure AI Studio. Please set the api_base parameter. Passed `api_base={api_base}`

What it means

The Azure image-edit transformation builds the full request URL from an api_base that is resolved through the chain: api_base argument -> litellm.api_base global -> AZURE_API_BASE environment variable. If all three are empty this ValueError fires, because Azure image edits require the resource endpoint (e.g. https://<resource>.openai.azure.com) to construct the /openai/deployments/<deployment>/images/edits URL. It is raised before any HTTP request.

Source

Thrown at litellm/llms/azure/image_edit/transformation.py:93

    ) -> str:
        """
        Constructs a complete URL for the API request.

        Args:
        - api_base: Base URL, e.g.,
            "https://litellm8397336933.openai.azure.com"
            OR
            "https://litellm8397336933.openai.azure.com/openai/deployments/<deployment_name>/images/edits?api-version=2024-05-01-preview"
        - model: Model name (deployment name).
        - litellm_params: Additional query parameters, including "api_version".

        Returns:
        - A complete URL string, e.g.,
        "https://litellm8397336933.openai.azure.com/openai/deployments/<deployment_name>/images/edits?api-version=2024-05-01-preview"
        """
        api_base = api_base or litellm.api_base or get_secret_str("AZURE_API_BASE")
        if api_base is None:
            raise ValueError(
                f"api_base is required for Azure AI Studio. Please set the api_base parameter. Passed `api_base={api_base}`"
            )
        original_url: Final = httpx.URL(api_base)

        # Resolve api_version: litellm_params > litellm.api_version > AZURE_API_VERSION env > default.
        # Mirrors the fallback chain used by the Azure chat path in common_utils.py,
        # so callers that set a global / env api_version don't get an unversioned URL.
        api_version: Final = (
            cast(str | None, litellm_params.get("api_version"))
            or litellm.api_version
            or get_secret_str("AZURE_API_VERSION")
            or litellm.AZURE_DEFAULT_API_VERSION
        )

        # Create a new dictionary with existing params
        query_params: Final = dict(original_url.params)

        # Add api_version if needed

View on GitHub (pinned to 6c2dcb801b)

Solutions

Pass api_base='https://<your-resource>.openai.azure.com' explicitly to the image edit call.
Or export AZURE_API_BASE in the environment.
Or set litellm.api_base globally at startup.
Note api_version may also be needed; it resolves from litellm_params, litellm.api_version, AZURE_API_VERSION, then a default.

Example fix

# before
resp = litellm.azure_image_edit(model='azure/my-deployment', image_data=img, prompt='remove background')

# after
resp = litellm.azure_image_edit(
    model='azure/my-deployment',
    image_data=img,
    prompt='remove background',
    api_base='https://myresource.openai.azure.com',
    api_key=os.environ['AZURE_API_KEY'],
)

Defensive patterns

Strategy: validation

Validate before calling

import os, litellm

def resolve_azure_api_base(api_base: str | None) -> str:
    base = api_base or litellm.api_base or os.environ.get('AZURE_API_BASE')
    if not base:
        raise ValueError('Azure image edit requires api_base (arg, litellm.api_base, or AZURE_API_BASE)')
    return base

Try / catch

try:
        resp = litellm.azure_image_edit(..., api_base=api_base)
    except ValueError as e:
        if 'api_base is required' in str(e):
            raise ValueError('set AZURE_API_BASE or pass api_base for image edits') from e
        raise

Prevention

Always configure AZURE_API_BASE alongside AZURE_API_KEY.
Treat the three-part Azure config (base, key, version) as one unit in deployment templates.

When it happens

Trigger: Calling azure image edit without api_base while litellm.api_base is unset and AZURE_API_BASE is not exported; passing model='azure/<deployment>' believing the deployment name alone locates the resource.

Common situations: Configs that set AZURE_API_KEY and AZURE_API_VERSION but never AZURE_API_BASE; migrating from chat calls (which resolve the base elsewhere) to image edits; environment-specific .env files missing the base URL key.

Related errors

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