Client

Learn how to initialize and manage the Google Gen AI client for both sync and async operations

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')
)