gemini-file-api

majiayu000's avatarfrom majiayu000

Work with Gemini File API for document caching and efficient multi-query workflows. Use when discussing file uploads, caching strategies, token optimization, or comparing File API vs inline document approaches.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 5, 2026
[Files and Documents]

When & Why to Use This Skill

This Claude skill integrates the Gemini File API to streamline high-volume document processing and intelligent caching. By leveraging persistent file URIs with a 48-hour TTL, it optimizes multi-query workflows, significantly reduces token consumption, and minimizes latency. It is an essential tool for developers and researchers who need to perform repetitive, deep analysis on large datasets or complex documents without the overhead of redundant uploads.

Use Cases

  • Multi-Query Document Analysis: Conduct extensive follow-up questioning on large files, such as legal contracts or technical specifications, by uploading once and referencing the cached URI for all subsequent prompts.
  • Token and Cost Optimization: Reduce API operational costs in long-running AI sessions by switching from inline byte transfers to the Gemini File API, which becomes more cost-effective after approximately seven queries.
  • Automated Financial Auditing: Streamline the processing of multiple financial records (e.g., W2s, paystubs, or bank statements) using parallel uploads for rapid data extraction and mortgage underwriting workflows.
  • AI Workflow Benchmarking: Compare and evaluate the performance, latency, and cost-efficiency of File API versus inline document approaches to determine the optimal architecture for specific AI agent tasks.
namegemini-file-api
descriptionWork with Gemini File API for document caching and efficient multi-query workflows. Use when discussing file uploads, caching strategies, token optimization, or comparing File API vs inline document approaches.

Gemini File API Integration

Purpose

Understand and work with Gemini's File API for efficient document processing.

Architecture Overview

┌─────────────────────────────────────────────┐
│  Document Upload                            │
│  UploadFile() -> Gemini File API           │
│  Returns: URI with 48hr TTL                │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│  FileCache (in-memory)                      │
│  Prevents re-uploads within session        │
│  Key: file path, Value: FileReference      │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│  GenerateContent()                          │
│  References files by URI (not bytes)       │
│  Reuse same URI for multiple queries       │
└─────────────────────────────────────────────┘

Client Usage

Creating a Client

// Reads GEMINI_API_KEY from environment
client, err := gemini.NewClient(ctx)
if err != nil {
    return err
}
defer client.Close()

Uploading Files

Single file:

ref, err := client.UploadFile(ctx, "/path/to/doc.pdf", "application/pdf")
// ref.URI is reusable for 48 hours

Multiple files (parallel upload):

paths := []string{"/path/to/w2.pdf", "/path/to/paystub.pdf"}
mimeTypes := map[string]string{
    "/path/to/w2.pdf": "application/pdf",
    "/path/to/paystub.pdf": "application/pdf",
}
refs, err := client.UploadFiles(ctx, paths, mimeTypes)
// refs is map[string]*FileReference

Generating Content

With File API (recommended for multiple queries):

resp, err := client.GenerateContent(ctx, &gemini.GenerateRequest{
    Model:        gemini.ModelFlash,
    Prompt:       "Analyze this W2 for annual income",
    SystemPrompt: "You are a mortgage underwriter...",
    FileURIs:     []string{ref.URI},
    FileMIMEs:    map[string]string{ref.URI: "application/pdf"},
})

With Inline bytes (simpler for single queries):

resp, err := client.GenerateContent(ctx, &gemini.GenerateRequest{
    Model:  gemini.ModelFlash,
    Prompt: "Analyze this document",
    InlineFiles: []gemini.InlineFile{{
        Data:     fileBytes,
        MimeType: "application/pdf",
    }},
})

Data Structures

FileReference

type FileReference struct {
    Name      string    // Gemini-assigned name
    URI       string    // Reusable URI for requests
    MimeType  string
    State     string    // Processing state
    CreatedAt time.Time
    ExpiresAt time.Time // 48 hours from creation
    SizeBytes int64
}

GenerateRequest

type GenerateRequest struct {
    Model        string              // ModelFlash or ModelPro
    Prompt       string              // User prompt
    SystemPrompt string              // System instructions
    FileURIs     []string            // Gemini file URIs
    FileMIMEs    map[string]string   // URI -> MIME type
    InlineFiles  []InlineFile        // Direct bytes (alternative)
    Temperature  *float32
    MaxTokens    *int32
}

GenerateResponse

type GenerateResponse struct {
    Text           string
    FinishReason   string
    TokensUsed     int64
    ModelUsed      string
    ProcessingTime time.Duration
}

Model Selection

Model Constant Use Case
Gemini Flash gemini.ModelFlash Fast, cheaper, most tasks
Gemini Pro gemini.ModelPro Complex reasoning, escalation

File API vs Inline Comparison

Aspect File API Inline
Upload Once (cached 48hr) Every request
Best for Multiple queries, same docs Single query
Token cost Lower per query Higher per query
Latency Higher first query Consistent
Break-even ~7 queries N/A

FileCache Details

Located in internal/gemini/cache.go:

  • Thread-safe: Uses RWMutex
  • Expiry-aware: Checks 48hr TTL before returning
  • Methods: Get, Set, Delete, Cleanup, GetAllURIs

Troubleshooting

"GEMINI_API_KEY not set"

export GEMINI_API_KEY="your-key"

Upload failures

  • Check file exists and is readable
  • Verify MIME type matches content
  • Check file size limits

Rate limits

Add delays between requests:

time.Sleep(500 * time.Millisecond)
  • internal/gemini/client.go - Main client implementation
  • internal/gemini/cache.go - FileCache implementation
  • cmd/benchmark/main.go - Performance comparison tool