BerriAI/litellm · error · ValueError

API key is required for Topaz image variations. Set via `TOP

Error message

API key is required for Topaz image variations. Set via `TOPAZ_API_KEY` or `api_key=..`

What it means

Topaz Labs image-variation support in LiteLLM requires an API key on every request: validate_environment raises immediately when the api_key argument is None, directing you to TOPAZ_API_KEY or the api_key parameter. Unlike some providers, this code path performs no environment lookup itself — the key must already be resolved (by LiteLLM's main handler from TOPAZ_API_KEY, or passed explicitly) when it reaches this check.

Source

Thrown at litellm/llms/topaz/common_utils.py:24


class TopazException(BaseLLMException):
    pass


class TopazModelInfo(BaseLLMModelInfo):
    def validate_environment(
        self,
        headers: dict,
        model: str,
        messages: list[AllMessageValues],
        optional_params: dict,
        litellm_params: dict,
        api_key: str | None = None,
        api_base: str | None = None,
    ) -> dict:
        if api_key is None:
            raise ValueError("API key is required for Topaz image variations. Set via `TOPAZ_API_KEY` or `api_key=..`")
        return {
            # "Content-Type": "multipart/form-data",
            "Accept": "image/jpeg",
            "X-API-Key": api_key,
        }

    def get_models(self, api_key: str | None = None, api_base: str | None = None) -> list[str]:
        return [
            "topaz/Standard V2",
            "topaz/Low Resolution V2",
            "topaz/CGI",
            "topaz/High Resolution V2",
            "topaz/Text Refine",
        ]

    @staticmethod
    def get_api_key(api_key: str | None = None) -> str | None:
        return api_key or get_secret_str("TOPAZ_API_KEY")

View on GitHub (pinned to 77b7c6c40c)

Solutions

Export TOPAZ_API_KEY in the process environment so LiteLLM resolves it for topaz/* models.
Pass api_key="..." explicitly on the image_variation call.
For litellm proxy, set litellm_params.api_key on the topaz model_list deployment.
Verify with os.environ.get('TOPAZ_API_KEY') in the exact runtime before retrying.

Example fix

# before
resp = litellm.image_variation(model="topaz/Standard V2", image=fp)
# -> ValueError: API key is required for Topaz image variations...

# after
import os
resp = litellm.image_variation(
    model="topaz/Standard V2",
    image=fp,
    api_key=os.environ["TOPAZ_API_KEY"],
)

Defensive patterns

Strategy: validation

Validate before calling

import os


def topaz_ready(api_key: str | None = None) -> bool:
    return bool(api_key or os.environ.get("TOPAZ_API_KEY"))


if not topaz_ready():
    raise RuntimeError("TOPAZ_API_KEY missing — topaz image variations unavailable")

Try / catch

try:
    resp = litellm.image_variation(model="topaz/Standard V2", image=fp)
except ValueError as e:
    if "API key is required for Topaz" in str(e):
        raise RuntimeError("configure TOPAZ_API_KEY or per-deployment api_key") from e
    raise

Prevention

Check provider credentials at startup for every model you expose.
In proxy deployments, always set litellm_params.api_key for topaz models.
Remember Topaz validation accepts only an explicit key here — don't rely on loose defaults.

When it happens

Trigger: Calling litellm.image_variation(model="topaz/Standard V2", ...) without api_key while TOPAZ_API_KEY is not set in the environment; proxy deployments that omit litellm_params.api_key for the topaz model entry.

Common situations: New Topaz integration where the env var was never provisioned; containerized proxy missing the TOPAZ_API_KEY entry; assuming the key is optional because other image providers default differently; renaming the model provider prefix so key-resolution rules no longer match.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/c28a6287de02030f. Report an issue: GitHub.