Gemini API Production Deployment Guide

Configuration Requirements

Production Setup

• SDK: Use @google/generative-ai npm package, not curl/Postman
• Model Selection: Gemini-2.5-Flash for 90% of requests, Pro only when necessary
• Generation Config: Temperature 0.7, topP 0.8, maxOutputTokens 1024
• Environment: Load API keys from environment variables, never hardcode

Critical Environment Issues

• WSL2 on Windows: Different failure modes than regular Windows
• Docker containers: Require specific network configurations for Google APIs
• Corporate firewalls: Block endpoints without clear error messages
• Environment variables: Cache inconsistently during development

Resource Requirements and Costs

Pricing Reality

• Flash Model: $0.05-0.15 per interaction
• Pro Model: $0.20-0.50 per interaction
• Video Processing: 3-5x higher costs than text/images
• Medium Traffic App (10K requests/day): $200-500/month
• Context Caching: Can save 75% or double costs depending on implementation

Cost Optimization Rules

• Context caching only works for documents >32K tokens queried multiple times within 24 hours
• Set cache TTL to 1 hour maximum unless guaranteed reuse
• Overlapping document chunks create separate cache entries, multiplying costs
• Free tier unsuitable for production (aggressive rate limits, account bans possible)

Rate Limiting and Performance

Actual Rate Limits (vs Documentation)

• Free Tier: 15 RPM, 1M TPM, 1.5K RPD (production unsuitable)
• Paid Tier: 360 RPM, 4M TPM, no daily limit
• Regional Variations: US-East more generous than Europe/Asia
• Video Requests: Count as 10x regular requests
• Failed Requests: Still count against limits
• Reset Timing: Inconsistent (60-90 seconds)

Performance Thresholds

• Images: >20MB timeout despite 50MB limit
• Videos: >100MB consistently timeout regardless of duration
• Context Window: Breaking points not clearly documented in errors
• Peak Hours: 2-3 infrastructure hiccups per week

Critical Failure Modes

Common Production Failures

Failure Type	Trigger	Impact	Resolution Time
Infrastructure overload	Peak hours	500 errors	30-60 seconds
Safety filter false positive	Code screenshots, certain keywords	Content rejection	Immediate with workaround
Regional rate limit variance	Geographic location	429 errors	Switch regions
Context caching misconfiguration	Overlapping chunks	2x cost increase	Redesign chunking
Video processing timeout	>100MB files, DRM audio	Silent failures	Preprocess files

Error Message Translation

• "Model is overloaded": Infrastructure struggle, wait 30s and retry
• "Content may violate safety guidelines": Text in images triggered filters, rephrase/crop
• "Token limit exceeded": Context limit hit, error doesn't specify which limit
• "Invalid API key": Could be wrong key, rate limited, or regional restrictions

Implementation Patterns

Retry Logic (Production-Tested)

async function callGeminiWithRetry(prompt, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await model.generateContent(prompt);
    } catch (error) {
      if (error.status === 429) {
        await new Promise(resolve => setTimeout(resolve, 2000 * Math.pow(2, i)));
        continue;
      } else if (error.status >= 500) {
        await new Promise(resolve => setTimeout(resolve, 1000));
        continue;
      } else {
        throw error; // Don't retry client errors
      }
    }
  }
  throw new Error(`Failed after ${maxRetries} retries`);
}

Image Preprocessing (Prevents 80% of failures)

• Convert to JPEG, max 10MB, strip metadata
• Resize to max 2048px, remove alpha channels
• Dark theme screenshots cause hallucinations - convert to light backgrounds
• PNG with transparency: Use JPEG for reliability

Request Deduplication

const processedHashes = new Map();
async function processImageSafely(imageBuffer) {
  const hash = crypto.createHash('sha256').update(imageBuffer).digest('hex');
  if (processedHashes.has(hash)) {
    return processedHashes.get(hash);
  }
  const result = await callGeminiWithRetry(imageBuffer);
  processedHashes.set(hash, result);
  return result;
}

Production Deployment Checklist

Essential Infrastructure

• ✅ API key in secret manager (not environment variables)
• ✅ Exponential backoff retry logic with circuit breakers
• ✅ Request queuing and rate limiting
• ✅ Billing alerts at $50, $200, $500 thresholds
• ✅ Context caching only for large, repeated documents
• ✅ Fallback models (Claude/GPT-4) for when Gemini fails
• ✅ Response validation for hallucination detection
• ✅ Performance monitoring (response times, failure rates)

Monitoring Requirements

• Independent health checks (don't trust status pages)
• Client-side token counting and cost estimation
• Regional failover capabilities
• Real-time error rate tracking
• Daily cost threshold alerts

Decision Criteria

When to Use Gemini vs Alternatives

• Choose Gemini: Multimodal processing, cost optimization priority, OpenAI compatibility needed
• Choose Alternatives: Consistent low-latency requirements, complex reasoning tasks, sensitive compliance needs

Model Selection Logic

• Flash: 90% of use cases, especially high-volume processing
• Pro: Complex analysis requiring extra intelligence, low-volume specialized tasks
• Video Processing: Preprocess to <100MB, constant frame rate, remove DRM audio

Migration Considerations

• OpenAI compatibility covers 80% of common use cases
• Gemini-specific features require native API
• Pin to specific model versions in production
• Test thoroughly before upgrading (Google updates without notice)

Real-World Cost Examples

Production Incidents

• Context Caching Mistake: $800 unexpected charges from overlapping document chunks
• Black Friday Traffic Spike: $3,000 weekend (should have been $300) from retry storms
• Rate Limit Regional Variance: 40% European traffic failed for full day

Successful Optimizations

• Switching 90% requests to Flash: 60% cost reduction
• Proper context caching implementation: 75% savings on document processing
• Request deduplication: Eliminated redundant processing costs

Breaking Points and Warnings

What Will Break Your Production App

• No fallback workflow when API fails (happens 2-3x/week)
• Improper retry logic causing cost spirals
• Relying on free tier for anything important
• Not implementing request deduplication
• Using Pro model for everything instead of Flash
• Setting cache TTL too high without guaranteed reuse
• Processing videos >100MB without preprocessing
• Trusting status pages instead of independent monitoring

Hidden Prerequisites

• Regional API endpoint differences
• Corporate firewall configurations
• Docker networking for Google APIs
• Token counting API for cost control
• Circuit breaker patterns for high availability
• Image preprocessing pipeline for reliability