Skip to main content

​
Overview

The Client class is the main entry point for interacting with Google’s Gen AI models. It supports both the Gemini Developer API and Vertex AI API, providing synchronous and asynchronous operations.

​
Importing the Client

from google import genai
from google.genai import types

​
Client Initialization

​
Gemini Developer API

Initialize the client with an API key: 
client = genai.Client(api_key='GEMINI_API_KEY')

​
Vertex AI API

Initialize the client with project and location: 
client = genai.Client(
    vertexai=True,
    project='your-project-id',
    location='us-central1'
)

​
Client Parameters

​
api_key
str
The API key to use for authentication. Applies to the Gemini Developer API only. Can also be set via the GOOGLE_API_KEY or GEMINI_API_KEY environment variable.
​
vertexai
bool
default:"False"
Indicates whether the client should use the Vertex AI API endpoints. Defaults to False (uses Gemini Developer API endpoints).
​
credentials
google.auth.credentials.Credentials
The credentials to use for authentication when calling the Vertex AI APIs. Credentials can be obtained from environment variables and default credentials. Applies to the Vertex AI API only.
​
project
str
The Google Cloud project ID to use for quota. Can be obtained from environment variables (e.g., GOOGLE_CLOUD_PROJECT). Applies to the Vertex AI API only.
​
location
str
The location to send API requests to (e.g., us-central1). Can be obtained from environment variables. Applies to the Vertex AI API only.
​
http_options
types.HttpOptions | dict
HTTP options to use for the client. These options will be applied to all requests made by the client.

​
Using Environment Variables

​
Gemini Developer API

Set the GEMINI_API_KEY or GOOGLE_API_KEY environment variable: 
export GEMINI_API_KEY='your-api-key'
Then create the client without explicit parameters: 
client = genai.Client()
If both GOOGLE_API_KEY and GEMINI_API_KEY are set, GOOGLE_API_KEY takes precedence.

​
Vertex AI API

Set the required environment variables: 
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT='your-project-id'
export GOOGLE_CLOUD_LOCATION='us-central1'
Then create the client: 
client = genai.Client()

​
Sync and Async Clients

The SDK provides both synchronous and asynchronous interfaces.

​
Synchronous Client

The default Client instance provides synchronous operations: 
client = genai.Client(api_key='GEMINI_API_KEY')

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='Hello World',
)
print(response.text)

​
Asynchronous Client

Access the async client using the .aio property: 
client = genai.Client(api_key='GEMINI_API_KEY')

response = await client.aio.models.generate_content(
    model='gemini-2.5-flash',
    contents='Hello World',
)
print(response.text)

​
Context Managers

Context managers ensure proper resource cleanup when the client is no longer needed.

​
Synchronous Context Manager

The sync client context manager automatically closes the underlying sync client: 
from google.genai import Client

with Client(api_key='GEMINI_API_KEY') as client:
    response_1 = client.models.generate_content(
        model='gemini-2.5-flash',
        contents='Hello',
    )
    response_2 = client.models.generate_content(
        model='gemini-2.5-flash',
        contents='Ask a question',
    )
Using the context manager prevents “client has been closed” errors by automatically releasing resources when exiting the with block.

​
Asynchronous Context Manager

The async client context manager automatically closes the underlying async client: 
from google.genai import Client

async with Client(api_key='GEMINI_API_KEY').aio as aclient:
    response_1 = await aclient.models.generate_content(
        model='gemini-2.5-flash',
        contents='Hello',
    )
    response_2 = await aclient.models.generate_content(
        model='gemini-2.5-flash',
        contents='Ask a question',
    )

​
Closing Clients

​
Closing the Sync Client

Explicitly close the sync client to release resources: 
from google.genai import Client

client = Client(api_key='GEMINI_API_KEY')
response_1 = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='Hello',
)
response_2 = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='Ask a question',
)

# Close the sync client to release resources
client.close()

​
Closing the Async Client

Explicitly close the async client using aclose(): 
from google.genai import Client

aclient = Client(
    vertexai=True,
    project='my-project-id',
    location='us-central1'
).aio

response_1 = await aclient.models.generate_content(
    model='gemini-2.5-flash',
    contents='Hello',
)
response_2 = await aclient.models.generate_content(
    model='gemini-2.5-flash',
    contents='Ask a question',
)

# Close the async client to release resources
await aclient.aclose()
When you close the sync client with client.close(), it doesn’t close the async client. Similarly, when you close the async client with await client.aio.aclose(), it doesn’t close the sync client. Each must be closed separately if both are used.

​
Client Properties

The client provides access to various API resources:
  • client.models - Model operations (generate content, count tokens, etc.)
  • client.chats - Chat session management
  • client.files - File upload and management (Gemini API only)
  • client.caches - Cached content management
  • client.tunings - Model tuning operations (Vertex AI only)
  • client.batches - Batch prediction jobs
  • client.operations - Long-running operation management
  • client.aio - Async client interface
  • client.vertexai - Boolean indicating if using Vertex AI API

​
HTTP Options

Customize client behavior with HTTP options: 
from google import genai
from google.genai import types

client = genai.Client(
    vertexai=True,
    project='your-project-id',
    location='us-central1',
    http_options=types.HttpOptions(
        api_version='v1',
        timeout=60000,  # 60 seconds in milliseconds
        retry_options=types.HttpRetryOptions(
            attempts=5,
            initial_delay=1.0,
            max_delay=60.0
        )
    )
)

​
API Version Selection

By default, the SDK uses beta API endpoints. To use stable v1 endpoints:

​
Vertex AI

from google import genai
from google.genai import types

client = genai.Client(
    vertexai=True,
    project='your-project-id',
    location='us-central1',
    http_options=types.HttpOptions(api_version='v1')
)

​
Gemini Developer API

from google import genai
from google.genai import types

client = genai.Client(
    api_key='GEMINI_API_KEY',
    http_options=types.HttpOptions(api_version='v1alpha')
)

Build docs developers (and LLMs) love

Get started for freeTalk to us