Environment:Googleapis Python genai Gemini API Key Authentication
| Knowledge Sources | |
|---|---|
| Domains | Authentication, Infrastructure |
| Last Updated | 2026-02-15 14:00 GMT |
Overview
API key-based authentication environment for the Gemini Developer API, using `GOOGLE_API_KEY` or `GEMINI_API_KEY` environment variables.
Description
This environment configures authentication for the Gemini Developer API (non-Vertex AI) path. The SDK reads API keys from environment variables with a defined precedence order: `GOOGLE_API_KEY` takes priority over `GEMINI_API_KEY`. If both are set, a warning is logged and `GOOGLE_API_KEY` is used.
The API key is passed as the `x-goog-api-key` HTTP header on every request. The base URL for this mode is `https://generativelanguage.googleapis.com/` with API version `v1beta`.
Usage
Use this environment for Gemini Developer API access. This is the simplest authentication mode — obtain an API key from Google AI Studio and set it as an environment variable or pass it directly to the Client constructor.
This is mutually exclusive with the Vertex AI Service Account environment. You cannot provide both an API key and project/location or credentials simultaneously.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| Network | HTTPS to `generativelanguage.googleapis.com` | Default Gemini API endpoint |
| Authentication | Google API Key | Obtainable from Google AI Studio |
Dependencies
No additional dependencies beyond the base SDK runtime (Googleapis_Python_genai_Python_3_10_SDK_Runtime).
Credentials
The following environment variables configure API key authentication:
- `GOOGLE_API_KEY`: Primary API key for Google Gemini Developer API. Takes precedence if both keys are set.
- `GEMINI_API_KEY`: Fallback API key. Used only if `GOOGLE_API_KEY` is not set.
Alternatively, pass the API key directly:
client = genai.Client(api_key='your-api-key')
Quick Install
# Set the API key environment variable
export GOOGLE_API_KEY='your-api-key-here'
# Install the SDK
pip install google-genai
Code Evidence
API key retrieval with precedence logic from `_api_client.py:95-109`:
def get_env_api_key() -> Optional[str]:
env_google_api_key = os.environ.get('GOOGLE_API_KEY', None)
env_gemini_api_key = os.environ.get('GEMINI_API_KEY', None)
if env_google_api_key and env_gemini_api_key:
logger.warning(
'Both GOOGLE_API_KEY and GEMINI_API_KEY are set. Using GOOGLE_API_KEY.'
)
return env_google_api_key or env_gemini_api_key or None
Mutual exclusivity validation from `_api_client.py:567-578`:
if (project or location) and api_key:
raise ValueError(
'Project/location and API key are mutually exclusive in the client'
' initializer.'
)
elif credentials and api_key:
raise ValueError(
'Credentials and API key are mutually exclusive in the client'
' initializer.'
)
Ephemeral token restriction from `_api_client.py:1147-1150`:
if self.api_key and self.api_key.startswith('auth_tokens/'):
raise EphemeralTokenAPIKeyError(
'Ephemeral tokens can only be used with the live API.'
)
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `ValueError: Project/location and API key are mutually exclusive` | Both `api_key` and `project`/`location` provided | Use only one authentication mode |
| `ValueError: Credentials and API key are mutually exclusive` | Both `credentials` and `api_key` provided | Use only one authentication mode |
| `EphemeralTokenAPIKeyError: Ephemeral tokens can only be used with the live API` | Used `auth_tokens/` key with non-Live API | Ephemeral tokens only work with `client.aio.live` |
| `Both GOOGLE_API_KEY and GEMINI_API_KEY are set` (warning) | Both env vars configured | Remove one; `GOOGLE_API_KEY` takes precedence |
| `ClientError` with 401/403 | Invalid or expired API key | Regenerate key from Google AI Studio |
Compatibility Notes
- Precedence: `GOOGLE_API_KEY` > `GEMINI_API_KEY` > None.
- Ephemeral Tokens: API keys starting with `auth_tokens/` are restricted to the Live API only and require `api_version='v1alpha'`.
- Explicit vs Implicit: Explicitly passed `api_key` parameter always overrides environment variables.
- Vertex AI Express: API keys can also be used with Vertex AI (when `vertexai=True`), but explicit project/location takes precedence over implicit API key in that mode.