Environment:Googleapis Python genai Vertex AI Service Account

Knowledge Sources	googleapis/python-genai Vertex AI Documentation
Domains	Authentication, Infrastructure, Google_Cloud
Last Updated	2026-02-15 14:00 GMT

Overview

Google Cloud service account / Application Default Credentials (ADC) environment for Vertex AI API access, configured via `GOOGLE_GENAI_USE_VERTEXAI`, `GOOGLE_CLOUD_PROJECT`, and `GOOGLE_CLOUD_LOCATION`.

Description

This environment configures authentication for the Vertex AI API path. When `vertexai=True` or the `GOOGLE_GENAI_USE_VERTEXAI` environment variable is set, the SDK uses Google Cloud Application Default Credentials (ADC) with the `cloud-platform` OAuth scope. The base URL becomes `https://{location}-aiplatform.googleapis.com/` with API version `v1beta1`.

The SDK automatically loads credentials via `google.auth.default()` and manages token refresh using a thread-safe lock mechanism. Credentials are refreshed before each request if they have expired.

Usage

Use this environment when accessing Gemini models through Vertex AI in Google Cloud. This is required for enterprise features, VPC Service Controls, private endpoints, and when billing through a Google Cloud project.

System Requirements

Category	Requirement	Notes
Network	HTTPS to `{location}-aiplatform.googleapis.com`	Location-specific endpoint
Authentication	Google Cloud service account or ADC	Application Default Credentials
Google Cloud	Active GCP project with Vertex AI API enabled	Billing must be configured

Dependencies

No additional dependencies beyond the base SDK runtime (Googleapis_Python_genai_Python_3_10_SDK_Runtime). The `google-auth` package (already a core dependency) handles credential loading.

Credentials

The following environment variables configure Vertex AI authentication:

• `GOOGLE_GENAI_USE_VERTEXAI`: Set to `true` or `1` to enable Vertex AI mode.
• `GOOGLE_CLOUD_PROJECT`: Google Cloud project ID. Auto-detected from ADC if not set.
• `GOOGLE_CLOUD_LOCATION`: Google Cloud region (e.g., `us-central1`). Required for Vertex AI.
• `GOOGLE_VERTEX_BASE_URL`: (Optional) Custom Vertex AI base URL for private endpoints.
• `SSL_CERT_FILE`: (Optional) Path to custom CA certificate file. Defaults to certifi bundle.
• `SSL_CERT_DIR`: (Optional) Directory containing CA certificates.

Credential sources (in order of precedence):

1. Explicitly passed `credentials` parameter
2. Application Default Credentials via `google.auth.default()`

OAuth Scope: `https://www.googleapis.com/auth/cloud-platform`

Quick Install

# Set up Vertex AI mode
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT='my-project-id'
export GOOGLE_CLOUD_LOCATION='us-central1'

# Authenticate with Google Cloud
gcloud auth application-default login

# Install the SDK
pip install google-genai

Code Evidence

Vertex AI mode detection from `_api_client.py:559-564`:

if self.vertexai is None:
    if os.environ.get('GOOGLE_GENAI_USE_VERTEXAI', '0').lower() in [
        'true',
        '1',
    ]:
        self.vertexai = True

Project and location from environment in `_api_client.py:597-602`:

env_project = os.environ.get('GOOGLE_CLOUD_PROJECT', None)
env_location = os.environ.get('GOOGLE_CLOUD_LOCATION', None)
env_api_key = get_env_api_key()
self.project = project or env_project
self.location = location or env_location
self.api_key = api_key or env_api_key

ADC credential loading from `_api_client.py:182-203`:

def load_auth(*, project: Union[str, None]) -> Tuple[Credentials, str]:
    os.environ['GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES'] = 'false'
    credentials, loaded_project_id = google.auth.default(
        scopes=['https://www.googleapis.com/auth/cloud-platform'],
    )
    if not project:
        project = loaded_project_id
    if not project:
        raise ValueError(
            'Could not resolve project using application default credentials.'
        )
    return credentials, project

Precedence logic for Vertex AI mode from `_api_client.py:615-644`:

if self.vertexai:
    if credentials and env_api_key:
        # Explicit credentials take precedence over implicit api_key.
        self.api_key = None
    elif (env_location or env_project) and api_key:
        # Explicit api_key takes precedence over implicit project/location.
        self.project = None
        self.location = None
    elif (project or location) and env_api_key:
        # Explicit project/location takes precedence over implicit api_key.
        self.api_key = None
    elif (env_location or env_project) and env_api_key:
        # Implicit project/location takes precedence over implicit api_key.
        self.api_key = None

SSL configuration from `_api_client.py:834-835`:

cafile=os.environ.get('SSL_CERT_FILE', certifi.where())
capath=os.environ.get('SSL_CERT_DIR')

Common Errors

Error Message	Cause	Solution
`ValueError: Could not resolve project using application default credentials.`	No project ID found via ADC or env var	Set `GOOGLE_CLOUD_PROJECT` or pass `project=` parameter
`ValueError: Project/location and API key are mutually exclusive`	Both API key and project/location provided	Use one authentication mode
`google.auth.exceptions.DefaultCredentialsError`	No ADC configured	Run `gcloud auth application-default login`
`PermissionDenied` (403)	Vertex AI API not enabled or missing IAM roles	Enable Vertex AI API; grant `roles/aiplatform.user`

Compatibility Notes

• Vertex AI Express Mode: API keys can be used with Vertex AI (bypassing ADC), but project/location takes precedence when both are available from environment.
• Token Sharing: The SDK internally sets `GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES=false` to disable bound token sharing.
• Thread Safety: Credential refresh is protected by `threading.Lock` (sync) and `asyncio.Lock` (async) for concurrent access.
• Custom Endpoints: Use `GOOGLE_VERTEX_BASE_URL` for private or regional endpoints.
• Live API: Vertex AI Live API uses bearer token authentication over WebSocket, with automatic credential refresh if the token has expired.

Related Pages

• Implementation:Googleapis_Python_genai_Client_Init