tessl/maven-com-google-genai--google-genai

Java idiomatic SDK for the Gemini Developer APIs and Vertex AI APIs

Overview

Eval results

Files

File Management

Name: tessl/maven-com-google-genai--google-genai
Author: tessl

Upload, retrieve, list, download, and delete files for use with Gemini models. The Files API supports images, audio, video, and documents up to 2GB per file.

Core Imports

import com.google.genai.Files;
import com.google.genai.AsyncFiles;
import com.google.genai.Pager;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import com.google.genai.types.GetFileConfig;
import com.google.genai.types.DeleteFileConfig;
import com.google.genai.types.DownloadFileConfig;
import com.google.genai.types.ListFilesConfig;
import com.google.genai.types.DeleteFileResponse;
import java.util.concurrent.CompletableFuture;

Files Service

package com.google.genai;

public final class Files {
  // Upload methods
  public File upload(java.io.File file, UploadFileConfig config);
  public File upload(byte[] bytes, UploadFileConfig config);
  public File upload(InputStream inputStream, long size, UploadFileConfig config);
  public File upload(String filePath, UploadFileConfig config);

  // Retrieve and list
  public File get(String name, GetFileConfig config);
  public Pager<File> list(ListFilesConfig config);

  // Download methods
  public void download(String fileName, String downloadPath, DownloadFileConfig config);
  public void download(Video video, String downloadPath, DownloadFileConfig config);
  public void download(File file, String downloadPath, DownloadFileConfig config);
  public void download(GeneratedVideo generatedVideo, String downloadPath, DownloadFileConfig config);

  // Delete
  public DeleteFileResponse delete(String name, DeleteFileConfig config);
}

Async Files Service

package com.google.genai;

public final class AsyncFiles {
  public CompletableFuture<File> upload(java.io.File file, UploadFileConfig config);
  public CompletableFuture<File> upload(byte[] bytes, UploadFileConfig config);
  public CompletableFuture<File> upload(InputStream inputStream, long size, UploadFileConfig config);
  public CompletableFuture<File> upload(String filePath, UploadFileConfig config);

  public CompletableFuture<File> get(String name, GetFileConfig config);
  public CompletableFuture<AsyncPager<File>> list(ListFilesConfig config);

  public CompletableFuture<Void> download(String fileName, String downloadPath, DownloadFileConfig config);
  public CompletableFuture<Void> download(Video video, String downloadPath, DownloadFileConfig config);
  public CompletableFuture<Void> download(File file, String downloadPath, DownloadFileConfig config);
  public CompletableFuture<Void> download(GeneratedVideo generatedVideo, String downloadPath, DownloadFileConfig config);

  public CompletableFuture<DeleteFileResponse> delete(String name, DeleteFileConfig config);
}

File Type

package com.google.genai.types;

public final class File {
  public static Builder builder();

  public Optional<String> name();
  public Optional<String> displayName();
  public Optional<String> mimeType();
  public Optional<String> sizeBytes();
  public Optional<String> createTime();
  public Optional<String> updateTime();
  public Optional<String> expirationTime();
  public Optional<String> sha256Hash();
  public Optional<String> uri();
  public Optional<String> state();
  public Optional<FileStatus> status();
  public Optional<VideoMetadata> videoMetadata();
}

File Status

package com.google.genai.types;

public final class FileStatus {
  public Optional<Status> error();
  public Optional<String> state();
}

Video Metadata

package com.google.genai.types;

public final class VideoMetadata {
  public Optional<String> videoDuration();
}

Upload File Config

package com.google.genai.types;

public final class UploadFileConfig {
  public static Builder builder();

  public Optional<String> mimeType();
  public Optional<String> displayName();
  public Optional<HttpOptions> httpOptions();
}

Get File Config

package com.google.genai.types;

public final class GetFileConfig {
  public static Builder builder();

  public Optional<HttpOptions> httpOptions();
}

List Files Config

package com.google.genai.types;

public final class ListFilesConfig {
  public static Builder builder();

  public Optional<Integer> pageSize();
  public Optional<String> pageToken();
  public Optional<HttpOptions> httpOptions();
}

Download File Config

package com.google.genai.types;

public final class DownloadFileConfig {
  public static Builder builder();

  public Optional<HttpOptions> httpOptions();
}

Delete File Response

package com.google.genai.types;

public final class DeleteFileResponse {
  public Optional<HttpResponse> sdkHttpResponse();
}

Upload Files

Upload from File Object

import com.google.genai.Client;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.io.File as JavaFile;

Client client = new Client();

UploadFileConfig config = UploadFileConfig.builder()
    .mimeType("image/jpeg")
    .displayName("My Image")
    .build();

File file = client.files.upload(
    new JavaFile("path/to/image.jpg"),
    config
);

System.out.println("Uploaded file: " + file.name().orElse("N/A"));
System.out.println("URI: " + file.uri().orElse("N/A"));

Upload from File Path

File file = client.files.upload(
    "path/to/document.pdf",
    UploadFileConfig.builder()
        .mimeType("application/pdf")
        .displayName("Research Paper")
        .build()
);

Upload from Bytes

import java.nio.file.Files;
import java.nio.file.Paths;

byte[] imageBytes = Files.readAllBytes(Paths.get("path/to/image.png"));

File file = client.files.upload(
    imageBytes,
    UploadFileConfig.builder()
        .mimeType("image/png")
        .displayName("Screenshot")
        .build()
);

Upload from InputStream

import java.io.FileInputStream;
import java.io.InputStream;

try (InputStream inputStream = new FileInputStream("path/to/video.mp4")) {
    long fileSize = new JavaFile("path/to/video.mp4").length();

    File file = client.files.upload(
        inputStream,
        fileSize,
        UploadFileConfig.builder()
            .mimeType("video/mp4")
            .displayName("Demo Video")
            .build()
    );

    System.out.println("Uploaded: " + file.name().orElse("N/A"));
}

Check Upload Status

File file = client.files.upload("path/to/large-video.mp4", null);

// For large files, check processing status
while (file.state().orElse("").equals("PROCESSING")) {
    Thread.sleep(5000);
    file = client.files.get(file.name().get(), null);
    System.out.println("File state: " + file.state().orElse("N/A"));
}

if (file.state().orElse("").equals("ACTIVE")) {
    System.out.println("File ready to use");
}

Retrieve Files

Get File by Name

File file = client.files.get("files/abc123", null);

System.out.println("Name: " + file.name().orElse("N/A"));
System.out.println("Display name: " + file.displayName().orElse("N/A"));
System.out.println("MIME type: " + file.mimeType().orElse("N/A"));
System.out.println("Size: " + file.sizeBytes().orElse("N/A") + " bytes");
System.out.println("State: " + file.state().orElse("N/A"));
System.out.println("Created: " + file.createTime().orElse("N/A"));
System.out.println("Expires: " + file.expirationTime().orElse("N/A"));

Access Video Metadata

File videoFile = client.files.get("files/video123", null);

videoFile.videoMetadata().ifPresent(metadata -> {
    System.out.println("Video duration: " + metadata.videoDuration().orElse("N/A"));
});

List Files

Basic Listing

import com.google.genai.Pager;

Pager<File> pager = client.files.list(null);

for (File file : pager) {
    System.out.println("File: " + file.displayName().orElse("N/A"));
    System.out.println("  Name: " + file.name().orElse("N/A"));
    System.out.println("  Type: " + file.mimeType().orElse("N/A"));
    System.out.println("  Size: " + file.sizeBytes().orElse("N/A"));
    System.out.println();
}

Paginated Listing

ListFilesConfig config = ListFilesConfig.builder()
    .pageSize(10)
    .build();

Pager<File> pager = client.files.list(config);

// Get first page
ImmutableList<File> firstPage = pager.page();
System.out.println("Files in first page: " + firstPage.size());

// Get next page
if (firstPage.size() == 10) {
    ImmutableList<File> secondPage = pager.nextPage();
    System.out.println("Files in second page: " + secondPage.size());
}

Iterate All Files

Pager<File> pager = client.files.list(ListFilesConfig.builder().pageSize(100).build());

int count = 0;
for (File file : pager) {
    count++;
    System.out.println(count + ". " + file.displayName().orElse("N/A"));
}
System.out.println("Total files: " + count);

Download Files

Download by File Name

client.files.download(
    "files/abc123",
    "path/to/download/file.jpg",
    null
);

System.out.println("File downloaded successfully");

Download by File Object

File file = client.files.get("files/abc123", null);

client.files.download(
    file,
    "path/to/download/" + file.displayName().orElse("file"),
    null
);

Download Video

import com.google.genai.types.Video;

Video video = Video.builder()
    .videoUri("files/video123")
    .build();

client.files.download(
    video,
    "path/to/download/video.mp4",
    null
);

Download Generated Video

import com.google.genai.types.GeneratedVideo;

// Assume you have a generated video from video generation
GeneratedVideo generatedVideo = /* ... */;

client.files.download(
    generatedVideo,
    "path/to/download/generated-video.mp4",
    null
);

Delete Files

Delete by Name

DeleteFileResponse response = client.files.delete("files/abc123", null);
System.out.println("File deleted");

Delete After Use

// Upload file
File file = client.files.upload("path/to/temp.jpg", null);

try {
    // Use file for generation
    Content content = Content.fromParts(
        Part.fromText("Describe this image"),
        Part.fromUri(file.uri().get(), file.mimeType().get())
    );

    GenerateContentResponse response = client.models.generateContent(
        "gemini-2.0-flash",
        content,
        null
    );

    System.out.println(response.text());
} finally {
    // Clean up
    client.files.delete(file.name().get(), null);
    System.out.println("Temporary file deleted");
}

Use Files with Generation

Image File with Generation

// Upload image
File imageFile = client.files.upload(
    "path/to/image.jpg",
    UploadFileConfig.builder().mimeType("image/jpeg").build()
);

// Use in generation
Content content = Content.fromParts(
    Part.fromText("What's in this image?"),
    Part.fromFileData(FileData.builder()
        .fileUri(imageFile.uri().get())
        .mimeType(imageFile.mimeType().get())
        .build())
);

GenerateContentResponse response = client.models.generateContent(
    "gemini-2.0-flash",
    content,
    null
);

System.out.println(response.text());

Multiple Files

// Upload multiple files
File image1 = client.files.upload("image1.jpg", null);
File image2 = client.files.upload("image2.jpg", null);
File document = client.files.upload("document.pdf", null);

// Use all in generation
Content content = Content.fromParts(
    Part.fromText("Compare these images and summarize the document:"),
    Part.fromUri(image1.uri().get(), image1.mimeType().get()),
    Part.fromUri(image2.uri().get(), image2.mimeType().get()),
    Part.fromUri(document.uri().get(), document.mimeType().get())
);

GenerateContentResponse response = client.models.generateContent(
    "gemini-2.0-flash",
    content,
    null
);

Audio File

File audioFile = client.files.upload(
    "audio.mp3",
    UploadFileConfig.builder()
        .mimeType("audio/mpeg")
        .displayName("Interview Recording")
        .build()
);

Content content = Content.fromParts(
    Part.fromText("Transcribe and summarize this audio"),
    Part.fromUri(audioFile.uri().get(), audioFile.mimeType().get())
);

GenerateContentResponse response = client.models.generateContent(
    "gemini-2.0-flash",
    content,
    null
);

Async File Operations

Async Upload

import java.util.concurrent.CompletableFuture;

CompletableFuture<File> future = client.async.files.upload(
    "path/to/file.jpg",
    UploadFileConfig.builder().mimeType("image/jpeg").build()
);

future.thenAccept(file -> {
    System.out.println("Uploaded: " + file.name().orElse("N/A"));
}).exceptionally(error -> {
    System.err.println("Upload failed: " + error.getMessage());
    return null;
});

Async List

CompletableFuture<AsyncPager<File>> future = client.async.files.list(null);

future.thenAccept(pager -> {
    pager.forEach(file -> {
        System.out.println("File: " + file.displayName().orElse("N/A"));
    });
});

Async Download

CompletableFuture<Void> future = client.async.files.download(
    "files/abc123",
    "path/to/download.jpg",
    null
);

future.thenRun(() -> {
    System.out.println("Download complete");
});

File Lifecycle

Files uploaded to the Gemini API are automatically deleted after 48 hours.

File file = client.files.upload("path/to/file.jpg", null);

// File info includes expiration time
file.expirationTime().ifPresent(expiration -> {
    System.out.println("File will expire at: " + expiration);
});

// File will be automatically deleted after 48 hours
// Or manually delete earlier:
client.files.delete(file.name().get(), null);

Error Handling

import com.google.genai.errors.GenAiIOException;
import com.google.genai.errors.ApiException;

try {
    File file = client.files.upload("path/to/large-file.mp4", null);
    System.out.println("Upload successful");
} catch (GenAiIOException e) {
    System.err.println("I/O error: " + e.getMessage());
} catch (ApiException e) {
    System.err.println("API error: " + e.code() + " - " + e.message());
}

Best Practices

Check File Size Limits

import java.io.File as JavaFile;

JavaFile localFile = new JavaFile("path/to/file.mp4");
long fileSizeBytes = localFile.length();
long maxSize = 2L * 1024 * 1024 * 1024; // 2GB

if (fileSizeBytes > maxSize) {
    System.err.println("File too large: " + fileSizeBytes + " bytes");
} else {
    File uploadedFile = client.files.upload(localFile, null);
}

Wait for Processing

File file = client.files.upload("large-video.mp4", null);

// Poll until processing complete
int maxAttempts = 60;
int attempt = 0;
while (attempt < maxAttempts && "PROCESSING".equals(file.state().orElse(""))) {
    Thread.sleep(5000);
    file = client.files.get(file.name().get(), null);
    attempt++;
}

if ("ACTIVE".equals(file.state().orElse(""))) {
    // File ready to use
} else if ("FAILED".equals(file.state().orElse(""))) {
    file.status().flatMap(FileStatus::error).ifPresent(error -> {
        System.err.println("Processing failed: " + error);
    });
}

Batch Upload Multiple Files

import java.util.List;
import java.util.stream.Collectors;
import java.util.concurrent.CompletableFuture;

List<String> filePaths = List.of(
    "image1.jpg", "image2.jpg", "image3.jpg"
);

// Upload all files asynchronously
List<CompletableFuture<File>> futures = filePaths.stream()
    .map(path -> client.async.files.upload(path, null))
    .collect(Collectors.toList());

// Wait for all uploads
CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
    .thenRun(() -> {
        List<File> files = futures.stream()
            .map(CompletableFuture::join)
            .collect(Collectors.toList());

        System.out.println("Uploaded " + files.size() + " files");
    });

Install with Tessl CLI

npx tessl i tessl/maven-com-google-genai--google-genai

docs

batch-operations.md

caching.md

chat-sessions.md

client-configuration.md

content-generation.md

embeddings-tokens.md

error-handling.md

file-search-stores.md