Files Client - gunpal5/Google_GenerativeAI GitHub Wiki

Introduction

The FileClient provides functionality to upload, retrieve, and manage files for use with Gemini models. This page explains how to use the FileClient to interact with the Gemini Files API.

Details

The FileClient offers methods for uploading files (from a file path or a stream), retrieving file metadata, listing files, and deleting files.

Using Files Property on GeminiModel

When working with the Gemini SDK, the GeminiModel class comes with an initialized Files property of type FileClient. This means you can use the methods directly on the GeminiModel.Files property, without creating or initializing a separate FileClient.

For example:

// Assuming you have an instance of GeminiModel called 'geminiModel'
// You can directly call the FileClient methods through geminiModel.Files

string filePath = "path/to/my/file.txt"; // Replace with the actual file path

try
{
    var remoteFile = await geminiModel.Files.UploadFileAsync(
        filePath,
        progressCallback: (progress) =>
        {
            Console.WriteLine($"Upload Progress: {progress:F2}%");
        }
    );

    Console.WriteLine($"File uploaded successfully. Remote File Name: {remoteFile.Name}");
}
catch (Exception ex)
{
    Console.WriteLine($"Error uploading file: {ex.Message}");
}

With this approach, you do not need a separate new FileClient() call; the methods are already available from your GeminiModel instance.

1. Uploading Files

Uploading from a File Path (UploadFileAsync)

This method uploads a file from the specified path.

// Assuming you have an instance of FileClient called 'fileClient'
string filePath = "path/to/my/file.txt"; // Replace with the actual file path

try
{
    var remoteFile = await fileClient.UploadFileAsync(
        filePath,
        progressCallback: (progress) =>
        {
            Console.WriteLine($"Upload Progress: {progress:F2}%");
        }
    );

    Console.WriteLine($"File uploaded successfully. Remote File Name: {remoteFile.Name}");
}
catch (Exception ex)
{
    Console.WriteLine($"Error uploading file: {ex.Message}");
}

Uploading from a Stream (UploadStreamAsync)

This method uploads a file from a provided stream.

// Assuming you have an instance of FileClient called 'fileClient'
using var fileStream = File.OpenRead("path/to/my/file.txt"); // Or any other stream source
string displayName = "my_uploaded_file";
string mimeType = "text/plain"; // Or the appropriate MIME type

try
{
    var remoteFile = await fileClient.UploadStreamAsync(
        fileStream,
        displayName,
        mimeType,
        progressCallback: (progress) =>
        {
            Console.WriteLine($"Upload Progress: {progress:F2}%");
        }
    );

    Console.WriteLine($"File uploaded successfully. Remote File Name: {remoteFile.Name}");
}
catch (Exception ex)
{
    Console.WriteLine($"Error uploading file: {ex.Message}");
}

2. Retrieving File Metadata (GetFileAsync)

This method retrieves the metadata for a specific remote file.

// Assuming you have an instance of FileClient called 'fileClient'
string fileName = "files/your-file-id"; // Replace with the actual file name/ID

try
{
    var remoteFile = await fileClient.GetFileAsync(fileName);
    Console.WriteLine($"File Name: {remoteFile.Name}, Size: {remoteFile.SizeBytes}");
}
catch (Exception ex)
{
    Console.WriteLine($"Error retrieving file metadata: {ex.Message}");
}

3. Listing Files (ListFilesAsync)

This method lists the files owned by the project. You can use pageSize and pageToken for pagination.

// Assuming you have an instance of FileClient called 'fileClient'
try
{
    var response = await fileClient.ListFilesAsync(pageSize: 20); // Optional page size

    foreach (var file in response.Files)
    {
        Console.WriteLine($"File Name: {file.Name}, Display Name: {file.DisplayName}");
    }

    if (!string.IsNullOrEmpty(response.NextPageToken))
    {
        // Use response.NextPageToken to retrieve the next page of results
        Console.WriteLine($"Next Page Token: {response.NextPageToken}");
    }
}
catch (Exception ex)
{
    Console.WriteLine($"Error listing files: {ex.Message}");
}

4. Deleting Files (DeleteFileAsync)

This method deletes a remote file.

// Assuming you have an instance of FileClient called 'fileClient'
string fileName = "files/your-file-id"; // Replace with the actual file name/ID

try
{
    await fileClient.DeleteFileAsync(fileName);
    Console.WriteLine("File deleted successfully.");
}
catch (Exception ex)
{
    Console.WriteLine($"Error deleting file: {ex.Message}");
}

5. Waiting for File State Active (AwaitForFileStateActiveAsync)

This method waits until a file is in the ACTIVE state.

// Assuming you have an instance of FileClient called 'fileClient'
var remoteFile = await fileClient.GetFileAsync("files/your-file-id");
await fileClient.AwaitForFileStateActiveAsync(remoteFile, 60, cancellationToken: default);
Console.WriteLine("File is now active.");

Important Considerations

  • File Size Limits: There are limits on the size of files that can be uploaded. The FileTooLargeException is thrown if the file exceeds the limit.
  • MIME Types: Ensure you use correct MIME types when uploading files from a stream.
  • Error Handling: Implement proper error handling to manage potential exceptions during file operations.
  • Authentication: The FileClient relies on the same authentication mechanism as other Gemini API clients. Make sure you have configured authentication correctly.

API Reference