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.
Understand and work with Gemini's File API for efficient document processing.
┌─────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────┘
// Reads GEMINI_API_KEY from environment
client, err := gemini.NewClient(ctx)
if err != nil {
return err
}
defer client.Close()
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
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",
}},
})
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
}
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
}
type GenerateResponse struct {
Text string
FinishReason string
TokensUsed int64
ModelUsed string
ProcessingTime time.Duration
}
| Model | Constant | Use Case |
|---|---|---|
| Gemini Flash | gemini.ModelFlash | Fast, cheaper, most tasks |
| Gemini Pro | gemini.ModelPro | Complex reasoning, escalation |
| 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 |
Located in internal/gemini/cache.go:
export GEMINI_API_KEY="your-key"
Add delays between requests:
time.Sleep(500 * time.Millisecond)
internal/gemini/client.go - Main client implementationinternal/gemini/cache.go - FileCache implementationcmd/benchmark/main.go - Performance comparison tool