Skip to content

GeminiFiles

GeminiFiles wraps the Gemini Files API for uploading, managing, and tracking files. Files uploaded through this API have 48-hour retention and can be referenced in generation requests via GeminiFileReference -- ideal for large documents (up to 50 MB / 1000 pages) or files reused across multiple requests.

Import

import { GeminiClient } from "@modernpath/agent-framework";

const client = new GeminiClient({ apiKey: process.env.GEMINI_API_KEY! });
const files = client.files();

GeminiFiles is accessed via GeminiClient.files() rather than imported directly.

When to Use the Files API

Scenario Recommended Approach
Small file, single use (< 20 MB) Inline via GeminiDocument
Large file (20 -- 50 MB) Upload via Files API, reference via GeminiFileReference
File reused across multiple requests Upload once via Files API, reuse the reference
Persistent knowledge base Use File Search Stores instead

Methods

uploadFromPath()

Upload a file from a local filesystem path.

async uploadFromPath(
  filePath: string,
  options?: UploadFileOptions,
): Promise<GeminiUploadedFile>

Example

const file = await files.uploadFromPath("./report.pdf", {
  mimeType: "application/pdf",
  displayName: "Q4 Incident Report",
});
console.log(file.uri);   // Use this URI in GeminiFileReference
console.log(file.state); // "PROCESSING" or "ACTIVE"

uploadFromBuffer()

Upload a file from an in-memory Buffer.

async uploadFromBuffer(
  buffer: Buffer,
  options: UploadFileOptions & { displayName: string },
): Promise<GeminiUploadedFile>

Example

const buffer = await fetchDocumentFromSharePoint(docId);
const file = await files.uploadFromBuffer(buffer, {
  displayName: "maintenance-guide.docx",
  mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
});

uploadFromUrl()

Download a file from a URL and upload it to the Files API.

async uploadFromUrl(
  url: string,
  options?: UploadFileOptions,
): Promise<GeminiUploadedFile>

The method automatically detects the content type from the HTTP response headers.

uploadAndWait()

Upload a file and poll until it reaches ACTIVE state. This is the recommended method for production use -- large files require processing time before they can be used in generation requests.

async uploadAndWait(
  source: string | Buffer,
  options: UploadFileOptions & { displayName: string },
): Promise<GeminiUploadedFile>
Parameter Type Description
source string \| Buffer File path, URL, or Buffer. URLs are auto-detected by http:// / https:// prefix.
options.displayName string Required. Display name for the uploaded file.
options.mimeType string MIME type (auto-detected if omitted).

Upload and use in generation

const uploaded = await files.uploadAndWait(
  readFileSync("./large-manual.pdf"),
  { displayName: "manual.pdf", mimeType: "application/pdf" },
);

const result = await client.generateContent(
  "Summarize the key maintenance procedures.",
  {
    fileReferences: [{
      fileUri: uploaded.uri!,
      mimeType: uploaded.mimeType!,
      displayName: uploaded.displayName,
    }],
  },
);

waitForActive()

Poll a file until its state transitions to ACTIVE (or FAILED).

async waitForActive(fileName: string): Promise<GeminiUploadedFile>
  • Polls every 2 seconds.
  • Times out after 60 seconds (30 attempts).
  • Throws on FAILED state or timeout.

getFile()

Get file metadata by resource name.

async getFile(name: string): Promise<GeminiUploadedFile>

deleteFile()

Delete a file by resource name.

async deleteFile(name: string): Promise<void>

listFiles()

List all uploaded files.

async listFiles(pageSize?: number): Promise<GeminiUploadedFile[]>

isExpiredOrExpiring()

Check if a file is expired or about to expire.

isExpiredOrExpiring(
  file: GeminiUploadedFile,
  bufferMinutes?: number, // default: 60
): boolean

Returns true if the file has expired or will expire within the specified buffer window.

getExpiryMinutes()

Get the remaining time until a file expires, in minutes.

getExpiryMinutes(file: GeminiUploadedFile): number

Types

UploadFileOptions

interface UploadFileOptions {
  mimeType?: string;     // MIME type of the file
  displayName?: string;  // Human-readable display name
}

GeminiUploadedFile

interface GeminiUploadedFile {
  name: string;             // Resource name (e.g. "files/abc123")
  displayName?: string;     // Display name
  mimeType?: string;        // MIME type
  sizeBytes?: string | number;
  uri?: string;             // URI for use in GeminiFileReference
  state?: "PROCESSING" | "ACTIVE" | "FAILED";
  createTime?: string;      // ISO timestamp
  updateTime?: string;      // ISO timestamp
  expirationTime?: string;  // ISO timestamp (48h after upload)
  error?: { message?: string };
}

File Lifecycle

stateDiagram-v2
    [*] --> PROCESSING: Upload
    PROCESSING --> ACTIVE: Processing complete
    PROCESSING --> FAILED: Processing error
    ACTIVE --> [*]: Expiration (48h) or delete()
    FAILED --> [*]: delete()

48-hour retention

Files uploaded via the Files API are automatically deleted after 48 hours. For persistent storage, use File Search Stores or manage re-uploads using the isExpiredOrExpiring() helper.

Supported Formats

The Files API supports the same formats as inline documents plus additional large-format support:

  • Documents: PDF (up to 1000 pages)
  • Text: Plain text, CSV, HTML, Markdown, JSON, XML
  • Office: DOCX, XLSX, PPTX
  • Images: PNG, JPEG, WebP, HEIC, HEIF