gemini-file-api

nimag's avatarfrom nimag

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 Dec 22, 2025
[API Helpers]

When & Why to Use This Skill

The Gemini File API skill streamlines document management for AI workflows by leveraging Gemini's specialized File API. It provides robust tools for document caching, parallel file uploads, and token optimization, allowing developers to handle large-scale document processing with reduced latency and lower costs. By managing file URIs with a 48-hour TTL, it eliminates redundant data transfers in multi-query scenarios, making it an essential tool for building efficient, document-heavy AI applications.

Use Cases

  • Efficient Multi-Query Workflows: Reuse uploaded document URIs across multiple prompts to maintain context without re-sending large files, significantly reducing token consumption and costs.
  • Automated Document Caching: Implement a thread-safe FileCache to prevent redundant uploads within a session, ensuring faster response times for repetitive document analysis tasks.
  • Parallel Document Processing: Handle batch uploads of multiple files (e.g., financial records or legal documents) simultaneously using structured Go-based implementations for high-throughput workflows.
  • Architecture Optimization: Compare File API vs. Inline byte approaches using built-in benchmarking logic to determine the most cost-effective strategy based on query volume and document size.
  • Token-Efficient Context Management: Optimize long-context window usage by referencing files via URI, allowing for complex reasoning across large datasets without hitting payload limits.
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