BerriAI/litellm · error · ValueError

GEMINI_API_KEY is not set

Error message

GEMINI_API_KEY is not set

What it means

Raised by GeminiImageEditConfig.validate_environment before any request is sent for litellm.image_edit with a gemini/ image model (e.g. gemini/gemini-2.5-flash-image). Resolution is the explicit api_key argument OR the GEMINI_API_KEY secret — notably GOOGLE_API_KEY is NOT consulted here, unlike the chat/interactions Gemini handlers. The key is placed in the x-goog-api-key header.

Solutions

  1. Set GEMINI_API_KEY in the environment (export GEMINI_API_KEY=...)
  2. Or pass the key per call: litellm.image_edit(..., api_key=os.environ['GOOGLE_API_KEY']) — the explicit argument is checked first
  3. If you only have GOOGLE_API_KEY, alias it: export GEMINI_API_KEY="$GOOGLE_API_KEY"
  4. Verify: python -c "from litellm.secret_managers.main import get_secret_str; print(get_secret_str('GEMINI_API_KEY'))"

Example fix

# before
resp = litellm.image_edit(model='gemini/gemini-2.5-flash-image', prompt='add a hat', image=img_bytes)
# ValueError: GEMINI_API_KEY is not set

# after
resp = litellm.image_edit(
    model='gemini/gemini-2.5-flash-image',
    prompt='add a hat',
    image=img_bytes,
    api_key=os.environ['GOOGLE_API_KEY'],  # explicit key is accepted
)
Defensive patterns

Strategy: validation

Validate before calling

from litellm.secret_managers.main import get_secret_str

def gemini_image_edit_ready(api_key: str | None) -> bool:
    # NOTE: this handler accepts ONLY api_key arg or GEMINI_API_KEY — not GOOGLE_API_KEY
    return bool(api_key or get_secret_str('GEMINI_API_KEY'))

assert gemini_image_edit_ready(None), 'Set GEMINI_API_KEY or pass api_key= to image_edit'

Prevention

When it happens

Trigger: litellm.image_edit(model='gemini/gemini-2.5-flash-image', prompt=..., image=...) with no api_key kwarg while GEMINI_API_KEY is unset — even if GOOGLE_API_KEY IS set, because this handler ignores it.

Common situations: Users who set only GOOGLE_API_KEY (chat completion works, image edit fails); env vars missing in CI/containers; VPN/proxy deployments that inject keys under other names; free-tier projects using AI Studio keys.

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/14f373b1e16ad929. Report an issue: GitHub.

Appendix: source

Thrown at litellm/llms/gemini/image_edit/transformation.py:65

    ) -> dict[str, Any]:
        return map_openai_image_params_to_gemini(
            params=image_edit_optional_params,
            model=model,
            supported_params=self.get_supported_openai_params(model),
            parse_image_config_string=True,
        )

    def validate_environment(
        self,
        headers: dict,
        model: str,
        api_key: str | None = None,
        litellm_params: dict | None = None,
        api_base: str | None = None,
    ) -> dict:
        final_api_key: Final[str | None] = api_key or get_secret_str("GEMINI_API_KEY")
        if not final_api_key:
            raise ValueError("GEMINI_API_KEY is not set")

        headers["x-goog-api-key"] = final_api_key
        headers["Content-Type"] = "application/json"
        return headers

    def use_multipart_form_data(self) -> bool:
        """Gemini uses JSON requests, not multipart/form-data."""
        return False

    def get_complete_url(
        self,
        model: str,
        api_base: str | None,
        litellm_params: dict,
    ) -> str:
        base_url = api_base or get_secret_str("GEMINI_API_BASE") or self.DEFAULT_BASE_URL
        base_url = base_url.rstrip("/")
        return f"{base_url}/models/{model}:generateContent"

View on GitHub (pinned to 77b7c6c40c)