Client

Synchronous client for making requests to the Gemini API or Vertex AI API.

The Client class is the main entry point for making synchronous requests to the Gemini Developer API or Vertex AI API. It provides access to all SDK features including models, files, caches, tunings, and more.

Constructor

Create a new client instance for either the Gemini API or Vertex AI API.

vertexai · bool · default: "False"

Indicates whether the client should use the Vertex AI API endpoints. Defaults to False (uses Gemini Developer API endpoints).

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 environment variable.

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. For more information, see Set up Application 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. Find your project ID.

location · str

The location to send API requests to (e.g., us-central1). Can be obtained from environment variables (e.g., GOOGLE_CLOUD_LOCATION). Applies to the Vertex AI API only.

debug_config · DebugConfig

Configuration settings that control network behavior of the client. This is typically used when running test code.

http_options · types.HttpOptions | dict

HTTP options to use for the client. These options will be applied to all requests made by the client.

See HttpOptions for available fields.

Usage Examples

Gemini Developer API

from google import genai

client = genai.Client(api_key='my-api-key')

Vertex AI API

from google import genai

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

With HTTP Options

from google import genai
from google.genai import types

client = genai.Client(
    api_key='my-api-key',
    http_options=types.HttpOptions(
        api_version='v1',
        timeout=30000,  # 30 seconds in milliseconds
        headers={'Custom-Header': 'value'}
    )
)

Using Context Manager

from google import genai

with genai.Client(api_key='my-api-key') as client:
    response = client.models.generate_content(
        model='gemini-2.0-flash',
        contents='Hello World'
    )
    print(response.text)
# Client is automatically closed when exiting the context

Properties

models

models · Models

Access to the Models API for content generation, embeddings, and model management.

See generate_content for details.

response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='Tell me a story'
)

aio

aio · AsyncClient

Access to the asynchronous client for non-blocking operations.

See AsyncClient for details.

async_client = client.aio
response = await async_client.models.generate_content(
    model='gemini-2.0-flash',
    contents='Hello async world'
)

chats

chats · Chats

Access to multi-turn conversation functionality.

See chats.create for details.

chat = client.chats.create(model='gemini-2.0-flash')
response = chat.send_message('Hello!')

files

files · Files

Access to the Files API for uploading and managing media files.

See files.upload for details.

file = client.files.upload(path='image.jpg')
print(file.name)

caches

caches · Caches

Access to the Caches API for context caching.

See caches.create for details.

cache = client.caches.create(
    model='gemini-2.0-flash',
    contents='Long document...'
)

file_search_stores

file_search_stores · FileSearchStores

Access to the File Search Stores API for semantic search.

batches

batches · Batches

Access to the Batches API for batch processing.

See batches.create for details.

tunings

tunings · Tunings

Access to the Tunings API for model fine-tuning.

See tunings.tune for details.

auth_tokens

auth_tokens · Tokens

Access to authentication token management.

operations

operations · Operations

Access to long-running operations management.

interactions

interactions · InteractionsResource

Access to the experimental Interactions API for live, streaming interactions.

This API is experimental and may change in future versions.

vertexai

vertexai · bool

Returns whether the client is using the Vertex AI API.

if client.vertexai:
    print("Using Vertex AI API")
else:
    print("Using Gemini Developer API")

Methods

close()

Closes the synchronous client explicitly and releases resources.

This method does not close the async client. Use client.aio.aclose() or the async context manager to close the async client.

from google.genai import Client

client = Client(
    vertexai=True,
    project='my-project-id',
    location='us-central1'
)

response_1 = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='Hello World'
)

response_2 = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='Goodbye World'
)

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

Context Manager Methods

The Client supports the context manager protocol for automatic resource cleanup.

__enter__()

Enters the runtime context and returns the client.

__exit__(exc_type, exc_value, traceback)

Exits the runtime context and closes the client.

with genai.Client(api_key='my-api-key') as client:
    # Use the client
    response = client.models.generate_content(
        model='gemini-2.0-flash',
        contents='Hello'
    )
# Client is automatically closed here

HttpOptions

HTTP configuration options for customizing client behavior.

base_url · str

The base URL for the AI platform service endpoint.

api_version · str

Specifies the version of the API to use.

headers · dict[str, str]

Additional HTTP headers to be sent with each request.

timeout · int

Timeout for requests in milliseconds.

client_args · dict[str, Any]

Arguments passed to the HTTP client.

async_client_args · dict[str, Any]

Arguments passed to the async HTTP client.

extra_body · dict[str, Any]

Extra parameters to add to the request body. The structure must match the backend API’s request structure:

• VertexAI backend API docs
• GeminiAPI backend API docs

retry_options · HttpRetryOptions

HTTP retry options for requests. See HttpRetryOptions.

httpx_client · httpx.Client

A custom httpx client to be used for requests.

httpx_async_client · httpx.AsyncClient

A custom httpx async client to be used for requests.

aiohttp_client · aiohttp.ClientSession

A custom aiohttp client session to be used for requests.

HttpRetryOptions

Configuration options for HTTP request retries.

attempts · int · default: "5"

Maximum number of attempts, including the original request. If 0 or 1, it means no retries.

initial_delay · float · default: "1.0"

Initial delay before the first retry, in seconds.

max_delay · float · default: "60.0"

Maximum delay between retries, in seconds.

exp_base · float · default: "2.0"

Multiplier by which the delay increases after each attempt.

jitter · float · default: "1.0"

Randomness factor for the delay.

http_status_codes · list[int]

List of HTTP status codes that should trigger a retry. If not specified, a default set of retryable codes (408, 429, and 5xx) may be used.

from google import genai
from google.genai import types

client = genai.Client(
    api_key='my-api-key',
    http_options=types.HttpOptions(
        retry_options=types.HttpRetryOptions(
            attempts=3,
            initial_delay=0.5,
            max_delay=10.0
        )
    )
)

See Also

• AsyncClient - Asynchronous client for non-blocking operations
• generate_content - Generate content with models
• chats.create - Multi-turn conversations
• files.upload - Upload and manage media files