Gemini API Tutorial: Carbon in 12 Steps, 70 Min [2026]

Google made Gemini 4 Carbon generally available to paying developers and enterprises on November 10, 2026, at an introductory price of $2 per million input tokens and $10 per million output tokens through November 30, 2026, with rates doubling to $4 and $20 per million tokens from December 1. The model, identified as `gemini-4-carbon`, runs in the Gemini API, Google AI Studio, Android Studio, Gemini for business and Antigravity, with cached input priced at 95% off the input rate, and Google also introduced the faster, cheaper Gemini 4 Hydrogen on November 12 for agentic loops. A tutorial built around the launch warns that anyone who ships a prototype this month and forgets the December 1 date will see costs double overnight, and notes Carbon's rollout still varies by account and region.

The Gemini API now serves Gemini 4 Carbon to paying developers, and Google’s launch post https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-4-carbon-now-available/ priced it at $2 per million input tokens and $10 per million output tokens through November 30, 2026. From December 1 those rates double to $4 and $20. Anyone who ships a prototype this month and forgets that date will watch the bill jump overnight. That deadline shapes the whole build. Create a small Python CLI called carbon-lab that covers the full path: a safely stored API key, a first call, token accounting, streaming, tool calls, typed JSON output, retries, a spend ledger and a test suite. Each step ends with a command to run and output to compare. Carbon’s rollout still varies by account and region, as the availability picture for the $2 intro price https://shattered.io/gemini-4-carbon-availability-2-dollar-intro-price-not-worldwide-2026/ shows, so the project checks which model IDs your key can see before it sends a single prompt. Demand for this skill is easy to measure. Stack Overflow’s 2025 developer survey https://stackoverflow.co/company/press/archive/stack-overflow-2025-developer-survey/ found that 35% of developers reported using Gemini Flash models. Among developers who use ready-made agents, copilots or assistants, 47.4% reported using Google Gemini. Most of them start the same way you will: grab a key, paste a snippet, and discover the details thinking tokens, retries, price changes only after the first invoice. Don't miss new tech stories on Google Add Shattered once in the Google app and our stories show up in your news suggestions. Add now https://www.google.com/preferences/source?hl=en&q=https%3A%2F%2Fshattered.io%2F Where the Gemini API Stands on November 15, 2026 Google moved Gemini 4 Carbon from a limited cyber-defender preview to general availability for paying developers and enterprises on November 10, 2026. The model reaches developers through the Gemini API, Google AI Studio, Android Studio and Gemini for business. Consumers on Google AI Ultra get it in the Gemini app, AI Mode in Search and Google Antigravity, and Android Authority’s rollout report https://www.androidauthority.com/google-gemini-4-carbon-rollout-3733702/ describes the Ultra-first pattern. The API identifier is gemini-4-carbon . Google also introduced Gemini 4 Hydrogen https://shattered.io/gemini-4-hydrogen-agentic-workflows-1m-context-1-50-input-2026/ on November 12, and reports describe it as the faster, cheaper sibling aimed at agentic loops, while Carbon and Gemini 4 Argon target deeper reasoning. Treat any Hydrogen price you see on forums as unconfirmed until you read Google’s pricing page yourself. The table below sticks to what Google has published. | Item | Current state November 15, 2026 | |---|---| | Model ID | gemini-4-carbon | | General availability | November 10, 2026, for paying developers and enterprises | | Input price, through November 30 | $2 per 1M tokens | | Output price, through November 30 | $10 per 1M tokens | | Input price, from December 1 | $4 per 1M tokens | | Output price, from December 1 | $20 per 1M tokens | | Cached input | 95% off the input price | | Intro price matches | Gemini 4 Argon $2 and $10 per 1M | | Where it runs | Gemini API, Google AI Studio, Android Studio, Gemini for business, Antigravity | Two details in that table matter for a tutorial. First, the price applies to the public Carbon model, and Google’s footnote names no carve-out for existing projects, so budget every token sent on or after December 1 at the higher rate. Second, a subscription is not an API plan. Google AI Ultra unlocks Carbon in consumer surfaces, while Gemini API usage bills separately by token. Reports from the week of November 13 say Google AI Pro subscribers can claim $10 a month in Google Cloud credits for Gemini API use in AI Studio, but confirm that on your own billing page before you rely on it. For model choice beyond this project, the independent comparison of Claude Opus 5.5 and Gemini 4 Carbon https://shattered.io/claude-vs-gemini-opus-5-5-vs-gemini-4-carbon-argon-59-vs-58-2026/ covers where each wins. The Gemini 4 launch timeline https://shattered.io/gemini-4-launch-earlier-claim-meta-muse-argon-carbon-zero-new-dates-2026/ explains how Argon, Carbon and Hydrogen reached developers in that order. Prerequisites and Versions The project needs very little. Everything runs on a laptop, and the test suite works offline with no key at all. - Python 3.12 or newer. Python 3.13 also works. Check with python3 --version . - The google-genai SDK, latest version. This is Google’s current Python client. The older google-generativeai package is the legacy library and does not mix well with the new one in a single environment. - pydantic, python-dotenv and pytest, latest versions. Pydantic gives you typed output, dotenv loads the key, pytest runs the checks. - A Google account with billing enabled in Google AI Studio. Carbon is a paid-tier model, so a free-tier key will list other models and fail on this one. - A Linux, macOS or WSL shell. Windows PowerShell works too, but the commands below use POSIX syntax. - About $1 of credit. At intro prices the whole walkthrough costs a few cents, yet a funded account avoids rate-limit surprises. Pin the exact versions your install resolves into requirements.txt when you finish. Reproducible builds matter more than usual here because the SDK and the model lineup are both moving fast. Steps 1 and 2: Create a Key and Scaffold the Project Step 1: Create the API key Open Google AI Studio, create a key under your billing-enabled project, and copy it once. Treat it like a database password. A key pasted into a notebook, a screenshot or a public repository gets scraped within minutes, and a leaked key on a paid project spends real money. Never commit the key. Create the project folder and an environment file that git ignores: mkdir carbon-lab && cd carbon-lab python3 -m venv .venv source .venv/bin/activate pip install google-genai pydantic python-dotenv pytest printf "GEMINI API KEY=paste-your-key-here\nCARBON MODEL=gemini-4-carbon\nFAST MODEL=gemini-4-hydrogen\nTHINKING LEVEL=low\nDAILY BUDGET USD=2.00\n" .env printf ".env\n.venv/\nusage.jsonl\n pycache /\n" .gitignore printf "GEMINI API KEY=\nCARBON MODEL=gemini-4-carbon\nFAST MODEL=gemini-4-hydrogen\nTHINKING LEVEL=low\nDAILY BUDGET USD=2.00\n" .env.example The last line produces an .env.example with the key blanked out, which is the only env file that belongs in version control. If you already run local models behind an authenticated proxy, the same hygiene applies, and the walkthrough on setting up an Ollama API key behind a reverse proxy https://shattered.io/ollama-api-key-reverse-proxy-docker-12-steps-2026/ shows the pattern. Beyond the ignore file, three habits protect a paid key. Rotate it on a schedule, for example every 90 days, and immediately after anyone who had access leaves the team. Restrict it where the console allows, so a stolen key cannot reach services you never use. In CI and production, inject it from a secrets manager or the platform’s encrypted variables instead of baking it into an image. A key in a Docker layer lives in that layer forever, even after you delete the file in a later step. Step 2: Lay out the project Create the package and test folders so the later steps drop files into the right places: mkdir -p carbonlab tests touch carbonlab/ init .py tests/ init .py pip freeze | grep -iE "google-genai|pydantic|python-dotenv|pytest" requirements.txt cat requirements.txt Expected output your versions will differ : google-genai==<resolved version pydantic==<resolved version python-dotenv==<resolved version pytest==<resolved version The final layout looks like this, and each later step adds one file: carbon-lab/ carbonlab/ config.py step 3 client.py steps 4 and 10 usage.py steps 5 and 9 tools.py step 7 schemas.py step 8 cli.py steps 3 to 11 tests/ test usage.py step 12 test retry.py step 12 Steps 3 and 4: Load Settings and Make the First Call Step 3: Load settings and verify the model ID Hard-coded model names rot quickly. Gemini’s lineup changed several times between October and mid-November 2026, and community threads describe older models leaving some consumer plans while access to Gemini 2.5 narrows to projects that already used it. Put the model ID in configuration and verify it against the live model list. python carbonlab/config.py import os from dataclasses import dataclass from dotenv import load dotenv load dotenv @dataclass frozen=True class Settings: api key: str model: str fast model: str thinking level: str daily budget usd: float def load settings - Settings: key = os.environ.get "GEMINI API KEY", "" .strip if not key: raise SystemExit "GEMINI API KEY is not set. Copy .env.example to .env and fill it in." return Settings api key=key, model=os.environ.get "CARBON MODEL", "gemini-4-carbon" , fast model=os.environ.get "FAST MODEL", "gemini-4-hydrogen" , thinking level=os.environ.get "THINKING LEVEL", "low" , daily budget usd=float os.environ.get "DAILY BUDGET USD", "2.00" , Now add the first piece of the CLI, a models command that lists what your key can see and flags the two IDs you configured: python carbonlab/cli.py part 1 import argparse import sys from google import genai from carbonlab.config import load settings def visible models client - set str : return {m.name.removeprefix "models/" for m in client.models.list } def cmd models args - int: settings = load settings client = genai.Client api key=settings.api key names = visible models client for wanted in settings.model, settings.fast model : flag = "OK " if wanted in names else "MISSING" print f"{flag} {wanted}" gemini4 = sorted n for n in names if n.startswith "gemini-4" print "gemini-4 models your key can see:", ", ".join gemini4 or "none" return 0 if settings.model in names else 1 Run it once the CLI entry point exists the final assembly appears in step 11 . Sample output on a paid key: bash $ python -m carbonlab.cli models OK gemini-4-carbon OK gemini-4-hydrogen gemini-4 models your key can see: gemini-4-argon, gemini-4-carbon, gemini-4-hydrogen If MISSING appears next to Carbon, stop here. The model is invisible to your key, and no amount of retry logic will fix that. The troubleshooting section lists the usual causes. Hydrogen’s identifier also comes from community trackers rather than a page you can verify offline, so this check protects the fast-model setting too. The check costs nothing because listing models is a metadata call, not a generation. Run it in a deploy script as well, and fail the release when the configured ID disappears. That turns a 3 a.m. outage into a red build at 3 p.m. It also answers a question that trips up many first-time users: whether the problem lives in their code or in their account. Step 4: Send the first request A first call needs three things: a client, a model ID and some contents. Add a thin generate wrapper now, because step 10 will extend it with retries and you want one place to change. python carbonlab/client.py from google import genai from google.genai import types def make client api key: str - genai.Client: return genai.Client api key=api key def build config thinking level: str, max output tokens: int = 1024, system: str | None = None : return types.GenerateContentConfig system instruction=system, max output tokens=max output tokens, temperature=0.4, thinking config=types.ThinkingConfig thinking level=thinking level , def generate client, model: str, prompt: str, config=None : return client.models.generate content model=model, contents=prompt, config=config Wire an ask command into the CLI that prints the answer and a one-line usage summary: python carbonlab/cli.py part 2 from carbonlab.client import build config, generate, make client def cmd ask args - int: settings = load settings client = make client settings.api key config = build config args.thinking or settings.thinking level, args.max tokens resp = generate client, settings.model, args.prompt, config print resp.text u = resp.usage metadata print f"\n prompt={u.prompt token count} output={u.candidates token count} " f"thinking={u.thoughts token count} ", file=sys.stderr return 0 Run it: python -m carbonlab.cli ask "Explain HTTP 429 in two sentences." HTTP 429 means the client sent too many requests in a given window, so the server refuses further calls until the limit resets. A well-behaved client reads the Retry-After header when present and backs off exponentially with a little random jitter. prompt=9 output=52 thinking=118 The sample numbers are illustrative, yet the shape is real: thinking tokens show up in a separate counter, and on a short question they can outnumber the visible answer. That brings up the next step. Step 5: Read Token Usage and Price Thinking Tokens Carbon is a reasoning model, and reasoning is not free. Real Python’s explainer on Carbon https://realpython.com/gemini-4-carbon/ frames it as a model that thinks longer, and the pricing page analysis from Apidog https://apidog.com/blog/gemini-4-carbon-pricing/ reports that thinking tokens bill at the output rate. In one example drawn from Google’s documentation, the model thought for 297 tokens to write 171, so most of the charge landed on text the user never saw. Plan on that behavior until your own ledger says otherwise. That makes three counters worth tracking per request: prompt tokens minus any cached portion , cached tokens, and output tokens including thinking. Build the cost module around exactly those fields and keep the price table in one place with the cutover date written down. The usage object returned with every response carries the numbers you need: - prompt token count is everything you sent, including the system instruction, the conversation history and any cached content. - cached content token count is the part of the prompt served from cache, which bills at the cached rate. - candidates token count is the visible answer. - thoughts token count is the hidden reasoning, billed with output. - total token count is the sum, useful as a cross-check against the other fields. If the sum of your own fields drifts from the total, the SDK or the API changed a field, and that is exactly the kind of drift a test should catch. python carbonlab/usage.py import json from dataclasses import dataclass from datetime import date, datetime, timezone from decimal import Decimal from pathlib import Path INTRO ENDS = date 2026, 11, 30 LEDGER = Path "usage.jsonl" @dataclass frozen=True class Rate: input: Decimal cached: Decimal output: Decimal INTRO = Rate Decimal "2" , Decimal "0.10" , Decimal "10" STANDARD = Rate Decimal "4" , Decimal "0.20" , Decimal "20" class BudgetExceeded RuntimeError : pass def rate for day: date - Rate: return INTRO if day <= INTRO ENDS else STANDARD def cost usd usage, day: date | None = None - Decimal: rate = rate for day or date.today prompt = usage.prompt token count or 0 cached = usage.cached content token count or 0 out = usage.candidates token count or 0 + usage.thoughts token count or 0 fresh = max prompt - cached, 0 total = Decimal fresh rate.input + Decimal cached rate.cached + Decimal out rate.output return total / Decimal 1 000 000 def record model: str, usage, cost: Decimal, label: str = "" - None: row = { "ts": datetime.now timezone.utc .isoformat , "model": model, "label": label, "prompt": usage.prompt token count or 0, "cached": usage.cached content token count or 0, "output": usage.candidates token count or 0, "thinking": usage.thoughts token count or 0, "cost usd": str cost , } with LEDGER.open "a", encoding="utf-8" as fh: fh.write json.dumps row + "\n" def spent today - Decimal: if not LEDGER.exists : return Decimal "0" today = datetime.now timezone.utc .date .isoformat total = Decimal "0" for line in LEDGER.read text encoding="utf-8" .splitlines : row = json.loads line if row "ts" .startswith today : total += Decimal row "cost usd" return total def check budget limit: float - None: spent = spent today if spent = Decimal str limit : raise BudgetExceeded f"Daily budget ${limit:.2f} reached spent ${spent:.4f} ." Two design choices deserve a note. Decimal arithmetic keeps fractions of a cent exact, which matters when you sum thousands of tiny charges. And the ledger lives in a plain JSONL file, so you can grep it, load it into a spreadsheet, or diff it against Google’s billing export at month end. Now call the ledger from ask . Add these lines right after the response comes back: carbonlab/cli.py inside cmd ask, after resp = generate ... from carbonlab.usage import check budget, cost usd, record check budget settings.daily budget usd place this BEFORE the generate call c = cost usd resp.usage metadata record settings.model, resp.usage metadata, c, label="ask" print f" cost=${c:.6f} ", file=sys.stderr A second run now prints a cost line and the ledger grows by one row: prompt=9 output=52 thinking=118 cost=$0.001718 Carbon bills input at $2 per million tokens and output at $10 per million tokens through November 30, 2026. From December 1, 2026 the rates are $4 and $20, so the same request costs twice as much. Step 6: Stream Responses for Faster Perceived Latency Reasoning models pause before they talk. Streaming hides part of that wait because the first visible token arrives as soon as the model finishes thinking, instead of after the full answer is assembled. The SDK exposes streaming as a generator, and the usage metadata arrives on the final chunk. python carbonlab/client.py add def stream client, model: str, prompt: str, config=None : last = None for chunk in client.models.generate content stream model=model, contents=prompt, config=config : if chunk.text: yield chunk.text last = chunk yield " usage ", getattr last, "usage metadata", None The sentinel tuple is a small hack to carry usage out of a generator without a class. Consume it in the CLI like this: python carbonlab/cli.py part 3 import time from carbonlab.client import stream def cmd stream args - int: settings = load settings check budget settings.daily budget usd client = make client settings.api key config = build config args.thinking or settings.thinking level, args.max tokens started = time.perf counter first = None usage = None for piece in stream client, settings.model, args.prompt, config : if isinstance piece, tuple : usage = piece 1 continue if first is None: first = time.perf counter - started print piece, end="", flush=True total = time.perf counter - started print f"\n\n first token {first:.2f}s, total {total:.2f}s ", file=sys.stderr if usage: c = cost usd usage record settings.model, usage, c, label="stream" print f" cost=${c:.6f} ", file=sys.stderr return 0 Sample run: bash $ python -m carbonlab.cli stream "List three failure modes of retry loops." 1. Retry storms: every client retries at once and amplifies the outage. 2. Non-idempotent calls: a retried POST charges the customer twice. 3. Unbounded attempts: the loop never gives up and hides a permanent error. first token 2.84s, total 4.10s cost=$0.002290 Your timings will differ with thinking level, load and region. Streaming is not free of trade-offs. It keeps a connection open longer, it complicates retries because a stream can fail halfway through an answer, and it makes JSON output harder to validate until the final chunk arrives. Stream for chat-style interfaces where a human watches the text appear. Skip it for batch jobs, structured extraction and anything a program consumes, where a single complete response is simpler and easier to retry cleanly. The point is the gap between first token and total time. If you want to compare that gap across vendors on identical prompts, a cross-vendor API test harness https://shattered.io/chatgpt-vs-claude-vs-gemini-api-test-harness-12-steps-2026/ gives you a fair way to measure it. One streaming caveat bites early. Community reports from November 12 describe a model-identity mismatch in Carbon streaming responses, so log the model name you requested and never trust a self-reported identity string inside the generated text. Step 7: Add Function Calling With a Real Tool Tool use lets the model ask your code for facts instead of guessing. The SDK can run Python functions for you: pass the function in tools , keep the type hints and docstring accurate, and the library builds the schema, executes the call and feeds the result back to the model. Use a tool that ties into this project’s own purpose, a price checker that answers “what would this request cost on a given day?”: python carbonlab/tools.py from datetime import date from types import SimpleNamespace from carbonlab.usage import cost usd def price check prompt tokens: int, output tokens: int, on date: str - dict: """Estimate the Gemini 4 Carbon API cost in USD for one request. Args: prompt tokens: Input tokens sent with the request. output tokens: Output tokens including thinking tokens. on date: Calendar date in YYYY-MM-DD format used to pick the price period. """ usage = SimpleNamespace prompt token count=prompt tokens, cached content token count=0, candidates token count=output tokens, thoughts token count=0, day = date.fromisoformat on date return {"on date": on date, "cost usd": str cost usd usage, day } Hook it into a tool command: python carbonlab/cli.py part 4 from google.genai import types from carbonlab.tools import price check def cmd tool args - int: settings = load settings check budget settings.daily budget usd client = make client settings.api key config = types.GenerateContentConfig tools= price check , max output tokens=args.max tokens, thinking config=types.ThinkingConfig thinking level=settings.thinking level , resp = client.models.generate content model=settings.model, contents=args.prompt, config=config print resp.text c = cost usd resp.usage metadata record settings.model, resp.usage metadata, c, label="tool" return 0 bash $ python -m carbonlab.cli tool "A request sends 1000 input tokens and gets 468 output tokens. Compare the cost on 2026-11-20 and 2026-12-05." On 2026-11-20 the request costs about $0.00668. On 2026-12-05 it costs about $0.01336, exactly double, because the introductory Carbon price ends on November 30. When you need control, such as human approval before a tool with side effects runs, disable the automatic loop with types.AutomaticFunctionCallingConfig disable=True and read resp.function calls yourself. Never give a model a tool that deletes, pays or emails without that approval gate. Anything the model can call, a prompt-injected document can also try to call. Step 8: Force Structured JSON Output Free-form text breaks parsers. Constrain the response with a schema and let Pydantic validate it. This is the step that turns a chatty model into a dependable component. python carbonlab/schemas.py from typing import Literal from pydantic import BaseModel class TicketTriage BaseModel : category: Literal "billing", "bug", "feature", "other" urgency: int summary: str needs human: bool python carbonlab/cli.py part 5 from carbonlab.schemas import TicketTriage def cmd triage args - int: settings = load settings check budget settings.daily budget usd client = make client settings.api key config = types.GenerateContentConfig system instruction="Classify support tickets. Urgency runs from 1 low to 5 outage .", response mime type="application/json", response schema=TicketTriage, max output tokens=args.max tokens, thinking config=types.ThinkingConfig thinking level="low" , resp = client.models.generate content model=settings.model, contents=args.prompt, config=config ticket = resp.parsed if not isinstance ticket, TicketTriage or not 1 <= ticket.urgency <= 5: raise SystemExit f"Invalid triage output: {resp.text r}" print ticket.model dump json indent=2 c = cost usd resp.usage metadata record settings.model, resp.usage metadata, c, label="triage" return 0 bash $ python -m carbonlab.cli triage "Our invoice shows two charges for November and the dashboard is down for the whole team." { "category": "billing", "urgency": 4, "summary": "Duplicate November charge reported alongside a team-wide dashboard outage.", "needs human": true } Notice that range validation happens in your code and not in the schema. Schema keywords vary in how strictly a model honors them, whereas a plain if statement always works. Treat the schema as strong guidance and your validator as the contract. Schema design matters as much as the call itself. Prefer enums over free strings for categories, because a closed set is far easier to validate and to count in a dashboard. Keep field names plain and descriptive, since the model reads them as hints. Avoid deeply nested objects when a flat structure will do, and give every field a purpose you could explain in one sentence. When a field is optional, say so in the system instruction, or the model will invent a value to fill the slot. Step 9: Build the Cost Calculator Before December 1 Google’s announcement set a hard cutover, and the pricing analysis from Apidog adds that batch discounts scale with the price, so the 50% batch discount it describes stays in place after the doubling. Whatever your volume, model the two periods side by side now. The table below sets out example scenarios for both periods, with no caching unless a row says otherwise. | Scenario | Through Nov 30 | From Dec 1 | |---|---|---| | 1 request | Not listed | Not listed | | 1,000 requests | Not listed | Not listed | | 10,000 requests | $66.80 | $133.60 | | 100,000 requests | Not listed | Not listed | | 10,000 requests, thinking cut to 100 tokens | Not listed | Not listed | | 10,000 requests, 800 of 1,000 input tokens cached | Not listed | Not listed | The last two rows show where savings come from. Trimming 197 thinking tokens per request cuts about 30% of the bill, and caching an 800-token shared prefix cuts about 23%. Output still dominates this request, so thinking control beats caching here. If your prompts carry long documents and your answers stay short, caching moves much further. Run the numbers on your own token mix with a small cost command: python carbonlab/cli.py part 6 from datetime import date from types import SimpleNamespace def cmd cost args - int: usage = SimpleNamespace prompt token count=args.prompt tokens, cached content token count=args.cached, candidates token count=args.output tokens, thoughts token count=0, per req intro = cost usd usage, date 2026, 11, 30 per req std = cost usd usage, date 2026, 12, 1 n = args.requests print f"Through Nov 30: ${per req intro n:,.2f} for {n:,} requests" print f"From Dec 1: ${per req std n:,.2f} for {n:,} requests" print f"Increase: ${ per req std - per req intro n:,.2f}" return 0 bash $ python -m carbonlab.cli cost --prompt-tokens 1000 --output-tokens 468 --requests 10000 Through Nov 30: $66.80 for 10,000 requests From Dec 1: $133.60 for 10,000 requests Increase: $66.80 If your task does not need a reasoning model at all, such as classifying short texts or scoring decisions, look at Google’s cheaper endpoints. The Decisions API pricing https://shattered.io/gemini-decision-1-decisions-api-1000-questions-0-10-per-million-2026/ sits far below Carbon’s per-token rates for that narrow job. One billing wrinkle to watch: a community report says some AI Studio billing dashboards appeared to charge standard rather than promotional prices during the intro window. Reconcile your ledger against the dashboard weekly, and ask Google support if the two diverge. Steps 10 and 11: Retries, Budget Guards and Cost Controls Step 10: Retry transient failures with backoff and jitter Rate limits and server faults happen on any hosted API, so retries are not optional. The rule is simple: retry only errors that can heal rate limits and server faults , cap the attempts, and add random jitter so a thousand clients do not retry in lockstep. python carbonlab/client.py replace generate with this version import random import sys import time from google.genai import errors RETRYABLE = {429, 500, 502, 503, 504} def generate client, model: str, prompt: str, config=None, max attempts: int = 5, sleep=time.sleep : delay = 1.0 for attempt in range 1, max attempts + 1 : try: return client.models.generate content model=model, contents=prompt, config=config except errors.APIError as exc: if exc.code not in RETRYABLE or attempt == max attempts: raise wait = delay + random.uniform 0, delay / 2 print f"retry {attempt}/{max attempts - 1} after HTTP {exc.code}, waiting {wait:.1f}s", file=sys.stderr sleep wait delay = min delay 2, 30.0 The sleep parameter exists so tests can pass a no-op and finish instantly. A failing run prints something like this: retry 1/4 after HTTP 503, waiting 1.3s retry 2/4 after HTTP 503, waiting 2.6s A bad request or a permission error is not retryable. Retrying a bad request wastes time, and retrying a permission error can trip abuse protections. Two companions to retries are worth adding early. Set a client-side timeout so a stalled connection fails in seconds instead of hanging a worker, and keep the calls themselves idempotent. Text generation is safe to repeat, but a tool that charges a card or sends an email is not, so give those tools an idempotency key and check it before acting. Retries multiply whatever your code does, good or bad. Step 11: Route cheap work away from Carbon and cap thinking Three levers cut spend without touching quality much. Lower the thinking level on simple prompts, because Apidog’s reading of Google’s thinking guide says Carbon defaults to a medium level and also accepts low and high. Keep a stable prompt prefix so implicit caching can bill repeated input at the 95% discount Google announced. And route easy requests to the faster model. python carbonlab/client.py add def pick model settings, prompt: str, needs deep reasoning: bool - tuple str, str : if needs deep reasoning or len prompt 4000: return settings.model, "medium" return settings.fast model, "low" This router is deliberately crude. A length check and an explicit flag beat a clever classifier until your ledger proves otherwise. After a week of data, look at the label and thinking columns, find the labels where thinking tokens dominate, and lower the level for those first. Independent quality-per-dollar data, such as the Artificial Analysis index results for Carbon https://shattered.io/gemini-4-carbon-artificial-analysis-59-claude-opus-5-5-2026/ , helps you decide which prompts deserve the premium model. Finally, assemble the entry point so every command works from one file: php carbonlab/cli.py part 7, bottom of file def main argv=None - int: p = argparse.ArgumentParser prog="carbonlab" sub = p.add subparsers dest="cmd", required=True sub.add parser "models" .set defaults fn=cmd models for name, fn in "ask", cmd ask , "stream", cmd stream , "tool", cmd tool , "triage", cmd triage : sp = sub.add parser name sp.add argument "prompt" sp.add argument "--max-tokens", type=int, default=1024 sp.add argument "--thinking", choices= "low", "medium", "high" sp.set defaults fn=fn c = sub.add parser "cost" c.add argument "--prompt-tokens", type=int, required=True c.add argument "--output-tokens", type=int, required=True c.add argument "--cached", type=int, default=0 c.add argument "--requests", type=int, default=1 c.set defaults fn=cmd cost args = p.parse args argv return args.fn args if name == " main ": raise SystemExit main Because the file grows through several parts, keep all imports at the top of cli.py when you merge the snippets. Python does not care where an import sits, but flake8 and your teammates do. Step 12: Test the Project and Wire It Into CI Tests for an API client should never need the API. Test the parts you own: the price math, the cutover date, the retry policy and the budget guard. Use fakes for the network. python tests/test usage.py from datetime import date from decimal import Decimal from types import SimpleNamespace import pytest from carbonlab import usage def u prompt=1000, cached=0, out=171, think=297 : return SimpleNamespace prompt token count=prompt, cached content token count=cached, candidates token count=out, thoughts token count=think def test intro price last day : assert usage.cost usd u , date 2026, 11, 30 == Decimal "0.00668" def test price doubles on dec first : assert usage.cost usd u , date 2026, 12, 1 == Decimal "0.01336" def test cached tokens use cached rate : cost = usage.cost usd u prompt=1000, cached=800, out=0, think=0 , date 2026, 11, 30 assert cost == Decimal "0.00048" def test budget guard tmp path, monkeypatch : monkeypatch.setattr usage, "LEDGER", tmp path / "usage.jsonl" usage.record "gemini-4-carbon", u , Decimal "1.50" with pytest.raises usage.BudgetExceeded : usage.check budget 1.00 usage.check budget 5.00 python tests/test retry.py import pytest from google.genai import errors from carbonlab.client import generate class FlakyModels: def init self, failures, code : self.failures, self.code, self.calls = failures, code, 0 def generate content self, kwargs : self.calls += 1 if self.calls <= self.failures: raise errors.APIError self.code, {"error": {"message": "boom"}} return "ok" class FakeClient: def init self, failures, code : self.models = FlakyModels failures, code def test retries then succeeds : client = FakeClient failures=2, code=503 assert generate client, "m", "hi", sleep=lambda s: None == "ok" assert client.models.calls == 3 def test does not retry client errors : client = FakeClient failures=1, code=400 with pytest.raises errors.APIError : generate client, "m", "hi", sleep=lambda s: None assert client.models.calls == 1 Run them: python -m pytest -q ...... 100% 6 passed in 0.21s The cutover test earns its keep. When someone edits INTRO ENDS or the rates, a red test tells them before the invoice does. Add one live smoke test only if you accept the cost, and gate it on an environment variable so CI stays free. A minimal GitHub Actions workflow runs the offline suite on every push: .github/workflows/test.yml name: test on: push, pull request jobs: pytest: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: "3.12" - run: pip install -r requirements.txt - run: python -m pytest -q Store the real key as a repository secret only if you add the live test, and never echo it in a log step. Common Pitfalls Most failures in a first Gemini API project come from the same few habits. The table lists the ones that cost developers the most time or money. | Pitfall | Symptom | Fix | |---|---|---| | Hard-coding the model ID | Calls fail after a model is replaced or its access is restricted | Read the ID from .env and run the models check on startup | | Ignoring thinking tokens | Bills far above what visible text suggests | Log thoughts token count and lower THINKING LEVEL | | Setting max output tokens too low | Empty or cut-off text with a MAX TOKENS finish reason | Raise the cap, since thinking can consume part of the budget | | Budgeting with intro prices after November 30 | Spend doubles on December 1 | Use the dated rate table in usage.py and a daily cap | | Retrying every error | Wasted calls on client errors that can never succeed | Retry only 429 and 5xx codes, with jitter | | Treating a subscription as API access | Carbon works in the app but the API returns permission errors | Enable billing for the API project separately from any Ultra or Pro plan | | Committing the key | Surprise charges and a revoked key | Keep .env in .gitignore and rotate any exposed key at once | A subtler pitfall deserves its own sentence. Community measurements claim Carbon and Argon consume Antigravity subscription quota at roughly three times the rate of Gemini 3.8 Flash. That is an unconfirmed report about a consumer subscription, not API billing, so do not carry that multiplier into your cost model. Troubleshooting Work through these in order when something breaks. Most problems resolve in the first three. 1. Model not found error for gemini-4-carbon . Run the models command. If Carbon is missing, your project may lack billing, your region may lag the rollout, or the ID changed. Confirm against Google’s model documentation, then update CARBON MODEL . 2. Permission denied error. The key belongs to a project without access to the model, or the API is not enabled. Create a key under the billing-enabled project and retry. 3. 429 rate limit or quota errors. Check your tier in the AI Studio rate-limit dashboard. Forum reports note that some models are unavailable on the free tier. Back off, lower concurrency, or move to a paid tier. 4. Model overloaded error. A server-side capacity problem. The retry wrapper handles brief spikes. If failures persist for minutes, route to the fast model temporarily. 5. Empty resp.text or None . Check the finish reason. A MAX TOKENS stop usually means thinking consumed the budget. Raise max output tokens or lower the thinking level. A safety block returns no text either, so inspect resp.candidates . 6. resp.parsed is None in triage. The model returned JSON that failed the schema. Print resp.text , simplify the schema, and keep enum values short and unambiguous. 7. The tool never runs. Add a clearer docstring and type hints, and name the tool in your prompt. Vague docstrings give the model no reason to call the function. 8. ImportError on from google import genai . You probably have the legacy google-generativeai package shadowing the new SDK. Create a clean virtual environment and install only google-genai . 9. “User location is not supported”. Your request originates from a region the API does not serve. Run from a supported region and check that no proxy rewrites your exit location. 10. Costs on the dashboard exceed your ledger. The dashboard counts thinking tokens, retries that reached the server and calls from other scripts that share the key. Rotate the key and compare again, and remember the report that some dashboards showed standard rather than promotional prices. 11. Streaming shows no cost line. Usage metadata arrives on the last chunk. If your loop breaks early, the ledger misses that request. Always drain the generator. Advanced Tips Once the basics run clean, a few upgrades pay off quickly. - Count before you send. Call client.models.count tokens on large documents and refuse requests whose estimated cost exceeds a per-request ceiling. This catches an accidental 500-page paste before it bills. - Design prompts for implicit caching. Put the long, unchanging material instructions, reference text first and the variable question last. Repeated prefixes bill at the cached rate, which Google set at 95% below the input price. - Try the batch route for offline jobs. Apidog’s pricing breakdown reports a 50% batch discount that persists after the December increase. Overnight classification and summarization jobs fit that model. - Log prompt hashes, not prompts. A SHA-256 of the prompt lets you spot duplicate work and caching misses without storing sensitive text in your ledger. - Watch the newer API surface. Google’s documentation describes an Interactions API labeled beta alongside a stable v1. Pin your SDK version and read the changelog before adopting it in production code. - Use Carbon for hard problems and say so. Carbon has also been applied to formal verification, as in the report on Carbon checking Signal’s library with Lean proofs https://shattered.io/gemini-4-carbon-access-signal-libsignal-alphaproof-code-6-5m-lean-proofs-2026/ , which shows what the long-thinking mode is for. Short chat tasks rarely need it. - Alert on spend, not just errors. Send a message when spent today passes 80% of the cap. The cheapest outage is the one you see coming. - Review the ledger weekly. Group rows by label and sort by cost. Two or three labels usually account for most of the spend, and those are the prompts worth rewriting or routing to the faster model. - Keep a golden prompt set. Save ten real prompts with answers you have judged acceptable, and rerun them after every model or price change. A cheap model that fails three of ten is not cheaper once you count the human cleanup. For wider context on model releases, benchmarks and safety, browse the AI and machine learning coverage https://shattered.io/category/ai-machine-learning/ . FAQ How do I get a Gemini API key? Sign in to Google AI Studio with a Google account, create a key inside a project and copy it. Store it in an environment variable or a secrets manager and never commit it to git. For Gemini 4 Carbon you also need billing enabled on that project, because Google describes the model as available to paying developers. How much does the Gemini 4 Carbon API cost? Google priced Carbon at $2 per million input tokens and $10 per million output tokens through November 30, 2026. From December 1 the price becomes $4 per million input tokens and $20 per million output tokens. Cached input tokens carry a 95% discount from the input price, according to Google’s announcement. Does the price go up for existing users on December 1? Google’s published pricing names no exception for existing projects. Plan to pay $4 and $20 per million tokens on every Carbon token sent on or after December 1, and use the dated rate table from this project to model the change. Is the Gemini API free? Google’s billing documentation describes a free tier and a paid pay-as-you-go tier. Carbon launched for paying developers and enterprises, so expect to need the paid tier for it. A key that works on the free tier may still list other models and reject Carbon. Does a Google AI Ultra or Pro subscription include API access? Not automatically. Ultra gives subscribers Carbon in the Gemini app, AI Mode in Search and Google Antigravity, while the Gemini API bills by token on its own account. Check your Google AI Studio billing page for any credits that come with your plan. Which Python SDK should I use? Use the current google-genai package and import it with from google import genai . Avoid mixing it with the legacy google-generativeai library in the same environment. Should I use Carbon or Hydrogen? Use Carbon for deep, long-horizon reasoning and hard coding problems. Use Hydrogen, introduced on November 12, when speed matters more, such as agent loops. Run both through the same ledger for a week and compare cost per successful task before you commit.