API / SDK
Practical guides to the Gemini API and SDKs — quickstarts, Function Calling, structured output, streaming, cost optimization, and troubleshooting.
Run Managed Agents with background: true So Your UI Never Freezes — An Async Run Pattern for Solo Developers
A background run in Managed Agents returns a run ID, not a finished answer. Here is the minimal polling setup, where it pays off in solo development, and the credential-refresh details worth knowing.
Still image or short clip? Deciding feature placement from the cost gap between Nano Banana 2 Lite and Omni Flash
When I froze over whether a wallpaper app's hero asset should be a still image or a short moving loop, the deciding factor was not taste but the order of magnitude of the cost. Here is how to normalize Nano Banana 2 Lite and Omni Flash onto the same footing, down to a working decision function.
How Well Does Omni Flash Hear 'Rotate the Camera 30 Degrees Right'? Measuring Where Conversational Edits Land
Public-preview Gemini Omni Flash lets you re-edit a generated video in plain language. 'Make the lighting evening' lands; 'rotate the camera 30 degrees' often misses. Here is a running log of where instructions land, sorted mechanically by comparing before/after frames.
Keeping a Long-Running Managed Agent Alive Across Sandbox Recycling — Durable Checkpoints and Idempotent Resume
A Managed Agents sandbox can be recycled out from under you. Before 40 minutes of work resets to zero, we design a durable checkpoint that pushes progress outside the sandbox and an idempotent resume that never runs a side effect twice. With working SQLite code.
The Same gemini-flash-latest Pointed to Different Models in Different Regions
Alias resolution rolls out region by region. Send the same gemini-flash-latest to Tokyo and us-central1 and, for a few days, different models answer. Here is why that quietly invalidates your comparisons, and how a one-shot probe catches it.
A Gemini stream drops halfway — restart it, or have the model continue?
Most apps silently restart a dropped stream. Here is the arithmetic behind continuing from the partial output instead, and where to put the threshold.
I Asked Gemini to Grade My App Store Screenshots. Everything Scored 78–85.
Ask Gemini Vision to grade App Store screenshots out of 100 and good candidates and deliberately broken ones both land at 78–85. Here is how I measured the judge's discrimination power, dropped absolute scoring, and rebuilt it as debiased pairwise comparison.
Sample what you already accepted — an audit budget that catches silent quality drift
A confidence gate only ever looks at output the model hesitated on. Silent drift sinks into the batch that sailed through. Working from a fixed 30-minutes-a-day review budget, this walks through deriving detection time from the binomial, reallocating the same budget across risk strata, and catching slow decay with a cumulative monitor.
Before One Runaway Experiment Drains the Shared Budget: Using AI Studio Spend Caps as Isolation Walls
When you run several Gemini experiments under one billing account, a single runaway loop takes everything else down with it. Here is how I use AI Studio's per-project spend caps as isolation walls, plus a client-side soft ceiling and monthly reconciliation, with working code.
When a Batch Job Sat in RUNNING for Half a Day: Field Notes on Catching Stalls Early with Per-State Dwell Budgets and Record Reconciliation
When a Gemini Batch job stalls quietly under the shadow of the 24-hour SLA, per-state dwell-time budgets and submitted-vs-completed record reconciliation let you name the stall early. Field notes with real operational numbers.
When Gemini's executed result and its prose disagree on a number — a gate that trusts only code_execution_result
Gemini Code Execution returns the value it actually computed and the sentence describing it as separate parts. Trust the prose and you can inherit a hallucinated number. Here is a verification gate, in working code, that extracts the executed result as the single source of truth and rejects prose that disagrees.
When an Optional Field Comes Back Three Ways: Null, Empty String, and Missing Key in Gemini Structured Output
Optional fields in Gemini structured output drift between null, empty string, and a missing key, and downstream code breaks in three different ways. Here is how I collapse all three into one shape using nullable in responseSchema and a post-output normalization gate, with numbers from a nightly batch.
When responseSchema Can't Do $ref: Handling Recursive Schemas in Production with responseJsonSchema
Gemini's responseSchema is an OpenAPI subset with no $ref or $defs, so it can't express shared definitions or recursion. Here's how I moved to responseJsonSchema to reuse localized fields and handle a recursive category tree in production.
When a Whole Chapter Vanished From My Long-PDF Summary — Field Notes on Auditing Coverage
Chapter-wise summarize-then-merge works well on long PDFs, but a lost extraction or a merge step can drop an entire chapter while the pipeline finishes without a single error. This walks through catching those silent drops with one number—coverage—and re-running only the chapters that fell out.
Stop Your Captions From Dancing: Splitting Live Translate Into Committed and Volatile Text
Pasting Gemini 3.5 Live Translate interim results straight to the screen makes captions flicker until they are unreadable. Here is a stabilizer that separates a committed prefix from a volatile tail and never rewinds, with working code and measured numbers.
When Gemini's Context Cache Quietly Expires Mid-Run: A TTL Guard for Pipelines That Pause
When a nightly batch or a retry backoff pauses your pipeline, Gemini's explicit context cache can expire on the wall clock while nothing errors out, sending later calls back to full-token billing. Here is a small lease guard that decides whether to re-arm or run uncached based on cost.
Google Sheets API × Gemini API: A Python Data Pipeline — No Apps Script Required
Learn how to build a fully Python-based pipeline that reads data from Google Sheets, processes it with Gemini API, and writes results back — without touching Apps Script. Covers service account auth, structured output, and rate limit handling.
Gemini API System Instructions and Prompt Design — Practical Techniques to Dramatically Improve Output Quality
Practical techniques for designing system instructions and prompts that produce stable, high-quality output from the Gemini API. Includes working code examples for format control, few-shot learning, temperature tuning, and error handling.
When gemini-embedding-2 Retrieval Feels 'Almost Right,' Check task_type First
When gemini-embedding-2 search misses in a frustrating near-hit way, the cause is often a missing or mismatched task_type. Here is how to align document and query intent, plus the code and a tiny harness to prove the difference on your own data.
When My Paid Gemini Chat Bill Came in at Double the Estimate — Field Notes on Per-Request Token Accounting to Plug the Cost Leaks
From a real overrun where my paid Gemini chat SaaS bill nearly doubled the estimate, here is how I logged token usage per request, traced where cost was leaking, and plugged three specific gaps. Recording usage_metadata and reconciling it against the invoice is the starting point.
Extract Social Media Promo Metadata From Short Videos in One Omni Flash Pass
Hand a short clip to the public preview of Gemini Omni Flash once and get captions, chapters, and highlight timestamps back as structured JSON. Covers how this differs from a frame-extraction multi-call setup, where fps and media_resolution actually matter, and a per-clip cost estimate — from the angle of keeping an indie promo workflow moving.
Measure a Managed Agent's Behavior Against Fixed Scenarios Before It Reaches Production
The public-preview Managed Agents run autonomously inside an isolated sandbox, so a small prompt or config change can quietly shift their behavior. Diffing the output once, the way you would for a single prompt, is not enough. Here is how to build a regression harness that runs fixed scenarios repeatedly and judges on pass rate, plus a shadow to canary to full promotion with automatic rollback, all with runnable Python.
When Context Caching Didn't Lower My Gemini Bill — Field Notes on Measuring the Real Hit Rate
When Context Caching is enabled but the Gemini API bill barely drops, this field note measures the real hit rate from usage_metadata, separates TTL churn from fragmentation, and walks through a staged recovery.
Ingested but Never Cited: Pruning a File Search Store with Citation Logs and a Quarantine Window
Most documents in a File Search store are never cited, quietly draining both cost and retrieval quality. Learn to log grounding metadata, surface never-cited documents from real usage data, and prune them safely with a quarantine window — with working code.
Collapsing Video Understanding into One Native Call with Omni Flash
How I replaced an ffmpeg frame-extraction pipeline (7-9 calls per clip) with a single native Omni Flash call, the measured differences, and the boundaries where keeping frame sampling still wins.
Designing Batch Image Costs with Nano Banana 2 Lite: Decide by Measuring
How to fold the fastest, cheapest image model, Nano Banana 2 Lite, into high-volume generation: measuring per-image cost, a two-tier setup with a quality model, and retry handling grounded in real numbers.
Splitting Bulk Image Generation Cost in Two with Nano Banana 2 Lite: A Draft-and-Render Design
A two-tier cost design that routes first-pass generation to Nano Banana 2 Lite and final renders to the standard Nano Banana 2, with a minimal Python router you can adapt.
Building Conversational Translation Into an App: Speech-to-Speech With the Live API
A design walkthrough for adding speech-to-speech conversational translation to an app with Gemini 3.5 Live Translate and the Live API, covering session lifetime, automatic language switching, latency budgets, and streaming cost, with working code.
Catching only the deprecations that touch you — feeding the official changelog to url-context
I found out an image model was being shut down three days before the deadline. Here is a deprecation radar that reads the official changelog through url-context and surfaces only the models I actually use, with working Python and the over-alerting tuning I had to do in production.
When Two Managed Agents Fight Over the Same Repo: External Leases and Fencing for Isolated Sandboxes
Every Managed Agents run gets its own isolated sandbox, so a local lock cannot stop two runs from touching the same repo or record. Here is how I serialize them safely with an external lease and a fencing token.
When Gemini API Leaks Japanese Into Your English Output Once in a While — Field Notes on Measuring the Contamination Rate and Tightening It in Stages
You told Gemini to answer in English, and 3 out of 100 runs slip a Japanese sentence into the tail. Here is why you cannot stop that 'once in a while', and a production pattern that measures the contamination rate as an SLO and tightens it with graded recovery, with working code.
Catch Near-Duplicate Posts Before You Publish — a Topic-Cannibalization Gate with Gemini Embeddings
Once a blog passes a few hundred posts, new articles start cannibalizing old ones in search. This walks through a pre-publish gate that embeds each post's meaning with gemini-embedding-2 and blocks drafts that sit too close to something you already wrote — with runnable code and how to pick the thresholds.
Catching the Rows That Quietly Failed Overnight: A Per-Row Retry Ledger for the Gemini Batch API
A SUCCEEDED batch job is not the same as all-rows-succeeded. From running nightly batches as a solo developer, here is a per-row result ledger, a transient-vs-permanent failure classifier, selective retries, and a guard against retrying permanent failures forever, with a working SQLite state machine.
Building AI-Powered iOS and Android Apps with the Gemini API — Image Recognition, Voice Analysis, Chat, and Monetization
Architecture patterns, cost optimization, and monetization for adding image recognition, voice analysis, and AI chat to iOS/Android apps with the Gemini API — updated with Gemma 4 routing and the mandatory API key restriction change.
A Webhook Is a Claim, Not a Fact — Three Layers of Defense for Your Gemini Webhooks Endpoint
Your Gemini Webhooks receiver is a public URL, which means forged events, replays, and duplicate deliveries are all on the table. This walkthrough builds a three-layer defense — reachability checks, dedupe, and a lightweight handler that re-fetches truth from the API — with working FastAPI and SQLite code.
Routing Between Local Gemma 4 and the Gemini API Cut My Bill from ¥32,000 to ¥9,000 — A Production Hybrid Router Design
How I cut a ¥32,000/month Gemini API bill to the ¥9,000 range with hybrid inference: routing design, a full Python router, production pitfalls, and how Gemma 4 arriving on the Gemini API in July 2026 changes the decision.
Locking Down a Gemini API Key on Servers Whose IP Keeps Changing — Restrictions for Headless Automation
After unrestricted keys started getting blocked, headless server automation whose egress IP changes every run can't cleanly use HTTP referrer, app restrictions, or an IP allowlist. Do you get by with API restrictions alone, funnel egress through a fixed IP, or move server workloads off API keys onto Vertex service-account auth? A decision framework and working code, without taking your pipelines down.
Keeping Unattended Jobs From Failing Silently: A Preflight Gate for Gemini's Platform Changes
Unrestricted API keys are now rejected, the old CLI reached end of life, and the Interactions API is becoming the default entry point. These 2026 platform shifts stop working automation without raising an error. Here is a preflight gate, with runnable code, that catches the failure before the batch runs.
When a Prompt That Worked in AI Studio Quietly Breaks Over the API — Field Notes on Measuring the Difference
A prompt that behaves perfectly in AI Studio returns an empty string or a 404 the moment you call the Gemini API from your own code. Instead of eyeballing the two, here is a small harness that records the config diff plus finish_reason, token usage, and the model name the server actually resolved — so you can isolate the cause by layer.
Fire-and-Forget on a Cron That Never Loses a Result: Reclaiming Gemini Background Executions with a Submission Ledger
A design for running the Interactions API's background execution safely from a cron-driven runner. We reserve a row in a ledger by idempotency key before submitting, then reclaim only outstanding handles on the next tick — shown with working code.