API / SDK
Practical guides to the Gemini API and SDKs — quickstarts, Function Calling, structured output, streaming, cost optimization, and troubleshooting.
When 404 and 429 Show Up in the Same Gemini API Log, Check the Model Name Before the Quota
A triage order for Gemini API logs that mix 404 NOT_FOUND and 429 RESOURCE_EXHAUSTED, plus a small Python script that separates a bad model name from a real quota limit without generating anything.
The Day /models Returns 200 but generateContent Returns 403 — Decide Your Triage Order Before It Happens
A triage order for the case where listing models succeeds with 200 but generation fails with 403 permission_denied. Includes a small diagnostic script that checks key, project, and billing in turn, why you should not retry a 403, and how to assemble what support needs.
When Your config Raises "Extra inputs are not permitted", Check the Spelling of Every Key
If a google-genai call fails with a pydantic ValidationError (extra_forbidden) the moment you pass a config, it is almost always a one-letter typo. Here is the output I reproduced, a small function that checks keys before the call, and how to tell why response.text came back as None.
When a Deprecation Has No Shutdown Date: Re-Picking an Image Model on Three Conditions
gemini-nano-banana-2.1 went GA on October 6, and gemini-3.1-flash-image was deprecated with no shutdown date. Here is a table and a short script for choosing a replacement by resolution, reference images, and search grounding.
The Size Column Said 'F6' and 'About A4' — I Let Gemini Read It, and Let a Table Do the Math
An artist's spreadsheet mixed 'F6', '41×31.8cm', and 'about A4' in one size column. Here is the small tool I built: Gemini reads each cell, a lookup table converts to centimeters, and the artwork image decides the orientation. Working code, step by step.
When Function Calls Turn Into Plain Text, Suspect the Property Names in Your Tool Declarations
A record of chasing MALFORMED_FUNCTION_CALL after output limits and schema conflicts were ruled out, bisecting nine tool declarations down to one property name, and adding a linter that stops bad names before they ship.
gemini-2.5-flash-image stops on October 2, and the replacement the table names retired in June
gemini-2.5-flash-image shuts down on October 2, 2026, but the recommended replacement listed in the official table, gemini-3.1-flash-image-preview, was already retired on June 25. Here is the script I wrote to follow replacement chains to their end, and what it found across every row of the table.
When Transcription Keeps Mangling Proper Nouns: Choosing What Earns a Custom Vocabulary Slot
gemini-3.5-transcribe accepts up to 1,000 custom_vocabulary entries, but filling the list is not the goal. Here is a 60-line script that picks entries from your own reference-and-hypothesis pairs, plus the rules I use to decide what to leave out.
Writing my first Gemini cost estimate in two columns, one for now and one for January
Introductory pricing for Gemini Flash ends on December 31, 2026, and standard pricing starts on January 1, 2027. Staying on an older generation does not avoid it. Here is the small, working estimator I use to see both prices at once.
The day Lyria 3.5 landed, I changed how my audio folders are laid out
When Lyria 3.5 brought full-length generation, my generated takes were sitting in the same folder as the tracks I had chosen by hand. Here is the forty-line ledger gate that draws the line by hash, not by filename.
Two Ways to Make a Longer Shot in Gemini Omni 1.1, and Two Different Ways They Break
Omni 1.1 extends scenes in 10-second steps up to 40 seconds cumulative, and interpolates between a pinned first and last frame. Which one you use is decided before your first generation, not after. Here is the planner I run first and the drift check I run last.
Gemini 3.8 Flash Costs the Same Per Token and Can Still Raise Your Bill
Gemini 3.8 Flash carries the same per-token price as 3.7 Flash, but it is designed to work harder, so output tokens can grow and your bill with them. Here is what to measure before you switch, and how to price it across the January boundary.
Screen Loop Seam Clicks With Numbers Before You Hand the Audio to Gemini
An ambient loop that clicks only at the wrap point. Here is the numeric prescreen I run before sending anything to audio understanding, why an absolute threshold fails, and how AAC encoding quietly rebuilt the seam I had just repaired.
Taking stock of Gemini standard API keys before September, across CI, servers, and my own machine
Standard API keys, including restricted ones, stop being accepted during September. Because this changes where keys come from rather than what they say, here is the three-layer inventory I ran across code, deploy settings, and my local machine, plus a dual-path client to switch behind.
Your New Gemini API Key Never Took Effect, and Load Order Wasn't the Reason
When several sources supply the same environment variable, swapping your key can leave the old value in place. Here is what four load orders actually produced, and a ledger that records which source won.
Smart mode in gemini-3.5-transcribe returns no speaker labels and no word timestamps
Smart mode in gemini-3.5-transcribe cannot be combined with diarization_mode or timestamp_granularities. Here is why the mode field accepts two types, and why enabling features halves your audio limit.
Should Omni Flash Hand You the 4K, or Should You Upscale at the Last Step?
In Gemini Omni Flash, 1080p and 4K are upscaled outputs. Here is how to pick the upscale point by working backwards from your delivery target, plus a script that checks whether the detail matches the nominal resolution.
Your Spreadsheet Breaks Before Gemini Ever Sees It
Merged cells and two-row headers quietly strip rows of their keys during extraction, long before the model reads anything. Here is what gets lost, measured, plus the Python that flattens the table and catches the total row.
Record what you send before you try to measure whether temperature still works
Deprecated sampling parameters still return 200 and are silently ignored. Here is how a runtime recorder caught the call sites grep and AST both missed, kept the construction site attached to each config, and turned the ledger into a CI gate.
Streaming Gemini TTS: concatenate the PCM, write the WAV header once
Streamed Gemini TTS does not arrive as an audio file. It arrives as raw PCM fragments. Here is what happens when you wrap each fragment in its own WAV header, measured on my machine, plus the receiving code that avoids it.
Moving app AI work from runtime calls to a pre-ship batch pass
Where you put a Gemini call decides whether your request count scales with users or with assets. Here is the decision rule I used to move classification into a pre-ship batch pass, plus a resumable implementation.
Once You Pass Twenty Mediation Groups, How Do You Find the Setting That Went Missing?
As ad mediation groups multiply, missing sources and type drift accumulate quietly. Here is the split I settled on: normalize the settings into one matrix, let code confirm the gaps, and send Gemini only the cells that need judgment.
Never hand Gemini a raw ANR thread dump
An ANR dump came in at 96 threads and 33,616 characters. Keeping only main cuts 98 percent, but it also deletes the thread that caused the block. Here is a lock-chain preprocessor, measured three ways.
gemini-2.5-flash Can Return a 404 'no longer available' While the Docs Still List No Shutdown Date
The shutdown date for gemini-2.5-flash is blank in the official deprecation table, yet 404 reports have been circulating since July. Here is why reading that column as a safety margin misleads you, and how to check your own keys.
Routing Between Gemini 3.7 Flash and 3.1 Pro by Rework Cost, Not Speed
A single question replaced my model-selection ritual: can a machine catch this output when it is wrong? Here is how that splits work between 3.7 Flash and 3.1 Pro, plus the pricing math across the December 31 cutover.
After generated_images Disappeared: Three Branches Between the Response and a Saved File
Once you switch to generate_content, the line that breaks is usually the save. Here are the three branches on the response side - zero image parts, a shifting image count, and picking the extension - plus a receiver function you can drop in.
Moving to the Batch Tier Cancels Out the Gemini 3.7 Flash Price Increase Exactly
Introductory pricing for Gemini 3.7 Flash ends on December 31, 2026, and the rate doubles the next day. Here is which models are affected, which are not, and how to project your January bill from the usage you already have.
generate_images Survives Until 2027. Your Image Generation Still Stops on August 17
google-genai 2.18.1 still ships generate_images, and the SDK deprecation notice points at 2027. The imagen-4.0 models, meanwhile, shut down on August 17. Here is what those two deadlines actually mean, measured on my own machine.
Rewriting generate_images as generate_content, where the arguments actually go
Ahead of the August 17 Imagen shutdown, I checked the SDK directly: of the 17 arguments in GenerateImagesConfig, only 5 move across unchanged. Here is the mapping, a compatibility layer that keeps callers working, and a way to verify the request shape without an API key.
A Timeout Was Never Evidence of Failure — Designing Around Blocking Function Calls
When a tool call cannot return until the real-world effect finishes, two habits reverse on you: parallel dispatch and generous timeouts. Measured numbers from a sandbox harness, plus the design that replaces retries with observation.
When Streaming Responses Quietly Lose Non-ASCII Text: Measuring the Byte Boundary and the Event Boundary Separately
I measured why Japanese text disappears from streaming Gemini responses using a local mock SSE server. Two separate layers were broken, one of them silently, and an English-only test suite caught neither.
Retrying a Retired Model Never Showed Up in Success Latency
With the image generation models shutting down soon, I rebuilt a mock server to see what my retry layer actually does when it hits a retired model ID. The damage landed in wall time and queue wait, and never touched the metric I was watching.
Measuring Update Policies for Memory Profiles: The Guard That Cost Me 16 Points of Accuracy
Memory profiles went GA in Memory Bank, making structured memory available to downstream code. I built three update policies and compared them under identical conditions. The one that looked obviously correct turned out to be the worst. Full harness code and the path to per-field TTLs.
Measuring a Guard in environment hooks: 46 Microseconds to Decide, 23 Milliseconds to Start
A record of building a destructive-command guard for Managed Agents environment hooks. A regex denylist let 9 of 20 dangerous commands through; argv parsing reached 100 percent detection. The startup cost turned out to be 500 times the decision cost.
When Sampling Parameters Were Deprecated, Diversity Broke Before Determinism Did
Deprecating temperature, top_p and top_k hurt the diversity-generating side of my pipeline, not the deterministic side. Counting real call sites, moving diversity to the input layer, and measuring effective diversity.
What Decided Our Cascade's Economics Wasn't the Escalation Rate
Putting Flash-Lite in front of 3.6 Flash and escalating only the hard items looks like an easy win. Estimating it from the escalation rate alone will mislead you. Here is the break-even solved with the escalated subset's output length in the equation.
A 17% Drop in Output Tokens Sounded Big. Then I Decomposed the Bill
Output pricing fell 16.67% and output tokens fell about 17%. Adding those numbers does not give you the savings. Here is an exact price/volume/cross-term decomposition, plus a loop measurement where the savings rate went down instead of up.
Retiring Prompt Assets That Refuse to Die — A Ledger for Paths Static Analysis Cannot See
A prompt I had supposedly consolidated away was still running daily. Here is the retirement ledger I built to cross-check static references, flag defaults, observation windows, model end-of-life dates, and cache effectiveness.
Don't Let the AI Studio Developer Log Be Your Source of Truth: A Two-Layer Way to Observe the Interactions API
The Interactions API developer log in AI Studio is a great triage lens, but it is not a system of record. Here is a two-layer observability design with self-hosted structured logging, reconciliation code, measured sink sizing across 100,000 records, and per-feature cost attribution from an indie operator’s point of view.
When to Hand Conversation State to the Server: previous_interaction_id vs. Pruning History Yourself
With the Interactions API, passing previous_interaction_id lets the server hold conversation state so you stop resending history. But a large tool output that lands mid-conversation can't be pruned afterward, and every later turn drags its weight. Here is a branching design that mixes server-side state with client-side pruning, plus a thin, working Python wrapper.