Submodules ¶

Parameters:

model (str) – The model to use for the batch job.
src – The source of the batch job. Currently Gemini Enterprise Agent Platform supports GCS URI(-s) or BigQuery URI. Example: “gs://path/to/input/data” or “bq://projectId.bqDatasetId.bqTableId”. Gemini Develop API supports List of inlined_request, or file name. Example: “files/file_name”.
config (CreateBatchJobConfig) – Optional configuration for the batch job.

Returns:

A BatchJob object that contains details about the batch job.

Usage:

batch_job = await client.aio.batches.create(
    model="gemini-2.0-flash-001",
    src="gs://path/to/input/data",
)

async create_embeddings(*, model, src, config=None)¶

Experimental Creates an asynchronously embedding batch job.

Return type:

Parameters:

model (str) – The model to use for the batch job.
src – Gemini Developer API supports inlined_requests, or file name. Example: “files/file_name”.
config (CreateBatchJobConfig) – Optional configuration for the batch job.

Returns:

A BatchJob object that contains details about the batch job.

Usage:

batch_job = await client.aio.batches.create_embeddings(
    model="text-embedding-004",
    src="files/my_embedding_input",
)
print(batch_job.state)

async delete(*, name, config=None)¶

Deletes a batch job.

Return type:

DeleteResourceJob

Parameters:

name (str) –

A fully-qualified BatchJob resource name or ID. Example: “projects/…/locations/…/batchPredictionJobs/456” or “456”

when project and location are initialized in the client.

Returns:

A DeleteResourceJob object that shows the status of the deletion.

Usage:

await client.aio.batches.delete(name='123456789')

async get(*, name, config=None)¶

Gets a batch job.

Return type:

Parameters:

name (str) –

A fully-qualified BatchJob resource name or ID. Example: “projects/…/locations/…/batchPredictionJobs/456” or “456”

when project and location are initialized in the Gemini Enterprise Agent Platform client. Or “batches/abc” using the Gemini Developer AI client.

Returns:

A BatchJob object that contains details about the batch job.

Usage:

batch_job = await client.aio.batches.get(name='123456789')
print(f"Batch job: {batch_job.name}, state {batch_job.state}")

async list(*, config=None)¶

Lists batch jobs asynchronously.

Return type:: AsyncPager[BatchJob]
Parameters:: config (ListBatchJobsConfig) – Optional configuration for the list request.
Returns:: A Pager object that contains one page of batch jobs. When iterating over the pager, it automatically fetches the next page if there are more.

Usage:

class genai.batches.Batches(api_client_)¶

Bases: BaseModule

cancel(*, name, config=None)¶

Cancels a batch job.

Only available for batch jobs that are running or pending.

Return type:

None

Parameters:

name (str) –

A fully-qualified BatchJob resource name or ID. Example: “projects/…/locations/…/batchPredictionJobs/456” or “456”

when project and location are initialized in the Vertex AI client. Or “batches/abc” using the Gemini Developer AI client.

Usage:

client.batches.cancel(name='123456789')

create(*, model, src, config=None)¶

Creates a batch job.

Return type:

Parameters:

model (str) – The model to use for the batch job.
src – The source of the batch job. Currently Gemini Enterprise Agent Platform supports GCS URI(-s) or BigQuery URI. Example: “gs://path/to/input/data” or “bq://projectId.bqDatasetId.bqTableId”. Gemini Developer API supports List of inlined_request, or file name. Example: “files/file_name”.
config (CreateBatchJobConfig) – Optional configuration for the batch job.

Returns:

A BatchJob object that contains details about the batch job.

Usage:

batch_job = client.batches.create(
    model="gemini-2.0-flash-001",
    src="gs://path/to/input/data",
)
print(batch_job.state)

create_embeddings(*, model, src, config=None)¶

Experimental Creates an embedding batch job.

Return type:

Parameters:

model (str) – The model to use for the batch job.
src – Gemini Developer API supports List of inlined_request, or file name. Example: “files/file_name”.
config (CreateBatchJobConfig) – Optional configuration for the batch job.

Returns:

A BatchJob object that contains details about the batch job.

Usage:

batch_job = client.batches.create_embeddings(
    model="text-embedding-004",
    src="files/my_embedding_input",
)
print(batch_job.state)

delete(*, name, config=None)¶

Deletes a batch job.

Return type:

DeleteResourceJob

Parameters:

name (str) –

A fully-qualified BatchJob resource name or ID. Example: “projects/…/locations/…/batchPredictionJobs/456” or “456”

when project and location are initialized in the client.

Returns:

A DeleteResourceJob object that shows the status of the deletion.

Usage:

client.batches.delete(name='123456789')

get(*, name, config=None)¶

Gets a batch job.

Return type:

GenerateContentResponse

Parameters:

name (str) –

A fully-qualified BatchJob resource name or ID. Example: “projects/…/locations/…/batchPredictionJobs/456” or “456”

when project and location are initialized in the Gemini Enterprise Agent Platform client. Or “batches/abc” using the Gemini Developer AI client.

Returns:

A BatchJob object that contains details about the batch job.

Usage:

batch_job = client.batches.get(name='123456789')
print(f"Batch job: {batch_job.name}, state {batch_job.state}")

list(*, config=None)¶

Lists batch jobs.

Return type:: Pager[BatchJob]
Parameters:: config (ListBatchJobsConfig) – Optional configuration for the list request.
Returns:: A Pager object that contains one page of batch jobs. When iterating over the pager, it automatically fetches the next page if there are more.

Usage:

genai.caches module¶

class genai.caches.AsyncCaches(api_client_)¶

Bases: BaseModule

async create(*, model, config=None)¶

Creates a cached contents resource.

Usage:

contents = ... // Initialize the content to cache.
response = await client.aio.caches.create(
    model= ... // The publisher model id
    contents=contents,
    config={
        'display_name': 'test cache',
        'system_instruction': 'What is the sum of the two pdfs?',
        'ttl': '86400s',
    },
)

Return type:: CachedContent

async delete(*, name, config=None)¶

Deletes cached content.

Usage:

await client.aio.caches.delete(name= ... ) // The server-generated
resource name.

Return type:: DeleteCachedContentResponse

async get(*, name, config=None)¶

Gets cached content configurations.

await client.aio.caches.get(name= ... ) // The server-generated resource
name.

Return type:: CachedContent

async list(*, config=None)¶

Lists cached contents asynchronously.

Return type:: AsyncPager[CachedContent]
Parameters:: config (ListCachedContentsConfig) – Optional configuration for the list request.
Returns:: A Pager object that contains one page of cached contents. When iterating over the pager, it automatically fetches the next page if there are more.

Usage:

async update(*, name, config=None)¶

Updates cached content configurations.

response = await client.aio.caches.update(
    name= ... // The server-generated resource name.
    config={
        'ttl': '7600s',
    },
)

Return type:: CachedContent

class genai.caches.Caches(api_client_)¶

Bases: BaseModule

create(*, model, config=None)¶

Creates a cached contents resource.

Usage:

contents = ... // Initialize the content to cache.
response = client.caches.create(
    model= ... // The publisher model id
    contents=contents,
    config={
        'display_name': 'test cache',
        'system_instruction': 'What is the sum of the two pdfs?',
        'ttl': '86400s',
    },
)

Return type:: CachedContent

delete(*, name, config=None)¶

Deletes cached content.

Usage:

client.caches.delete(name= ... ) // The server-generated resource name.

Return type:: DeleteCachedContentResponse

get(*, name, config=None)¶

Gets cached content configurations.

client.caches.get(name= ... ) // The server-generated resource name.

Return type:: CachedContent

list(*, config=None)¶

Lists cached contents.

Return type:: Pager[CachedContent]
Parameters:: config (ListCachedContentsConfig) – Optional configuration for the list request.
Returns:: A Pager object that contains one page of cached contents. When iterating over the pager, it automatically fetches the next page if there are more.

Usage:

update(*, name, config=None)¶

Updates cached content configurations.

response = client.caches.update(
    name= ... // The server-generated resource name.
    config={
        'ttl': '7600s',
    },
)

Return type:: CachedContent

genai.chats module¶

class genai.chats.AsyncChat(*, modules, model, config=None, history)¶

Bases: _BaseChat

Async chat session.

async send_message(message, config=None)¶

Sends the conversation history with the additional message and returns model’s response.

Return type:

Parameters:

message – The message to send to the model.
config – Optional config to override the default Chat config for this request.

Returns:

The model’s response.

Usage:

chat = client.aio.chats.create(model='gemini-2.0-flash')
response = await chat.send_message('tell me a story')

async send_message_stream(message, config=None)¶

Sends the conversation history with the additional message and yields the model’s response in chunks.

Return type:

AsyncIterator[GenerateContentResponse]

Parameters:

message – The message to send to the model.
config – Optional config to override the default Chat config for this request.

Yields:

The model’s response in chunks.

Usage:

chat = client.aio.chats.create(model='gemini-2.0-flash')
async for chunk in await chat.send_message_stream('tell me a story'):
  print(chunk.text)

class genai.chats.AsyncChats(modules)¶

Bases: object

A util class to create async chat sessions.

create(*, model, config=None, history=None)¶

Creates a new chat session.

Return type:

AsyncChat

Parameters:

model – The model to use for the chat.
config – The configuration to use for the generate content request.
history – The history to use for the chat.

Returns:

A new chat session.

class genai.chats.Chat(*, modules, model, config=None, history)¶

Bases: _BaseChat

Chat session.

send_message(message, config=None)¶

Sends the conversation history with the additional message and returns the model’s response.

Return type:

GenerateContentResponse

Parameters:

message – The message to send to the model.
config – Optional config to override the default Chat config for this request.

Returns:

The model’s response.

Usage:

chat = client.chats.create(model='gemini-2.0-flash')
response = chat.send_message('tell me a story')

send_message_stream(message, config=None)¶

Sends the conversation history with the additional message and yields the model’s response in chunks.

Return type:

Iterator[GenerateContentResponse]

Parameters:

message – The message to send to the model.
config – Optional config to override the default Chat config for this request.

Yields:

The model’s response in chunks.

Usage:

chat = client.chats.create(model='gemini-2.0-flash')
for chunk in chat.send_message_stream('tell me a story'):
  print(chunk.text)

class genai.chats.Chats(modules)¶

Bases: object

A util class to create chat sessions.

create(*, model, config=None, history=None)¶

Creates a new chat session.

Return type:

Chat

Parameters:

model – The model to use for the chat.
config – The configuration to use for the generate content request.
history – The history to use for the chat.

Returns:

A new chat session.

genai.file_search_stores module¶

class genai.file_search_stores.AsyncFileSearchStores(api_client_)¶

Bases: BaseModule

async create(*, config=None)¶

Creates a File Search Store.

Return type:: FileSearchStore
Parameters:: config (CreateFileSearchStoreConfig | None) – Optional parameters for the request.
Returns:: FileSearchStore

async delete(*, name, config=None)¶

Deletes a FileSearchStore.

Return type:

None

Parameters:

name (str) – The resource name of the FileSearchStore. Example: FileSearchStores/my-file-search-store-123
config (DeleteFileSearchStoreConfig | None) – Optional parameters for the request.

Returns:

None

property documents: AsyncDocuments¶

async download_media(*, media_id, config=None)¶

Downloads media using a Media ID.

Return type:: bytes

The media_id has the format:: fileSearchStores/<store>/media/<blob_id>
This is mapped to the DownloadMedia RPC which expects:: GET /{name=fileSearchStores//media/}

Parameters:

media_id – The Media ID from grounding metadata.
config – Optional configuration for the download.

Returns:

The media data.

Return type:

bytes

async get(*, name, config=None)¶

Gets metadata about a FileSearchStore.

Return type:

FileSearchStore

Parameters:

name (str) – The resource name of the FileSearchStore. Example: FileSearchStores/my-file-search-store-123
config (GetFileSearchStoreConfig | None) – Optional parameters for the request.

Returns:

A FileSearchStore object containing the metadata.

async import_file(*, file_search_store_name, file_name, config=None)¶

Imports a File from File Service to a FileSearchStore.

This is a long-running operation, see aip.dev/151

Return type:

ImportFileOperation

Parameters:

file_search_store_name (str) – The resource name of the FileSearchStore. Example: fileSearchStores/my-file-search-store-123
file_name (str) – The resource name of the File to import. Example: files/abc-123
config (ImportFileConfig | None) – Optional parameters for the request.

Returns:

ImportFileOperation.

async list(*, config=None)¶

Lists FileSearchStores asynchronously.

Return type:: AsyncPager[FileSearchStore]
Parameters:: config (ListFileSearchStoresConfig) – Optional parameters for the request, such as page_size.
Returns:: A Pager object that contains one page of FileSearchStores. When iterating over the pager, it automatically fetches the next page if there are more.

Usage:

async upload_to_file_search_store(*, file_search_store_name, file, config=None)¶

Calls the API to upload a file to the given file search store.

Return type:

UploadToFileSearchStoreOperation

Parameters:

file_search_store_name – The resource name of the FileSearchStore. Example: fileSearchStores/file-search-store-123
file – A path to the file or an IOBase object to be uploaded. If it’s an IOBase object, it must be opened in blocking (the default) mode and binary mode. In other words, do not use non-blocking mode or text mode. The given stream must be seekable, that is, it must be able to call seek() on ‘path’.
config – Optional parameters to set diplay_name, mime_type and others.

class genai.file_search_stores.FileSearchStores(api_client_)¶

Bases: BaseModule

create(*, config=None)¶

Creates a File Search Store.

Return type:: FileSearchStore
Parameters:: config (CreateFileSearchStoreConfig | None) – Optional parameters for the request.
Returns:: FileSearchStore

delete(*, name, config=None)¶

Deletes a FileSearchStore.

Return type:

None

Parameters:

name (str) – The resource name of the FileSearchStore. Example: FileSearchStores/my-file-search-store-123
config (DeleteFileSearchStoreConfig | None) – Optional parameters for the request.

Returns:

None

property documents: Documents¶

download_media(*, media_id, config=None)¶

Downloads media using a Media ID.

Return type:: bytes

The media_id has the format:: fileSearchStores/<store>/media/<blob_id>
This is mapped to the DownloadMedia RPC which expects:: GET /{name=fileSearchStores//media/}

Parameters:

media_id – The Media ID from grounding metadata.
config – Optional configuration for the download.

Returns:

The media data.

Return type:

bytes

get(*, name, config=None)¶

Gets metadata about a FileSearchStore.

Return type:

FileSearchStore

Parameters:

name (str) – The resource name of the FileSearchStore. Example: FileSearchStores/my-file-search-store-123
config (GetFileSearchStoreConfig | None) – Optional parameters for the request.

Returns:

A FileSearchStore object containing the metadata.

import_file(*, file_search_store_name, file_name, config=None)¶

Imports a File from File Service to a FileSearchStore.

This is a long-running operation, see aip.dev/151

Return type:

ImportFileOperation

Parameters:

file_search_store_name (str) – The resource name of the FileSearchStore. Example: fileSearchStores/my-file-search-store-123
file_name (str) – The resource name of the File to import. Example: files/abc-123
config (ImportFileConfig | None) – Optional parameters for the request.

Returns:

ImportFileOperation.

list(*, config=None)¶

Lists FileSearchStores.

Return type:: Pager[FileSearchStore]
Parameters:: config (ListFileSearchStoresConfig) – Optional configuration for the list request.
Returns:: A Pager object that contains one page of file search stores. When iterating over the pager, it automatically fetches the next page if there are more.

Usage:

upload_to_file_search_store(*, file_search_store_name, file, config=None)¶

Calls the API to upload a file to the given file search store.

Return type:

UploadToFileSearchStoreOperation

Parameters:

file_search_store_name – The resource name of the FileSearchStore. Example: fileSearchStores/file-search-store-123
file – A path to the file or an IOBase object to be uploaded. If it’s an IOBase object, it must be opened in blocking (the default) mode and binary mode. In other words, do not use non-blocking mode or text mode. The given stream must be seekable, that is, it must be able to call seek() on ‘path’.
config – Optional parameters to set diplay_name, mime_type, and others.

genai.files module¶

class genai.files.AsyncFiles(api_client_)¶

Bases: BaseModule

async delete(*, name, config=None)¶

Deletes a remotely stored file.

Return type:

DeleteFileResponse

Parameters:

name (str) – The name identifier for the file to delete.
config (DeleteFileConfig) – Optional, configuration for the delete method.

Returns:

The response for the delete method

Return type:

DeleteFileResponse

Usage:

await client.aio.files.delete(name='files/...')

async download(*, file, config=None)¶

Downloads a file’s data from the file service.

The Gemini Enterprise Agent Platform implementation of the API foes not include the file service.

Files created by upload can’t be downloaded. You can tell which files are downloadable by checking the download_uri property.

Return type:

bytes

Parameters:

File (str) – A file name, uri, or file object. Identifying which file to download.
config (DownloadFileConfigOrDict) – Optional, configuration for the get method.

Returns:

The file data as bytes.

Return type:

Usage:

for file client.files.list():
  if file.download_uri is not None:
    break
else:
  raise ValueError('No files found with a `download_uri`.')
data = client.files.download(file=file)
# data = client.files.download(file=file.name)
# data = client.files.download(file=file.uri)

async get(*, name, config=None)¶

Retrieves the file information from the service.

Return type:

Parameters:

name (str) – The name identifier for the file to retrieve.
config (GetFileConfig) – Optional, configuration for the get method.

Returns:

The file information.

Return type:

Usage:

file = await client.aio.files.get(name='files/...')
print(file.uri)

async list(*, config=None)¶

Lists all files from the service asynchronously.

Return type:: AsyncPager[File]
Parameters:: config (ListFilesConfig) – Optional, configuration for the list method.
Returns:: A Pager object that contains one page of files. When iterating over the pager, it automatically fetches the next page if there are more.

Usage:

async for file in await client.aio.files.list(config={'page_size': 10}):
  print(file.name)

async register_files(*, auth, uris, config=None)¶

Registers gcs files with the file service.

Return type:: RegisterFilesResponse

async upload(*, file, config=None)¶

Calls the API to upload a file asynchronously using a supported file service.

Return type:

Parameters:

file – A path to the file or an IOBase object to be uploaded. If it’s an IOBase object, it must be opened in blocking (the default) mode and binary mode. In other words, do not use non-blocking mode or text mode. The given stream must be seekable, that is, it must be able to call seek() on ‘path’.
config – Optional parameters to set diplay_name, mime_type, and name.

class genai.files.Files(api_client_)¶

Bases: BaseModule

delete(*, name, config=None)¶

Deletes a remotely stored file.

Return type:

DeleteFileResponse

Parameters:

name (str) – The name identifier for the file to delete.
config (DeleteFileConfig) – Optional, configuration for the delete method.

Returns:

The response for the delete method

Return type:

DeleteFileResponse

Usage:

client.files.delete(name='files/...')

download(*, file, config=None)¶

Downloads a file’s data from storage.

Files created by upload can’t be downloaded. You can tell which files are downloadable by checking the source or download_uri property.

Note: This method returns the data as bytes. For Video and GeneratedVideo objects there is an additional side effect, that it also sets the video_bytes property on the Video object.

Return type:

bytes

Parameters:

file (str) – A file name, uri, or file object. Identifying which file to download.
config (DownloadFileConfigOrDict) – Optional, configuration for the get method.

Returns:

The file data as bytes.

Return type:

Usage:

for file client.files.list():
  if file.download_uri is not None:
    break
else:
  raise ValueError('No files found with a `download_uri`.')
data = client.files.download(file=file)
# data = client.files.download(file=file.name)
# data = client.files.download(file=file.download_uri)

video = types.Video(uri=file.uri)
video_bytes = client.files.download(file=video)
video.video_bytes

get(*, name, config=None)¶

Retrieves the file information from the service.

Return type:

Parameters:

name (str) – The name identifier for the file to retrieve.
config (GetFileConfig) – Optional, configuration for the get method.

Returns:

The file information.

Return type:

Usage:

file = client.files.get(name='files/...')
print(file.uri)

list(*, config=None)¶

Lists all files from the service.

Return type:: Pager[File]
Parameters:: config (ListFilesConfig) – Optional, configuration for the list method.
Returns:: A Pager object that contains one page of files. When iterating over the pager, it automatically fetches the next page if there are more.

Usage:

for file in client.files.list(config={'page_size': 10}):
  print(file.name)

register_files(*, auth, uris, config=None)¶

Registers gcs files with the file service.

Return type:: RegisterFilesResponse

upload(*, file, config=None)¶

Calls the API to upload a file using a supported file service.

Return type: