0
# Client Initialization and Configuration
1

2
Client initialization and configuration for accessing the Google GenAI Python SDK. The SDK supports both the Gemini Developer API (using API keys) and Vertex AI API (using Google Cloud credentials and project configuration). The Client class provides access to all SDK functionality through specialized API modules.
3

4
## Capabilities
5

6
### Client Initialization
7

8
Initialize the main synchronous client to access all SDK functionality. The client automatically determines which API to use based on the provided configuration.
9

10
```python { .api }
11
class Client:
12
    """
13
    Primary synchronous client for making requests to Gemini Developer API or Vertex AI API.
14

15
    Parameters:
16
        vertexai (bool, optional): Use Vertex AI API endpoints. Defaults to False (Gemini Developer API).
17
            Can be set via GOOGLE_GENAI_USE_VERTEXAI environment variable.
18
        api_key (str, optional): API key for Gemini Developer API authentication.
19
            Can be set via GOOGLE_API_KEY environment variable.
20
        credentials (google.auth.credentials.Credentials, optional): Google Cloud credentials for Vertex AI API.
21
            Uses Application Default Credentials if not provided.
22
        project (str, optional): Google Cloud project ID for Vertex AI API quota.
23
            Can be set via GOOGLE_CLOUD_PROJECT environment variable.
24
        location (str, optional): Google Cloud location for Vertex AI API (e.g., 'us-central1').
25
            Can be set via GOOGLE_CLOUD_LOCATION environment variable.
26
        debug_config (DebugConfig, optional): Configuration for testing and debugging network behavior.
27
        http_options (Union[HttpOptions, HttpOptionsDict], optional): HTTP client configuration options.
28

29
    Returns:
30
        Client instance providing access to all SDK API modules.
31
    """
32
    def __init__(
33
        self,
34
        *,
35
        vertexai: Optional[bool] = None,
36
        api_key: Optional[str] = None,
37
        credentials: Optional[google.auth.credentials.Credentials] = None,
38
        project: Optional[str] = None,
39
        location: Optional[str] = None,
40
        debug_config: Optional[DebugConfig] = None,
41
        http_options: Optional[Union[HttpOptions, HttpOptionsDict]] = None
42
    ): ...
43

44
    @property
45
    def aio(self) -> AsyncClient:
46
        """Access the async client interface for non-blocking operations."""
47
        ...
48

49
    @property
50
    def models(self) -> Models:
51
        """Access models API for content generation, embeddings, and image/video generation."""
52
        ...
53

54
    @property
55
    def chats(self) -> Chats:
56
        """Create multi-turn chat sessions with automatic history management."""
57
        ...
58

59
    @property
60
    def files(self) -> Files:
61
        """Access file management API (Gemini Developer API only)."""
62
        ...
63

64
    @property
65
    def caches(self) -> Caches:
66
        """Access cached content API for context caching."""
67
        ...
68

69
    @property
70
    def batches(self) -> Batches:
71
        """Access batch prediction jobs API."""
72
        ...
73

74
    @property
75
    def tunings(self) -> Tunings:
76
        """Access tuning jobs API (Vertex AI only)."""
77
        ...
78

79
    @property
80
    def file_search_stores(self) -> FileSearchStores:
81
        """Access file search stores API for retrieval-augmented generation."""
82
        ...
83

84
    @property
85
    def auth_tokens(self) -> Tokens:
86
        """Access authentication tokens API."""
87
        ...
88

89
    @property
90
    def operations(self) -> Operations:
91
        """Access long-running operations API."""
92
        ...
93

94
    @property
95
    def vertexai(self) -> bool:
96
        """Returns True if the client is using Vertex AI API, False otherwise."""
97
        ...
98

99
    def close(self) -> None:
100
        """
101
        Close the synchronous client explicitly to release resources.
102

103
        Note: This does not close the async client. Use Client.aio.aclose() for async client.
104
        """
105
        ...
106

107
    def __enter__(self) -> 'Client':
108
        """Context manager entry for automatic resource cleanup."""
109
        ...
110

111
    def __exit__(self, *args) -> None:
112
        """Context manager exit for automatic resource cleanup."""
113
        ...
114
```
115

116
**Usage Example - Gemini Developer API:**
117

118
```python
119
from google.genai import Client
120

121
# Initialize with API key
122
client = Client(api_key='YOUR_API_KEY')
123

124
# Generate content
125
response = client.models.generate_content(
126
    model='gemini-2.0-flash',
127
    contents='Explain quantum computing'
128
)
129
print(response.text)
130

131
# Close when done
132
client.close()
133
```
134

135
**Usage Example - Context Manager:**
136

137
```python
138
from google.genai import Client
139

140
with Client(api_key='YOUR_API_KEY') as client:
141
    response = client.models.generate_content(
142
        model='gemini-2.0-flash',
143
        contents='Hello!'
144
    )
145
    print(response.text)
146
# Client automatically closes
147
```
148

149
**Usage Example - Vertex AI:**
150

151
```python
152
from google.genai import Client
153

154
# Initialize for Vertex AI
155
client = Client(
156
    vertexai=True,
157
    project='my-project-id',
158
    location='us-central1'
159
)
160

161
# Generate content
162
response = client.models.generate_content(
163
    model='gemini-2.0-flash',
164
    contents='Explain machine learning'
165
)
166
print(response.text)
167

168
client.close()
169
```
170

171
### Async Client
172

173
Access asynchronous (non-blocking) client for concurrent operations. The async client provides the same API modules as the sync client but with async/await support.
174

175
```python { .api }
176
class AsyncClient:
177
    """
178
    Asynchronous client for making non-blocking requests.
179

180
    Access via Client.aio property. All methods are async and require await.
181
    """
182

183
    @property
184
    def models(self) -> AsyncModels:
185
        """Access async models API."""
186
        ...
187

188
    @property
189
    def chats(self) -> AsyncChats:
190
        """Create async multi-turn chat sessions."""
191
        ...
192

193
    @property
194
    def files(self) -> AsyncFiles:
195
        """Access async file management API."""
196
        ...
197

198
    @property
199
    def caches(self) -> AsyncCaches:
200
        """Access async cached content API."""
201
        ...
202

203
    @property
204
    def batches(self) -> AsyncBatches:
205
        """Access async batch prediction jobs API."""
206
        ...
207

208
    @property
209
    def tunings(self) -> AsyncTunings:
210
        """Access async tuning jobs API."""
211
        ...
212

213
    @property
214
    def file_search_stores(self) -> AsyncFileSearchStores:
215
        """Access async file search stores API."""
216
        ...
217

218
    @property
219
    def live(self) -> AsyncLive:
220
        """Access async live API for real-time bidirectional streaming."""
221
        ...
222

223
    @property
224
    def auth_tokens(self) -> AsyncTokens:
225
        """Access async authentication tokens API."""
226
        ...
227

228
    @property
229
    def operations(self) -> AsyncOperations:
230
        """Access async long-running operations API."""
231
        ...
232

233
    async def aclose(self) -> None:
234
        """
235
        Close the async client explicitly to release resources.
236

237
        Note: This does not close the sync client. Use Client.close() for sync client.
238
        """
239
        ...
240

241
    async def __aenter__(self) -> 'AsyncClient':
242
        """Async context manager entry."""
243
        ...
244

245
    async def __aexit__(self, *args) -> None:
246
        """Async context manager exit."""
247
        ...
248
```
249

250
**Usage Example - Async Client:**
251

252
```python
253
import asyncio
254
from google.genai import Client
255

256
async def main():
257
    client = Client(api_key='YOUR_API_KEY')
258
    async_client = client.aio
259

260
    # Make async request
261
    response = await async_client.models.generate_content(
262
        model='gemini-2.0-flash',
263
        contents='What is AI?'
264
    )
265
    print(response.text)
266

267
    # Close async client
268
    await async_client.aclose()
269
    client.close()
270

271
asyncio.run(main())
272
```
273

274
**Usage Example - Async Context Manager:**
275

276
```python
277
import asyncio
278
from google.genai import Client
279

280
async def main():
281
    client = Client(api_key='YOUR_API_KEY')
282

283
    async with client.aio as async_client:
284
        response = await async_client.models.generate_content(
285
            model='gemini-2.0-flash',
286
            contents='Hello!'
287
        )
288
        print(response.text)
289

290
    client.close()
291

292
asyncio.run(main())
293
```
294

295
### HTTP Configuration
296

297
Configure HTTP client behavior including API version, timeouts, retries, and custom headers.
298

299
```python { .api }
300
class HttpOptions:
301
    """
302
    HTTP client configuration options.
303

304
    Parameters:
305
        api_version (str, optional): API version to use (e.g., 'v1', 'v1beta'). Defaults to 'v1beta'.
306
        base_url (str, optional): Override base URL for API requests.
307
        timeout (float, optional): Request timeout in seconds.
308
        headers (Dict[str, str], optional): Additional HTTP headers for all requests.
309
        retry_options (HttpRetryOptions, optional): Retry configuration for failed requests.
310
    """
311
    api_version: Optional[str] = None
312
    base_url: Optional[str] = None
313
    timeout: Optional[float] = None
314
    headers: Optional[Dict[str, str]] = None
315
    retry_options: Optional[HttpRetryOptions] = None
316

317
class HttpRetryOptions:
318
    """
319
    HTTP retry configuration for handling transient failures.
320

321
    Parameters:
322
        max_retries (int, optional): Maximum number of retry attempts. Defaults to 3.
323
        initial_backoff (float, optional): Initial backoff delay in seconds. Defaults to 1.0.
324
        max_backoff (float, optional): Maximum backoff delay in seconds. Defaults to 60.0.
325
        backoff_multiplier (float, optional): Backoff multiplier for exponential backoff. Defaults to 2.0.
326
        retry_statuses (List[int], optional): HTTP status codes that trigger retries.
327
            Defaults to [408, 429, 500, 502, 503, 504].
328
    """
329
    max_retries: Optional[int] = None
330
    initial_backoff: Optional[float] = None
331
    max_backoff: Optional[float] = None
332
    backoff_multiplier: Optional[float] = None
333
    retry_statuses: Optional[List[int]] = None
334

335
# TypedDict variants for flexible usage
336
class HttpOptionsDict(TypedDict, total=False):
337
    api_version: str
338
    base_url: str
339
    timeout: float
340
    headers: Dict[str, str]
341
    retry_options: Union[HttpRetryOptions, 'HttpRetryOptionsDict']
342

343
class HttpRetryOptionsDict(TypedDict, total=False):
344
    max_retries: int
345
    initial_backoff: float
346
    max_backoff: float
347
    backoff_multiplier: float
348
    retry_statuses: List[int]
349
```
350

351
**Usage Example - HTTP Configuration:**
352

353
```python
354
from google.genai import Client
355
from google.genai.types import HttpOptions, HttpRetryOptions
356

357
# Configure HTTP options
358
http_options = HttpOptions(
359
    api_version='v1',
360
    timeout=30.0,
361
    headers={'User-Agent': 'MyApp/1.0'},
362
    retry_options=HttpRetryOptions(
363
        max_retries=5,
364
        initial_backoff=2.0,
365
        max_backoff=120.0
366
    )
367
)
368

369
client = Client(
370
    api_key='YOUR_API_KEY',
371
    http_options=http_options
372
)
373

374
# All requests use these HTTP options
375
response = client.models.generate_content(
376
    model='gemini-2.0-flash',
377
    contents='Hello'
378
)
379
```
380

381
### Debug Configuration
382

383
Configure client behavior for testing and debugging, including record/replay functionality for deterministic testing.
384

385
```python { .api }
386
class DebugConfig:
387
    """
388
    Configuration options for testing and debugging client network behavior.
389

390
    Parameters:
391
        client_mode (str, optional): Client operation mode. Options:
392
            - 'record': Record API requests and responses to replay files
393
            - 'replay': Replay API responses from recorded files
394
            - 'auto': Automatically record if replay file doesn't exist, otherwise replay
395
            Can be set via GOOGLE_GENAI_CLIENT_MODE environment variable.
396
        replays_directory (str, optional): Directory for storing replay files.
397
            Can be set via GOOGLE_GENAI_REPLAYS_DIRECTORY environment variable.
398
        replay_id (str, optional): Identifier for replay file.
399
            Can be set via GOOGLE_GENAI_REPLAY_ID environment variable.
400
    """
401
    client_mode: Optional[str] = None
402
    replays_directory: Optional[str] = None
403
    replay_id: Optional[str] = None
404
```
405

406
**Usage Example - Debug Configuration:**
407

408
```python
409
from google.genai import Client
410
from google.genai.client import DebugConfig
411

412
# Configure for recording API interactions
413
debug_config = DebugConfig(
414
    client_mode='record',
415
    replays_directory='./test_replays',
416
    replay_id='test_001'
417
)
418

419
client = Client(
420
    api_key='YOUR_API_KEY',
421
    debug_config=debug_config
422
)
423

424
# Requests are recorded to ./test_replays/test_001.json
425
response = client.models.generate_content(
426
    model='gemini-2.0-flash',
427
    contents='Test prompt'
428
)
429

430
# Later, replay the recorded interactions
431
debug_config = DebugConfig(
432
    client_mode='replay',
433
    replays_directory='./test_replays',
434
    replay_id='test_001'
435
)
436

437
# Responses are replayed from recorded file
438
```
439

440
## Types
441

442
```python { .api }
443
from typing import Optional, Union, Dict, List, TypedDict
444
import google.auth.credentials
445

446
# Credentials type from google.auth
447
Credentials = google.auth.credentials.Credentials
448

449
# HTTP response metadata
450
class HttpResponse:
451
    """
452
    HTTP response metadata from API requests.
453

454
    Attributes:
455
        status_code (int): HTTP status code
456
        headers (Dict[str, str]): Response headers
457
        request_url (str): URL of the request
458
    """
459
    status_code: int
460
    headers: Dict[str, str]
461
    request_url: str
462
```
463