API / SDK
Practical guides to the Gemini API and SDKs — quickstarts, Function Calling, structured output, streaming, cost optimization, and troubleshooting.
Folding Scattered Call Sites Into One Front Door: Migrating to the Interactions API for Automation
With the Interactions API now generally available, Gemini's calls can settle behind a single entry point. Here is a migration design for folding scattered call sites — generateContent, Batch, and homegrown agent loops — into one front door without breaking anything, complete with a working adapter layer.
Letting Gemini Listen to a Long Track and Build Its Chapters — Timestamped Structured Extraction
How I replaced hours of hand-chaptering long healing-audio tracks with Gemini's audio understanding: uploading long files via the Files API, pinning JSON output with response_schema, and the validation code that catches audio-specific quirks like timestamp drift and phantom silence.
Guarding Gemini API Responses in CI: Snapshot and Semantic Regression Testing
Defend non-deterministic Gemini API responses with pytest snapshots plus embedding-based semantic regression detection: record/replay CI, a weekly live smoke that keeps cassettes honest, per-field drift reporting, threshold calibration, and update governance — all in working code.
Stop Losing Silently-Failed Jobs in Your Unattended Gemini API Pipeline
When an unattended Gemini API batch drops a single job in silence, you may not notice for days. Here is a minimal dead-letter store and a safe replay flow — with copy-paste code and the operational judgment that makes it work.
A Finished Gemini Job Flipped Back to 'Running' — Stopping Out-of-Order Webhooks with Monotonic State Apply
When you receive Gemini long-running operations over webhooks, a stale 'running' event can arrive after completion and roll your state backward. Here is a monotonic-apply reducer that safely drops regressing updates.
Read Video with Timestamps in the Gemini API: Pull Just the Scene You Need
Hunting for 'where was that step?' in a screen recording or app demo is a chore. Here is how to use Gemini API video understanding to pull just the right scene with timestamps, plus a design that keeps tokens down with FPS and resolution.
The Morning a Managed Agent Stalled and Left No Trace — Building a Run-Observability Layer Outside the Sandbox
With Gemini Managed Agents, the sandbox lives on Google's side, so when a run stalls there is nothing left in your own logging stack. This is a working TypeScript design for an outside observability layer that taps stream events into a ledger, detects silent stalls, and folds runs into readable postmortems.
When Gemini × Qdrant Hybrid Search Was Quietly Losing Recall — Field Notes on Instrumenting RRF Weights and Sparse-Vector Drift
Run Gemini embeddings with Qdrant hybrid search in production and your dashboards stay green while recall quietly slips. These field notes show how to catch it with measurement — RRF weights, sparse-vector drift, missing payload indexes — and protect it with a quality budget.
Mixing Text and Images in One File Search Skewed My Results Toward Images — Rebalancing by Modality After Retrieval
When you put text and images in a single File Search store with gemini-embedding-2, results can quietly skew toward one modality. Here is how to measure that skew and even it out after retrieval, using per-modality normalization and quota-based merging — with working code.
Audit Your Gemini API Key Restrictions Before the Unrestricted-Key Block Stops Your Automation
Since June 19, 2026, requests from unrestricted Gemini API keys are blocked. Here is how to check whether your key is affected and add restrictions without taking your production automation down.
A Promotion Gate So gemini-flash-latest Flipping to 3.5 Flash Doesn't Break Your Pipeline at 3 AM
Floating aliases like gemini-flash-latest swap their target on every GA, quietly shifting the assumptions your unattended automation depends on. Here is a role-to-pinned-ID indirection layer, an acceptance harness that measures four metrics against your own golden set, and threshold-driven promotion and automatic rollback — with working code.
Don't Retry Every Gemini 429 — Telling Rate Limits Apart From Spend Cap Exhaustion
A 429 RESOURCE_EXHAUSTED can mean 'wait a second and it clears' or 'you're out of budget for the month.' Now that Project Spend Caps is generally available, the second case is real in production. Here's how to classify the two and build a retry layer plus a circuit breaker around them.
Stopping Runaway Costs Twice: Project Spend Caps Plus an App-Side Soft Limit
Pairing Gemini API Project Spend Caps (a monthly USD ceiling) with an app-side soft circuit breaker that trips before the hard cap. Includes a working Python and sqlite daily cost ledger.
Your Gemini Structured Output Keys Keep Reordering — Pin Them With propertyOrdering
You constrained the shape with responseSchema, yet the JSON key order shifts between calls and your snapshot tests go red for no reason. Here is why field order is not guaranteed by default, how propertyOrdering fixes it, how Pydantic sets it for you, and how to align few-shot examples — all with working code.
Is Gemini 3.5 Flash Actually Cheaper? Measuring Retry Amplification to Find the Flash vs Pro Break-Even
Now that 3.5 Flash is generally available, it is tempting to route everything to it. But once you measure effective cost per success instead of per-call price, the decision changes. Here is a small harness to measure retry amplification and find the break-even.
When Gemini's Safety Filter Silently Drops Legitimate Output — Field Notes on Catching False Positives Without Turning Everything Off
Field notes on handling Gemini API false positives in production without disabling every category. Separating input blocks from output blocks, instrumenting per-category false-positive rates, and recovering by relaxing only the offending category.
When your Gemini API spend cap trips, paying users go down too — isolating the blast radius with per-tier projects
A Project Spend Cap stops the entire project at once. To keep a runaway free tier from taking paying users down with it, this is a design note on isolating the cap's blast radius across per-tier projects and closing the ~10-minute delay with an application-side soft budget gate.
Reliable Text-in-Image with Gemini 3.1 Flash Image — an OCR-Verified Pipeline
After the preview shutdown, the GA gemini-3.1-flash-image still occasionally garbles text baked into images. Here is a generate -> read-back-verify -> regenerate/composite pipeline, with working code and an unattended retry budget.
Turning Articles into Audio with the Gemini 3.1 Flash TTS Preview: Splitting Long Text, Stitching It Back, and What It Actually Costs
The Gemini 3.1 Flash TTS preview launched today. Here is a single-narrator pipeline that converts a written article into clean audio, including how to split long text, stitch PCM without ugly seams, keep one voice steady, and estimate the real per-article cost.
Gemini API × TypeScript Type-Safe AI Application Architecture — Integrating Zod Schemas, Structured Output, and Streaming
Type-safe AI applications with the Gemini API and TypeScript: Zod validation, Structured Output, streaming pipelines, and error handling that holds up in production.
When Gemini's Structured Output Quietly Drifts From Your Schema — Field Notes on Measuring Validation and Retries
Even with response_schema set, Gemini's structured output occasionally drifts in production. Stop swallowing failures, measure them, split causes by finish_reason, and feed errors back for a corrected retry. Field notes from stabilizing a validation pipeline.
The Morning a Preview Image Model Went Dark — Migrating to GA Gemini Image Models and Building a Deprecation-Resilient Pipeline
With gemini-3.1-flash-image-preview and gemini-3-pro-image-preview retired, here is how to migrate to the GA models and design an image pipeline that no longer gets caught off guard by deprecation dates — with code and cost math, plus video-to-image thumbnail automation.
Citing the exact page and figure in File Search answers with visual-citation metadata
File Search grounding metadata now carries media_id and page_numbers, so you can trace each sentence of an answer back to a specific page and figure. Here's how I built a sentence-level, verifiable citation layer over a mix of PDFs and images.
Building an Intelligent Data Layer: Gemini API × GraphQL Architecture Guide
A comprehensive guide to integrating Gemini API into GraphQL for AI-powered resolvers, semantic caching, and type-safe schema design. Build production-grade intelligent data layers.
Gemini API × Cloudflare D1: A Zero-Cold-Start AI Backend Under $10/Month — Implementation Notes
Build a zero-cold-start, globally distributed AI backend with Cloudflare Workers + D1 (edge SQLite) and Gemini API — conversation history, rate limiting, post-stream write latency, and a real $8.50/month cost breakdown, from a deployment I actually operate.
When a Deploy Drops the Webhook: Reconciling Gemini Long-Running Operations with a Belt-and-Suspenders Design
Even after you move from polling to Webhooks, events still get dropped during deploys and transient 5xx windows. Here is how I double up Gemini long-running operations with an operation ledger and a low-frequency reconciliation poller so a missing terminal event never goes unnoticed.
When Gemini API Quietly Dies on the Edge from Subrequest Limits — Field Notes on Budgeting What's Left
Running Gemini API on Cloudflare Workers is calm until traffic rises or a tool chain deepens, and then it fails on the subrequest limit. Here are the instrumentation patterns I use to measure per-request consumption and treat it as a budget, drawn from the sites I run as an indie developer.
Stopping Gemini API Function Calling Loops: Why They Happen and How to Break Them
Your tool-calling agent keeps invoking the same function and never finishes. Here is how to diagnose the loop and bake stop conditions into your prompt, code, and tool responses — including catching regressions when the default model changes and detecting result-based stalls.
Your File Search Store Goes Stale in Production — Catalog Sync and Drift Detection That Actually Hold
Load a catalog into File Search once and forget it, and within weeks it starts confidently pointing users at assets you already pulled. Here is the sync pipeline I run: hash-based incremental import, a blue/green rebuild that swallows deletions, and a nightly drift audit.
Integrating Gemini 3.2 Pro Function Calling into iOS/Android Apps: Production Design Patterns
A practical guide to integrating Gemini 3.2 Pro Function Calling into iOS and Android apps. Includes working SwiftUI, Kotlin, and Python code, plus production patterns proven in a real indie wallpaper app — cost, latency, staged rollout, and regression testing.
Your Gemini API Average Latency Looks Great — But Some Users Still Get Stuck. Defending p95/p99
Your average TTFT is fast, yet a fraction of users keep hitting frozen responses. That is a tail-latency problem (p95/p99). From measurement to model routing, streaming budgets, cache accounting, and retry design — here are the defenses that actually held up in production, with code.
Implementing Gemini API Function Calling — Parallel Calls, Tool Chains, and When to Use Managed Agents
Production patterns for Gemini API Function Calling: parallel calls, error handling, and tool chaining, plus when to use Managed Agents and how to pin the tool-selecting model to a GA release.
Generating a Thumbnail From a Video With Nano Banana 2 (gemini-3.1-flash-image)
A hands-on guide to passing a whole video as context to the GA model gemini-3.1-flash-image (Nano Banana 2) and generating a single thumbnail. Covers how it differs from frame extraction, the preview-to-GA migration, and measured cost and time per image.
Before Free Users Quietly Eat Your Margin: Tier Design and Cost Ceilings for Gemini API Apps
Protecting the margin on a Gemini-powered app means designing around a per-user monthly cost ceiling, not request counts. Tier-aware model routing, real-cost metering in KV, and the token-bloat traps that drain profit, with working code.
Gemini API on Google Cloud: Diagnosing Production Errors Layer by Layer
Systematically diagnose Gemini API errors in Google Cloud production environments. Covers IAM permissions, Vertex AI vs AI Studio, VPC Service Controls, quota management, service accounts, and multi-region failover with full code examples.
Structured Product Image Analysis with the Gemini API — A Production Pipeline Built on Thousands of Photos
Turn a one-off image analysis script into a production pipeline that auto-generates tags, descriptions, and categories at scale — covering structured output, resumable batches, measured cost, and model routing learned from real indie-developer operation.
Compressing Gemini API Chat History with Rolling Summaries — Designing Chatbots That Survive Hundreds of Turns
When a Gemini chatbot grows long enough, your bills balloon and one day a request hits the token ceiling. The rolling-summary pattern keeps long chats stable.
Should You Move Your Agent Loop to Gemini's Managed Agents? Three Questions That Decide What Migrates
With Gemini API's Managed Agents in public preview, deciding between a self-hosted agent loop and a Google-hosted sandbox is now a real question. Three questions — execution environment, state ownership, and failure recovery — decide what migrates and what stays.
How to Handle Gemini API Model Deprecation and Migration Errors
A practical guide to migrating from deprecated Gemini API models and resolving common migration errors.
Gemini API Implicit Caching Not Working — Troubleshooting Guide by Root Cause
Troubleshoot Gemini API implicit caching issues: cache not hitting, unexpectedly high costs, or low cache hit rates. Covers token thresholds, prompt structure, model version consistency, TTL expiry, and multimodal caching with code examples.