Google GenAI Provider

Connect to Google's Gemini models via AI Studio (personal) or Vertex AI (enterprise). Supports multiple authentication methods with automatic credential detection.

Name google_genai
SDK google-genai
Models Gemini 1.5, 2.0, 2.5 family
Max Context Up to 2M tokens (Gemini 1.5 Pro)

Endpoints

Endpoint Use Case Auth
AI Studio Personal, development, prototyping API Key
Vertex AI Enterprise, production, GCP integration GCP credentials
Quick start - AI Studio
from jaato import JaatoClient
from shared import ProviderConfig

client = JaatoClient()

# AI Studio with API key
client.connect_with_config(ProviderConfig(
    api_key="your-api-key",
    use_vertex_ai=False
), model="gemini-2.5-flash")
Quick start - Vertex AI
from jaato import JaatoClient

client = JaatoClient()

# Vertex AI with GCP credentials
client.connect(
    project="my-gcp-project",
    location="us-central1",
    model="gemini-2.5-flash"
)

Authentication Methods

Method Endpoint Use Case
api_key AI Studio Personal development, quick prototyping
adc Vertex AI Local development with gcloud
service_account_file Vertex AI CI/CD, production servers
impersonation Vertex AI Cross-project, least-privilege access
auto Either Auto-detect from environment

API Key (AI Studio)

Simplest authentication. Get a key from Google AI Studio. See the API Key section below for details.

  • Free tier available
  • No GCP project required
  • Rate limits apply

ADC - Application Default Credentials

Uses credentials from gcloud auth application-default login. Recommended for local development with Vertex AI. See the ADC section below for details.

Service Account File

Uses a downloaded JSON key file. Required for automated environments without interactive login.

Impersonation

Allows a user or service account to act as another service account. Useful for:

  • Cross-project resource access
  • Least-privilege access patterns
  • Testing with different permissions

Requires the source principal to have roles/iam.serviceAccountTokenCreator on the target service account.

API Key authentication
from shared import ProviderConfig, load_provider

provider = load_provider("google_genai")
provider.initialize(ProviderConfig(
    api_key="AIza...",
    use_vertex_ai=False,
    auth_method="api_key"
))
provider.connect("gemini-2.5-flash")
ADC authentication
# First, authenticate with gcloud
gcloud auth application-default login
provider.initialize(ProviderConfig(
    project="my-project",
    location="us-central1",
    use_vertex_ai=True,
    auth_method="adc"
))
Service account authentication
provider.initialize(ProviderConfig(
    project="my-project",
    location="us-central1",
    credentials_path="/path/to/key.json",
    use_vertex_ai=True,
    auth_method="service_account_file"
))
Impersonation authentication
# Impersonate another service account
provider.initialize(ProviderConfig(
    project="target-project",
    location="us-central1",
    target_service_account="target-sa@project.iam.gserviceaccount.com",
    use_vertex_ai=True,
    auth_method="impersonation"
))

Google AI Studio API Key Authentication

Authentication using a Google AI Studio API key is a simple, project-based identification method. Unlike the robust, user-identity-focused methods of OAuth or the service account methods of ADC/impersonation, the API key acts as a simple, long-lived secret token to link API calls to a specific Google Cloud project for the purpose of billing and quota tracking.

Key Characteristics

Project Identification, Not User Identification
The API key identifies which project is making the API call, not who (which specific user or service account) is making it.
Simple Mechanism
You include the API key directly in your API requests. The Google AI SDKs automate this by looking for the GOOGLE_GENAI_API_KEY environment variable.
Ease of Use
It is the easiest form of authentication to set up, ideal for prototyping, testing, and public applications. You can generate keys quickly in the Google AI Studio dashboard.
Limited Scope
API keys are generally used for accessing specific, project-bound AI services (like the Generative Language API) but do not grant broad IAM permissions across your entire Google Cloud environment.

Security Considerations

API keys are less secure than token-based methods because they are long-lived and can be easily exposed if hardcoded in source code or client-side applications.

  • Treat API keys like passwords - never commit them to source control
  • Use environment variables or secret managers to store keys
  • Add API or IP address restrictions in the Google Cloud Console
  • Rotate keys periodically
Recommendation
For production-level, enterprise applications that require robust security, granular access control, and compliance features, use Application Default Credentials (ADC) or service account impersonation within Vertex AI.
Get your API key
1. Go to https://aistudio.google.com/apikey
2. Click "Create API Key"
3. Copy the generated key
4. Store securely (never commit to git)
Setup environment variable
# In your .env file (add to .gitignore)
GOOGLE_GENAI_API_KEY=AIza...your-api-key

# Or export directly (session only)
export GOOGLE_GENAI_API_KEY=AIza...your-api-key
Use API key in code
from jaato import JaatoClient
from shared import ProviderConfig

client = JaatoClient()

# Explicit API key config
client.connect_with_config(ProviderConfig(
    api_key="AIza...",  # or from env var
    use_vertex_ai=False,
    auth_method="api_key"
), model="gemini-2.5-flash")

# Or auto-detect from GOOGLE_GENAI_API_KEY env var
client = JaatoClient()
client.connect(model="gemini-2.5-flash")
# Provider auto-detects API key from environment
Rate limits
Free tier limits (as of 2025):
- 15 RPM (requests per minute)
- 1,500 RPD (requests per day)
- 1M TPM (tokens per minute)

Some models (e.g., gemini-3-pro) are
not available in the free tier.

Application Default Credentials (ADC)

Application Default Credentials (ADC) is an authentication strategy used by Google Cloud client libraries to automatically find credentials based on the application's environment. It provides a single, consistent way for your code to authenticate to Google Cloud APIs (including Vertex AI) regardless of where the code is running.

How ADC Works

Instead of hardcoding credentials or managing API keys manually within your code, ADC abstracts the authentication process. When a Google Cloud client library initializes, it looks for credentials in a specific, predefined search path:

  1. Environment Variable: Checks for the GOOGLE_APPLICATION_CREDENTIALS environment variable, which can point to a local JSON key file for a service account.
  2. Local Credential File: On a local development machine, it looks for credentials in a well-known file location created by running the gcloud auth application-default login command.
  3. Attached Service Account: In production environments like Compute Engine, App Engine, or Cloud Run, the libraries automatically use the attached service account's credentials via the metadata server.

Relationship to Impersonation

ADC can work in conjunction with service account impersonation:

  • Local Development: You can set up your local ADC file by using the gcloud auth application-default login --impersonate-service-account command. This command uses your user credentials to obtain a short-lived token for a specified service account and stores it locally.
  • Production: A service account attached to a VM (the impersonator) can be granted permission to impersonate another service account (the target) with the specific permissions needed for a task.

In short, ADC is the mechanism that automatically finds and uses the correct credentials (whether user credentials, service account keys, or short-lived impersonated tokens) for your application. This allows for seamless transitions between different development and production environments without changing your application's authentication code.

Setup ADC for local development
# Option 1: Use your user credentials
gcloud auth application-default login

# Option 2: Use impersonation with ADC
gcloud auth application-default login \
  --impersonate-service-account=my-sa@project.iam.gserviceaccount.com
ADC search path
1. GOOGLE_APPLICATION_CREDENTIALS env var
   → /path/to/service-account.json

2. gcloud ADC file location
   → ~/.config/gcloud/application_default_credentials.json

3. GCE/Cloud Run metadata server
   → Attached service account credentials
Use ADC in code
from jaato import JaatoClient
from shared import ProviderConfig

client = JaatoClient()

# ADC authentication (default for Vertex AI)
client.connect_with_config(ProviderConfig(
    project="my-project",
    location="us-central1",
    auth_method="adc"  # or "auto" to auto-detect
), model="gemini-2.5-flash")

# Client automatically uses ADC
response = client.generate("Hello!")

Service Account Impersonation

The impersonation authentication method allows an authenticated identity (such as a user account or another service account) to assume the permissions of a different service account to access Google Cloud resources.

This method is a secure alternative to using long-lived service account keys, as it uses short-lived credentials and requires prior authentication.

Key Concepts

Impersonator Principal
The user or service account that initiates the authentication process. This principal must have the iam.serviceAccounts.getAccessToken permission, included in the roles/iam.serviceAccountTokenCreator IAM role.
Target Service Account
The service account whose permissions are being assumed. This account has the actual roles and permissions required to perform operations within Vertex AI.
Short-lived Credentials
When impersonation is used, the system generates temporary access tokens that expire quickly (typically in less than an hour).

Why Use Impersonation?

  • Enhanced Security: Eliminates the need to create, manage, and distribute persistent service account keys, which are high-risk credentials if exposed.
  • Flexible Access Control: Allows administrators to temporarily grant elevated access or test specific sets of permissions without altering a user's permanent IAM roles.
  • Local Development: Developers can use their own user credentials to impersonate a service account, making development and testing simpler without managing service account keys on local machines.

How It Works

  1. An authenticated user or service account (the impersonator) requests short-lived credentials for the target service account.
  2. Google Cloud checks if the impersonator has the Service Account Token Creator role on the target service account.
  3. If permission is granted, Google Cloud issues a short-lived access token.
  4. The impersonator uses this token to make API calls to Vertex AI, acting as the target service account and leveraging its permissions.

For detailed steps on setting up impersonation, refer to the Google Cloud documentation on service account impersonation.

Setup impersonation permissions
# Step 1: Grant Token Creator role to impersonator
# (e.g., your user account)
gcloud iam service-accounts add-iam-policy-binding \
  target-sa@my-project.iam.gserviceaccount.com \
  --member="user:developer@example.com" \
  --role="roles/iam.serviceAccountTokenCreator"

# Step 2: Ensure target SA has Vertex AI access
gcloud projects add-iam-policy-binding my-project \
  --member="serviceAccount:target-sa@my-project.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
Use impersonation in code
from jaato import JaatoClient
from shared import ProviderConfig

client = JaatoClient()

# Your user credentials (via ADC) will impersonate
# the target service account
client.connect_with_config(ProviderConfig(
    project="my-project",
    location="us-central1",
    target_service_account="target-sa@my-project.iam.gserviceaccount.com",
    auth_method="impersonation"
), model="gemini-2.5-flash")

# Now all requests use target SA's permissions
response = client.generate("Hello!")
Environment-based configuration
# .env file
JAATO_GOOGLE_PROJECT=my-project
JAATO_GOOGLE_LOCATION=us-central1
JAATO_GOOGLE_TARGET_SERVICE_ACCOUNT=target-sa@my-project.iam.gserviceaccount.com
JAATO_GOOGLE_AUTH_METHOD=impersonation
MODEL_NAME=gemini-2.5-flash
# Auto-detects impersonation from env
client = JaatoClient()
client.connect(model="gemini-2.5-flash")

ProviderConfig Fields

Field Type Description
project str GCP project ID (Vertex AI only)
location str GCP region, e.g., us-central1
api_key str API key for AI Studio
credentials_path str Path to service account JSON
use_vertex_ai bool True = Vertex AI, False = AI Studio
auth_method str auto, api_key, adc, service_account_file, impersonation
target_service_account str Target SA email for impersonation

Auto-Detection

With auth_method="auto" (default), the provider checks:

  1. GOOGLE_GENAI_API_KEY env var → AI Studio
  2. JAATO_GOOGLE_TARGET_SERVICE_ACCOUNT → Impersonation
  3. GOOGLE_APPLICATION_CREDENTIALS → Vertex AI
  4. ADC from gcloud → Vertex AI
  5. GCE metadata server → Vertex AI
Minimal config (auto-detect)
# Just set environment variables
# Provider auto-detects credentials

from jaato import JaatoClient

client = JaatoClient()
client.connect(
    project="my-project",      # from env if not set
    location="us-central1",    # from env if not set
    model="gemini-2.5-flash"
)
Explicit config
from shared import ProviderConfig

# Full control over authentication
config = ProviderConfig(
    project="my-gcp-project",
    location="us-central1",
    use_vertex_ai=True,
    auth_method="adc",
    extra={
        "timeout": 60,
        "retry_count": 3
    }
)

Environment Variables

AI Studio

Variable Description
GOOGLE_GENAI_API_KEY API key from AI Studio

Vertex AI

Variable Description
JAATO_GOOGLE_PROJECT GCP project ID
JAATO_GOOGLE_LOCATION GCP region
GOOGLE_APPLICATION_CREDENTIALS Path to service account key
JAATO_GOOGLE_TARGET_SERVICE_ACCOUNT Target SA for impersonation

Optional Overrides

Variable Description
JAATO_GOOGLE_AUTH_METHOD Force auth method
JAATO_GOOGLE_USE_VERTEX Force endpoint (true/false)

Legacy (still supported)

Legacy Equivalent
PROJECT_ID JAATO_GOOGLE_PROJECT
LOCATION JAATO_GOOGLE_LOCATION
GOOGLE_CLOUD_PROJECT JAATO_GOOGLE_PROJECT
.env for AI Studio
# Google AI Studio (simple)
GOOGLE_GENAI_API_KEY=AIza...your-key

# Model selection
MODEL_NAME=gemini-2.5-flash
.env for Vertex AI
# Vertex AI (enterprise)
JAATO_GOOGLE_PROJECT=my-gcp-project
JAATO_GOOGLE_LOCATION=us-central1

# Option 1: ADC (run gcloud auth first)
# No additional env needed

# Option 2: Service account key
GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

# Model selection
MODEL_NAME=gemini-2.5-flash
.env for Impersonation
# Impersonation (act as another SA)
JAATO_GOOGLE_PROJECT=target-project
JAATO_GOOGLE_LOCATION=us-central1
JAATO_GOOGLE_TARGET_SERVICE_ACCOUNT=target-sa@project.iam.gserviceaccount.com
JAATO_GOOGLE_AUTH_METHOD=impersonation

# Model selection
MODEL_NAME=gemini-2.5-flash

Error Handling

The provider uses fail-fast validation and throws specific exceptions with actionable error messages.

Exception Cause
CredentialsNotFoundError No credentials found for auth method
CredentialsInvalidError Credentials rejected or malformed
CredentialsPermissionError Missing IAM permissions
ProjectConfigurationError Missing project/location for Vertex AI
ImpersonationError Impersonation failed or missing target SA

All exceptions include:

  • What was checked
  • Why it failed
  • How to fix it
Handling auth errors
from shared.plugins.model_provider.google_genai.errors import (
    CredentialsNotFoundError,
    CredentialsPermissionError,
    ProjectConfigurationError,
    ImpersonationError,
)

try:
    provider.initialize(config)
except CredentialsNotFoundError as e:
    print(f"Missing credentials: {e}")
    # Error message includes fix instructions
except CredentialsPermissionError as e:
    print(f"Permission denied: {e}")
    # Includes gcloud command to fix
except ProjectConfigurationError as e:
    print(f"Bad config: {e}")
except ImpersonationError as e:
    print(f"Impersonation failed: {e}")
    # Includes Token Creator role setup
Example error message
CredentialsNotFoundError: No credentials found for authentication method: auto

Checked locations:
  - GOOGLE_GENAI_API_KEY: not set
  - GOOGLE_APPLICATION_CREDENTIALS: not set
  - ADC user credentials: ~/.config/gcloud/... (not found)

To fix, either:
  1. Run: gcloud auth application-default login
  2. Set GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
  3. Use API key: set GOOGLE_GENAI_API_KEY

Available Models

Model Context Best For
gemini-2.5-flash 1M tokens Fast, cost-effective
gemini-2.5-pro 1M tokens Complex reasoning
gemini-2.0-flash 1M tokens Previous generation
gemini-1.5-pro 2M tokens Largest context
gemini-1.5-flash 1M tokens Fast, previous gen

Capabilities

  • Function Calling: All Gemini models
  • Multimodal: Images, PDFs, video
  • Structured Output: JSON schema constraints
List available models
provider = load_provider("google_genai")
provider.initialize(config)

# List all models
models = provider.list_models()
for model in models:
    print(model)

# Filter by prefix
gemini_models = provider.list_models(prefix="gemini")

# Check context limit
provider.connect("gemini-2.5-flash")
limit = provider.get_context_limit()
print(f"Context: {limit:,} tokens")
Using structured output
# Gemini supports JSON schema constraints
schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"}
    },
    "required": ["name", "age"]
}

response = provider.send_message(
    "Extract: John is 30 years old",
    response_schema=schema
)

# response.structured_output = {"name": "John", "age": 30}

Troubleshooting

No credentials found

  • For AI Studio: Set GOOGLE_GENAI_API_KEY
  • For Vertex AI: Run gcloud auth application-default login
  • Or set GOOGLE_APPLICATION_CREDENTIALS

Permission denied (403)

  • Verify the service account has roles/aiplatform.user
  • Check the project has Vertex AI API enabled
  • Verify billing is enabled on the project

Project/location missing

  • Set JAATO_GOOGLE_PROJECT and JAATO_GOOGLE_LOCATION
  • Or pass explicitly in ProviderConfig

Invalid API key

  • Verify the key at AI Studio
  • Check for extra whitespace in the key
  • Ensure the key hasn't been revoked

Impersonation failed

  • Verify the source has roles/iam.serviceAccountTokenCreator on the target SA
  • Check the target SA email is correct
  • Ensure target SA has roles/aiplatform.user
GCP setup commands
# Enable Vertex AI API
gcloud services enable aiplatform.googleapis.com \
  --project=my-project

# Grant permissions to service account
gcloud projects add-iam-policy-binding my-project \
  --member="serviceAccount:my-sa@my-project.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

# Set up ADC for local dev
gcloud auth application-default login

# Verify current project
gcloud config get-value project
Setup for impersonation
# Grant Token Creator role to source (your user or SA)
gcloud iam service-accounts add-iam-policy-binding \
  target-sa@project.iam.gserviceaccount.com \
  --member="user:you@example.com" \
  --role="roles/iam.serviceAccountTokenCreator"

# Grant Vertex AI role to target SA
gcloud projects add-iam-policy-binding my-project \
  --member="serviceAccount:target-sa@project.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
Test connectivity
# Quick test script
from shared import load_provider, ProviderConfig

provider = load_provider("google_genai")

try:
    provider.initialize()  # Auto-detect
    provider.connect("gemini-2.5-flash")

    response = provider.generate("Say hello")
    print(f"Success: {response.text}")
except Exception as e:
    print(f"Error: {e}")