Verified baseline:
2026-11-14(Asia/Taipei, UTC+8) on macOS Apple Silicon (ts-m1),gemini-api 0.4.6, plus our2026-11-15live execution onpaid-media-projectsummarized in Section 10. Runtime HTTP 403 scope diagnostics and Paid Tier live execution are observed tool outputs; pricing, quota, and consumer migration boundaries come directly from official Google documentation.📚 Series Navigation
- 📘 Part 1 (Dev.to): https://dev.to/jimmyliao/gemini-api-cli-official-guide-part-1-giving-your-ai-agent-a-stateless-multimodal-cli-toolbox-36p3
- 📝 Part 1 (Substack): https://memo.jimmyliao.net/p/gemini-api-cli-part-1-agent-api
- 🇹🇼 Part 2 (Substack, Traditional Chinese): https://memo.jimmyliao.net/p/gemini-api-cli-part-2keyless-adcscope
- ▶️ YouTube 16:9 Walkthrough (Part 1): https://youtu.be/Rb5ij419w2Y
- ⚡ YouTube Shorts (Part 1): https://youtube.com/shorts/82-Z_Jq-ezQ
1. Introduction: Why "Keyless" & Why You Must Track the Real Billing Pool
Part 1 introduced the standalone multimodal CLI. Once AI agents operate across laptops, containers, and CI runners, two architectural questions immediately arise:
- Can we avoid scattering static
AIza*API keys on disk while attributing every request cleanly to a designated GCP project? - Which billing or quota pool actually absorbs the cost?
Keyless OAuth answers the first question by minting short-lived bearer access tokens from your existing identity and attaching an explicit quota project header. Importantly, keyless does not mean credential-less: local ADC still stores an underlying refresh credential, short-lived bearer tokens remain secrets, and OAuth never bypasses IAM roles, API enablement, or Cloud Billing.
A second widespread misconception is "I pay for Google AI Pro / Ultra, so logging in with that Google account makes Gemini API calls free." Your Google Account is an identity; Google One / Antigravity is a consumer subscription pool; the Developer API (generativelanguage.googleapis.com) belongs to a GCP project / Cloud Billing pool. Even promotional or Promotional Cloud credits must be checked per billing account, eligible SKU, and expiration date.
Primary evidence lives in experiments/03-part2-keyless-adc/results.md, experiments/04-tier-limits-and-errors/tier-research.md, and gde-feedback/upstream-issues-draft.md.
2. Source Code Audit: How v0.4.6 Implements Keyless OAuth
To verify exact release behavior rather than relying on an earlier snapshot, we inspected four source files directly in tag v0.4.6:
Source File (v0.4.6) |
Observed Responsibility & Limitation |
|---|---|
internal/cli/auth.go |
runAuthLoginCmd persists an existing API key or access-token string via config.StoreSecret / config.SaveConfig; it never launches a browser OAuth flow or acquires refresh credentials. |
internal/config/config.go |
SecurityConfig.AccessToken maps to YAML access_token across flags, env vars, OS Keychain, and ~/.config/gemini-api/config.yaml (not config.json). |
internal/cli/configure.go |
runConfigureCmd writes credentials and global parameters including user-project locally. |
internal/client/client.go |
BuildGlobalSecurity selects API key or access token; buildGlobalOptions maps user-project to sdk.WithUserProject. No native ADC discovery or token auto-refresh source exists here yet. |
GEMINI_ACCESS_TOKEN / --access-token supplies the bearer credential (who is calling), whereas --user-project sets the x-goog-user-project header (which GCP project owns quota & billing). Never pass tokens on the command line where process inspection (ps) can read them—inject via subprocess environment variables instead.
General credential precedence follows flag -> environment -> Keychain -> config, and the Go client picks a complete explicit credential over fallback paths. Therefore our wrapper unsets inherited GEMINI_API_KEY variables before injecting a fresh ADC access token. Merely setting GOOGLE_APPLICATION_CREDENTIALS does not make v0.4.6 discover or refresh ADC natively. See OAuth quickstart and API CLI docs.
3. Debugging on ts-m1: HTTP 403 ACCESS_TOKEN_SCOPE_INSUFFICIENT
A Valid Token Still Fails Without the Right Scope
On ts-m1, the active gcloud/ADC identity sjliao@gmail.com (authorized_user, quota_project_id: leapcore-dev) held cloud-platform, sqlservice.login, userinfo.email, email, and openid—but lacked https://www.googleapis.com/auth/generative-language:
| Live Call Tested | Process Exit | HTTP / Error Reason | Engineering Conclusion |
|---|---|---|---|
models list (no project header) |
3 |
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT |
Default Cloud ADC token lacks generative-language scope |
models list --user-project gdg-kc-465418 |
3 |
Same | Switching --user-project cannot fix a token scope gap |
generate with gdg-kc-465418
|
3 |
403 PERMISSION_DENIED / same reason |
Zero inference response or usage incurred |
Wrapper generate with leapcore-dev
|
3 |
Same |
billingEnabled=true cannot compensate for missing OAuth scope |
Proper Re-Authorization & Desktop OAuth Client Fallback
gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/generative-language,https://www.googleapis.com/auth/generative-language.retriever,https://www.googleapis.com/auth/userinfo.email,openid"
Note why all of those scopes appear: the official /docs/oauth guide demonstrates cloud-platform + generative-language.retriever, whereas live generate calls explicitly requested https://www.googleapis.com/auth/generative-language. If Google's default gcloud client blocks sensitive scopes for your workspace or account, create a Desktop app OAuth Client in Google Cloud Console (configuring your consent screen / test users per OAuth quickstart), store client_secret.json outside the repo, and pass --client-id-file <path>:
./bin/gapi-adc --print-reauth
# Re-authorization modifies local ADC and opens a browser:
./bin/gapi-adc --reauth --client-id-file /secure/path/outside/repo/client_secret.json
Scope is not IAM: the target quota project must also enable generativelanguage.googleapis.com and grant the caller serviceusage.services.use.
4. Practical Tooling: Operating bin/gapi-adc
bin/gapi-adc calls gcloud auth application-default print-access-token right before live invocations, captures the short-lived token in memory, exports GEMINI_ACCESS_TOKEN, and execs gemini-api without ever persisting tokens to disk or CLI config. (Long-running polling loops past token TTL still require a refreshing client or periodic re-invocation.)
Because gemini-api v0.4.6 rejects -p (exit 2: unknown shorthand flag), the wrapper maps -p to --user-project. Project resolution order is: explicit --user-project/-p -> GAPI_USER_PROJECT -> scalar user_project/user-project in ~/.config/gemini-api/config.yaml -> gcloud core/project.
./bin/gapi-adc --help
./bin/gapi-adc --print-auth-status
./bin/gapi-adc --print-reauth
./bin/gapi-adc generate "hi" --dry-run
./bin/gapi-adc generate "hi" --user-project gdg-kc-465418 --dry-run
./bin/gapi-adc generate "hi" -p gdg-kc-465418 --dry-run
--print-auth-status safely inspects ADC type and quota_project_id (redacting refresh tokens/secrets), queries Google's tokeninfo endpoint via stdin so the token never appears in curl argv:
curl -sS -m 15 -X POST -d @- https://oauth2.googleapis.com/tokeninfo
It reports PRESENT/MISSING for both generative-language scopes, expires_in, and a masked email, returning exit 0 even when scopes are missing (diagnostic mode—never treat exit 0 of --print-auth-status as CI auth proof). Normal execution exits 3 on token failure, 2 if no project is resolved, 127 on missing binaries, or passes through gemini-api's exit code. --dry-run skips gcloud network calls completely.
5. Project & Cloud Billing Audit (sjliao@gmail.com)
Inspecting the actual GCP projects under sjliao@gmail.com illustrates why billingEnabled, OPEN billing accounts, and API enablement must be verified separately:
| Project ID(s) |
billingEnabled / Billing Account |
generativelanguage.googleapis.com Status |
|---|---|---|
jimmyliao-dev, gcp-trial-423705, gen-lang-client-0954497962, bwai2026-jimmyliao, bwai2026-jimmyliao-ws, io26-496910
|
false (bwai2026-jimmyliao retains historical linkage) |
Listed enabled -> Free Tier candidates |
gdg-kc-465418 |
true (01XXXX-XXXXXX-PAID01) |
Enabled -> generate blocked earlier by ADC scope 403 |
paid-media-project, credits-project-a, credits-project-b
|
true (Cloud_Credits / 01XXXX-XXXXXX-CREDITS) |
Enabled -> Paid / Cloud Credits candidates (paid-media-project verified live on 2026-11-15) |
leapcore-dev |
true (same Cloud_Credits account) |
Raw gcloud services list --enabled returned Listed 0 items. (contradicts earlier assumption) |
jimmyliao-ai-proj, bwai2026, gdg-ws-0523, gdgyep2026
|
false |
Not listed in enabled services |
Billing account checks also confirmed both billing-acct-secondary (01XXXX-XXXXXX-SECOND) and Cloud_Credits (01XXXX-XXXXXX-CREDITS) are OPEN=True, and showed why cloudbilling.googleapis.com on a consumer project sometimes needs --billing-project=jimmyliao-dev separately from --user-project.
6. Three User Layers: Free, Paid Tier 1–3, and Google AI Pro / Ultra
Free Tier (Unbilled GCP Projects)
-
Auth Paths & Constraints: Either AI Studio Free API keys (note that since 2026-05-28, newly created keys default to service-account-bound authorization keys rather than legacy keyless identities; verify regional availability and verification status) or OAuth/ADC (
GEMINI_ACCESS_TOKEN+--user-project <unbilled-project>withgenerativelanguage.googleapis.comenabled andserviceusage.services.useIAM). See API keys, OAuth, and ADC troubleshooting. -
RPM / TPM / RPD & Reset Time: Limits are enforced per project, not per key (multiple keys on the same project share one quota). RPD resets at Pacific midnight: 15:00 Asia/Taipei during PDT (
UTC-7) and 16:00 Asia/Taipei during PST (UTC-8, active in November). Current general numeric quotas live behind the authenticated AI Studio Rate Limits dashboard; a published exception is Gemini Decision 1 Free at200 RPM / 50,000 TPM / 10,000 RPD, whilegemini-omni-1.2-flashhas no Free Tier. See rate limits. - Feature Availability Matrix:
| Capability | Free vs. Paid Boundary (per Official Docs) |
|---|---|
| Text / Multimodal Input Analysis | Selected models offer Free Tier; free multimodal input does not imply free image/video output |
| Image Generation |
gemini-3.1-flash-image (Nano Banana 2) & gemini-nano-banana-2.1 list API Free Tier as Not available (AI Studio UI previews do not grant programmatic Free quota) |
| Text-to-Speech (TTS) |
gemini-3.8-flash-tts, 3.1 Flash TTS Preview, and 2.5 Flash Preview TTS allow Free Standard; Batch has no Free Tier |
| Video Generation | Current gemini-omni-1.2-flash is paid-only; legacy Veo 3.1 Preview shut down on 2026-10-22 (Veo GA lives in Enterprise Agent Platform, a separate surface) |
| Search Grounding | Not strictly paid-only: 2.5 Flash Standard offers 500 RPD free (shared with Flash-Lite); Gemini 3+ models include 5,000 monthly free Search requests then $14 / 1,000, capped at 1,500 RPD per project by default |
| Batch / Context Caching | No Free Tier for explicit context caching or Batch on checked models (2.5 Flash); paid Batch offers independent enqueue quotas |
| Managed / Deep Research Agents | Billed at underlying token rates + tool fees—not bundled in Google One subscriptions |
-
Data Privacy & Interactions Retention: Under Taiwan Unpaid Services terms, prompts and outputs may be used for product improvement/ML training and human review—never send confidential, sensitive, or personal user data on Unpaid projects (EEA/Switzerland/UK have separate legal exemptions). Interactions storage defaults to 1 day on Free vs. 55 days (configurable 7/14/28/55 days) on Paid;
store=falsedisables state persistence (incompatible withbackgroundexecution) but does not override Unpaid terms. See terms and Interactions.
Paid Layer: Tier 1 / 2 / 3 & GCP / Cloud Credits
Verified Tier Upgrade Thresholds
| Tier | Official Qualification Criteria | Monthly Spend Cap per Billing Account |
|---|---|---|
| Tier 1 | Linked active Cloud Billing account; Prepay requires minimum $5 USD top-up (eligible accounts may use Postpay) | $250 USD |
| Tier 2 | $100 USD paid spend + 3 days since first successful payment | $2,000 USD |
| Tier 3 | $1,000 USD paid spend + 30 days since first successful payment | $20,000 – $100,000+ USD (varies by account) |
Cumulative spend aggregates Google Cloud services spend across the linked billing account (upgrades trigger automatically after review: near-instant Free -> Tier 1, ~10 min afterward). Paid Tier 1 also enforces a rolling 10-minute spend rate limit of $10 USD (Tier 2/3: $200 USD), which protects against runaway retries (429).
Regarding Promotional Cloud Credits & Prepay: promotional credits only offset eligible Gemini API SKUs on the matching billing account before expiration. New $300 GCP Welcome Free Trial credits (since March 2026) exclude Gemini API except grandfathered balances within 90 days, and promotional credits alone may not satisfy paid-spend tier upgrade criteria (billing). Prompts sent through active-billing Paid projects are not used to improve Google products (Paid Services terms).
Multimodal Pricing Examples (Standard Paid Tier, USD)
| Modality | Pricing Notes from Docs (2026-11-14/15) |
|---|---|
| Text / Multimodal Understanding |
2.5 Flash: $0.30 / 1M text/image/video input, $1 / 1M audio input, $2.50 / 1M output (deprecated; auto-routes to 3.5 Flash-Lite on 2026-12-01). Current gemini-3.8-flash: $0.75 / 1M in, $3.75 / 1M out+thinking (through 2026-12-31). |
image (3.1 Flash / Nano Banana 2.1) |
Legacy 3.1 Flash Image: $0.067 (1K); current default gemini-nano-banana-2.1: $1.50 / 1M in, $7.50 / 1M text+thinking out, $30 / 1M image out (1,120 tokens = $0.0336 per 1K image). |
video (gemini-omni-1.2-flash) |
$1.50 / 1M in, $9.00 / 1M text out, $12.00 / 1M video out (5,792 tokens/s @ 720p ≈ $0.07/s). |
tts (gemini-3.8-flash-tts) |
Through 2026-12-31: $0.50 / 1M text input, $9.00 / 1M audio output (25 tokens/s ≈ $0.00225 / 10s); doubles starting 2027-01-01. |
| Deep Research / Managed Agents | Underlying model input/output + reasoning-loop intermediate tokens + tool fees; managed sandbox compute currently $0 in preview. |
| Batch Tier | Typically 50% off standard token rates on supported models (not applied to every tool/storage fee). |
Consumer Subscriptions: Google AI Pro / Ultra & the Golden Hybrid Pattern
Effective 2026-06-18, individual Pro/Ultra subscriptions moved from gemini-cli to agy, featuring 5-hour rolling quotas bounded by weekly caps (and optional AI Credits overage inside Antigravity). Because those credits sit strictly inside the consumer/Antigravity pool, logging into gcloud with a Pro/Ultra account does not transfer free API quota to gemini-api.
The Golden Hybrid Pattern resolves this cleanly:
- Keep planning, coding, long-context analysis, and prompt iteration on
agy's subscription pool. - Route deterministic CI / multimodal media generation (
image,video,music,tts) throughgapi-adcto explicitly governed Free or Paid GCP projects.
6.5 End-to-End Scenario (Part 2 Perspective): Running the 9:16 AI Reels Pipeline Across Identity Pools
In planning our 15-second Reels pipeline:
-
Free Candidate (
jimmyliao-dev): can run non-confidential pre-production (generatestoryboard, Standard singletts,analyzeQA), whileimage&omni-1.2-flashvideo remain paid-only. -
Paid / Cloud Credits (
gdg-kc-465418/paid-media-project): required for 9:16 keyframes and 720p video. Pre-execution cost model:
| Item Estimated Pre-Run | Initial Planning Estimate & Constraint |
|---|---|
3.1 Flash Image 1K (prior baseline) |
~$0.067 / image × 3 ≈ $0.201 (v0.4.6 actually defaults to gemini-nano-banana-2.1) |
Omni 1.2 Flash 720p video |
~$0.07 / s × 15s = $1.05 + input tokens |
3.8 Flash TTS |
$0.50 / 1M text in, $9.00 / 1M audio out |
| Strategy Safeguard |
Keyframe-First: inspect 9:16 image keyframes (~$0.05) manually before paying for video motion (~$0.35 / 5s) to avoid tripping Tier 1's $10 rolling 10-minute cap |
Runnable Part 2 Example (sample-part2-adc-tier-router.sh)
Offline project-attribution router dry-run (add --check-live-token locally for live ADC scope diagnostics; source: examples/part2-keyless-adc-tiers/sample-part2-adc-tier-router.sh):
bash <<'PART_SAMPLE'
(
set +x
set -euo pipefail
cd examples/part2-keyless-adc-tiers
unset GEMINI_API_KEY GEMINI_ACCESS_TOKEN GEMINI_ENVIRONMENT_KEY GEMINI_USER_PROJECT
export GEMINI_NO_KEYRING=true
R=../reels-storyboard-pipeline
W=../../bin/gapi-adc
FREE_PROJECT_ID=${FREE_PROJECT_ID:-jimmyliao-dev}
PAID_PROJECT_ID=${PAID_PROJECT_ID:-gdg-kc-465418}
case "${1:-}" in
'') echo 'Offline dry-run: skipping live token and network calls.' >&2 ;;
--check-live-token) "$W" --print-auth-status </dev/null ;;
*) echo 'Usage: sample-part2-adc-tier-router.sh [--check-live-token]' >&2; exit 2 ;;
esac
"$W" --print-reauth </dev/null
verify_project() {
local project=$1
shift
"$W" --agent-mode "$@" -p "$project" --dry-run </dev/null |
python3 -c 'import json,sys; d=json.load(sys.stdin); h=d["request"]["headers"]["X-Goog-User-Project"]; assert h == [sys.argv[1]], h; print(json.dumps(d,ensure_ascii=False)); print("Verified project header: "+sys.argv[1],file=sys.stderr)' "$project"
}
echo 'Stage A: Free candidate pre-production (requires online entitlement check separately)' >&2
verify_project "$FREE_PROJECT_ID" generate 'Plan a 3-scene 9:16 Reels storyboard' --stream=false
verify_project "$FREE_PROJECT_ID" tts 'Welcome to the Multimodal CLI' --out /tmp/part2-voice.wav
verify_project "$FREE_PROJECT_ID" analyze -i "$R/fixtures/scene1-keyframe.png" 'Inspect layout safe-zone'
echo 'Stage B: Paid render dry-run, Keyframe before Video' >&2
verify_project "$PAID_PROJECT_ID" image '9:16 tech Reels keyframe' --aspect-ratio 9:16 --image-size 1K --output-mime-type image/jpeg --out /tmp/part2-keyframe.jpg
verify_project "$PAID_PROJECT_ID" video 'Slow camera push on keyframe' --aspect-ratio 9:16 --resolution 720p -i "$R/fixtures/scene1-keyframe.png" --out /tmp/part2-video.mp4
echo 'Guardrail: Approve keyframe before video render to protect Tier 1 rolling 10-min $10 cap.' >&2
)
PART_SAMPLE
7. 3 × 6 Persona Decision Matrix
| Persona | Authentication | Billing Pool | Quota Reset | Data Privacy | Available Features | Recommended CLI Combo |
|---|---|---|---|---|---|---|
| Free | AI Studio key, or ADC token + unbilled --user-project
|
Project Free quota (no Google One transfer) | RPM/TPM; RPD 15:00 PDT / 16:00 PST (Taipei) | Taiwan Unpaid terms allow product training & review; no confidential data | Selected text/analyze/TTS/Grounding; image/video/Batch/cache restricted | Any coding agent + gemini-api Free (select Free models) |
| Paid Tier 1–3 | Key / auth key, or ADC token + billed --user-project
|
Cloud Billing / Prepay / eligible Promotional Cloud credits | Same RPD + rolling 10-min cap ($10/$200) & billing cap | Paid prompts not used to train Google models; compliance logging applies | Image, video, Managed Agents, Batch, caching per model unlock | Coding agent + gemini-api ADC; pin CLI & project in CI |
| Pro / Ultra |
agy personal OAuth; separate key/ADC for API |
agy 5H + weekly pool (+ optional AI Credits); separate API pool |
agy 5H bounded by weekly cap; API per-project |
agy consumer terms vs. Free/Paid project API terms |
agy coding/Argon; offload specialized multimodal tasks to API |
Golden Hybrid: agy + gemini-api
|
8. Common Error Codes Cheat Sheet
Documented CLI exit codes: 0 success, 1 runtime/API error, 2 usage/validation, 3 auth/authorization. Always inspect both HTTP status and reason:
| HTTP Status / Reason | Next Action | Evidence Type |
|---|---|---|
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT |
Run --print-auth-status, then re-authorize scopes (--reauth); do not swap billing projects to fix scope |
Live local test |
403 SERVICE_DISABLED |
Check which service & consumer project lacked enablement (--billing-project vs --user-project) |
Live Cloud Billing check |
401 / other 403
|
Inspect token expiration, IAM (serviceusage.services.use), API enablement, and project attribution |
Docs diagnostic |
429 RESOURCE_EXHAUSTED |
Distinguish RPM/TPM/RPD, tool caps, and 10-min rolling spend limits; respect server retry backoff | Docs research |
402 Payment Required |
Check Prepay balance / billing account status across the entire linked billing account | Docs research |
9. GDE Upstream Feedback & Official References
Both issue drafts in gde-feedback/upstream-issues-draft.md await submission:
- Requesting native ADC discovery/auto-refresh, clearer credential/project precedence, redacted diagnostics, and actionable
403scope/IAM error messages ingemini-api-cli(applied upstream in Speakeasy spec/generator rather than patched in generated files). - Aligning legacy
gemini-cliconsumer migration documentation banners with internal quota tables.
Official references verified during this research: OAuth quickstart, ADC troubleshooting, API CLI, API keys, Billing, Rate limits, Pricing, Terms, Interactions, Agents, Deep Research, Video, Antigravity plans, Antigravity install, Transition announcement.
10. Live Verification Addendum (2026-11-15): ADC Scope Guardrail & §6.5 Cost Proof
Our 2026-11-15 00:20–00:24 live run confirmed both Part 2 theses in practice:
-
Keyless ADC Scope Boundary Enforced cleanly (
$0.00): Running./bin/gapi-adc --agent-mode generate -p paid-media-projectwithGEMINI_API_KEYunset deterministically exited3(HTTP 403 ACCESS_TOKEN_SCOPE_INSUFFICIENT) because default ADC had not yet run--reauth—proving the wrapper fails loudly instead of silently billing the personal pool. -
§6.5 Keyframe-First Economics Validated: Switching to the
paid-media-projectPaid Tier API key for the full Reels pipeline showed that a single 5s 720p video render (gemini-omni-1.2-flash) accounted for$0.3527 / $0.5485(~64%), while generating two9:16keyframes (gemini-nano-banana-2.1), dual-speaker TTS ($0.0021), and QA ($0.0109) combined cost only~$0.107 USD—proving why gating video generation behind keyframe QA directly protects Tier 1's$10rolling 10-minute cap. Seeexperiments/06-live-execution-and-cost-log/cost-and-call-ledger.md.
Top comments (0)