fix(gemini): surface token usage from image generateContent path (#330)

[tombeckenham]

🎯 Changes

Fixes #330. The Gemini image adapter hardcoded usage: undefined, so ImageGenerationResult.usage was never populated and the image:usage devtools event never fired for Gemini image generation — even though the generateContent response carries usageMetadata.

This parses usageMetadata (promptTokenCount / candidatesTokenCount / totalTokenCount) into usage on the native generateContent path (e.g. Nano Banana), matching the convention already used by the Gemini text adapter.

The Imagen (generateImages) path is intentionally left unchanged: the GenerateImagesResponse SDK type does not expose usageMetadata, so parsing it there would require a speculative as any cast for a field that may never exist.

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Fixed token usage data tracking for Gemini image generation. The image adapter now properly exposes token usage information, including input tokens, output tokens, and total token counts, enabling better monitoring of API consumption and associated costs for image generation requests.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 380a5853-6850-4e1a-ac4c-4555a77c0964

📥 Commits

Reviewing files that changed from the base of the PR and between d5645cf and 8106603.

📒 Files selected for processing (3)

• .changeset/gemini-image-usage.md
• packages/ai-gemini/src/adapters/image.ts
• packages/ai-gemini/tests/image-adapter.test.ts

---

📝 Walkthrough

Walkthrough

The Gemini image adapter now extracts and exposes token usage metadata from the generateContent API response. The implementation parses usageMetadata fields into a standardized usage object, backed by a test case that validates the mapping, and documented in a patch changeset.

Changes

Gemini image adapter usage metadata

Layer / File(s)	Summary
Usage metadata extraction implementation packages/ai-gemini/src/adapters/image.ts	transformGeminiResponse conditionally spreads a usage object derived from response.usageMetadata, mapping promptTokenCount, candidatesTokenCount, and totalTokenCount with zero defaults when metadata is present.
Usage metadata test coverage packages/ai-gemini/tests/image-adapter.test.ts	New test case stubs generateContent to return usageMetadata and asserts that generateImage correctly maps prompt, candidate, and total token counts onto result.usage.
Release note documentation .changeset/gemini-image-usage.md	Changeset patch documents the fix: @tanstack/ai-gemini now parses usageMetadata for the generateContent path while the generateImages path remains unchanged.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 A rabbit hops through token trails so bright,
Where Gemini's usage now shines in the light!
From metadata shadows, the counts leap to gleam—
Input, output, total—a usage dream!
Hopping with tests, the fix is complete. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main fix: surfacing token usage from the image generateContent path, which is the core change across all modified files.
Description check	✅ Passed	The description comprehensively covers the changes, motivation, design decisions (why Imagen path unchanged), and includes all required checklist items completed.
Linked Issues check	✅ Passed	The code changes directly address issue #330 by parsing usageMetadata into ImageGenerationResult.usage for generateContent path, matching the expected behavior specified in the issue.
Out of Scope Changes check	✅ Passed	All changes are directly related to fixing #330: the changeset documents the fix, the adapter parses usageMetadata for generateContent, and tests validate the new behavior.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/gemini-image-usage

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install failed. For unrecoverable errors, disable the tool in CodeRabbit configuration.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🚀 Changeset Version Preview

8 package(s) bumped directly, 22 bumped as dependents.

🟥 Major bumps

Package	Version	Reason
@tanstack/ai-gemini	0.12.0 → 1.0.0	Changeset
@tanstack/ai-preact	0.6.35 → 1.0.0	Changeset
@tanstack/ai-react	0.12.1 → 1.0.0	Changeset
@tanstack/ai-solid	0.10.10 → 1.0.0	Changeset
@tanstack/ai-svelte	0.10.10 → 1.0.0	Changeset
@tanstack/ai-vue	0.10.11 → 1.0.0	Changeset
@tanstack/ai-anthropic	0.11.0 → 1.0.0	Dependent
@tanstack/ai-code-mode	0.1.22 → 1.0.0	Dependent
@tanstack/ai-code-mode-skills	0.1.22 → 1.0.0	Dependent
@tanstack/ai-elevenlabs	0.2.13 → 1.0.0	Dependent
@tanstack/ai-event-client	0.4.0 → 1.0.0	Dependent
@tanstack/ai-fal	0.7.15 → 1.0.0	Dependent
@tanstack/ai-grok	0.9.0 → 1.0.0	Dependent
@tanstack/ai-groq	0.2.7 → 1.0.0	Dependent
@tanstack/ai-isolate-node	0.1.22 → 1.0.0	Dependent
@tanstack/ai-isolate-quickjs	0.1.22 → 1.0.0	Dependent
@tanstack/ai-ollama	0.6.22 → 1.0.0	Dependent
@tanstack/ai-openai	0.10.3 → 1.0.0	Dependent
@tanstack/ai-openrouter	0.9.8 → 1.0.0	Dependent
@tanstack/ai-react-ui	0.8.3 → 1.0.0	Dependent
@tanstack/ai-solid-ui	0.7.3 → 1.0.0	Dependent
@tanstack/openai-base	0.4.0 → 1.0.0	Dependent

🟨 Minor bumps

Package	Version	Reason
@tanstack/ai	0.22.1 → 0.23.0	Changeset
@tanstack/ai-client	0.13.0 → 0.14.0	Changeset

🟩 Patch bumps

Package	Version	Reason
@tanstack/ai-devtools-core	0.4.0 → 0.4.1	Dependent
@tanstack/ai-isolate-cloudflare	0.2.13 → 0.2.14	Dependent
@tanstack/ai-vue-ui	0.2.6 → 0.2.7	Dependent
@tanstack/preact-ai-devtools	0.1.43 → 0.1.44	Dependent
@tanstack/react-ai-devtools	0.2.43 → 0.2.44	Dependent
@tanstack/solid-ai-devtools	0.2.43 → 0.2.44	Dependent

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 8106603

Command	Status	Duration	Result
nx affected --targets=test:sherif,test:knip,tes...	✅ Succeeded	21s	View ↗
nx run-many --targets=build --exclude=examples/...	✅ Succeeded	9s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-05-29 07:09:43 UTC

[pkg-pr-new]

Open in StackBlitz

@tanstack/ai

npm i https://pkg.pr.new/@tanstack/ai@655

@tanstack/ai-anthropic

npm i https://pkg.pr.new/@tanstack/ai-anthropic@655

@tanstack/ai-client

npm i https://pkg.pr.new/@tanstack/ai-client@655

@tanstack/ai-code-mode

npm i https://pkg.pr.new/@tanstack/ai-code-mode@655

@tanstack/ai-code-mode-skills

npm i https://pkg.pr.new/@tanstack/ai-code-mode-skills@655

@tanstack/ai-devtools-core

npm i https://pkg.pr.new/@tanstack/ai-devtools-core@655

@tanstack/ai-elevenlabs

npm i https://pkg.pr.new/@tanstack/ai-elevenlabs@655

@tanstack/ai-event-client

npm i https://pkg.pr.new/@tanstack/ai-event-client@655

@tanstack/ai-fal

npm i https://pkg.pr.new/@tanstack/ai-fal@655

@tanstack/ai-gemini

npm i https://pkg.pr.new/@tanstack/ai-gemini@655

@tanstack/ai-grok

npm i https://pkg.pr.new/@tanstack/ai-grok@655

@tanstack/ai-groq

npm i https://pkg.pr.new/@tanstack/ai-groq@655

@tanstack/ai-isolate-cloudflare

npm i https://pkg.pr.new/@tanstack/ai-isolate-cloudflare@655

@tanstack/ai-isolate-node

npm i https://pkg.pr.new/@tanstack/ai-isolate-node@655

@tanstack/ai-isolate-quickjs

npm i https://pkg.pr.new/@tanstack/ai-isolate-quickjs@655

@tanstack/ai-ollama

npm i https://pkg.pr.new/@tanstack/ai-ollama@655

@tanstack/ai-openai

npm i https://pkg.pr.new/@tanstack/ai-openai@655

@tanstack/ai-openrouter

npm i https://pkg.pr.new/@tanstack/ai-openrouter@655

@tanstack/ai-preact

npm i https://pkg.pr.new/@tanstack/ai-preact@655

@tanstack/ai-react

npm i https://pkg.pr.new/@tanstack/ai-react@655

@tanstack/ai-react-ui

npm i https://pkg.pr.new/@tanstack/ai-react-ui@655

@tanstack/ai-solid

npm i https://pkg.pr.new/@tanstack/ai-solid@655

@tanstack/ai-solid-ui

npm i https://pkg.pr.new/@tanstack/ai-solid-ui@655

@tanstack/ai-svelte

npm i https://pkg.pr.new/@tanstack/ai-svelte@655

@tanstack/ai-utils

npm i https://pkg.pr.new/@tanstack/ai-utils@655

@tanstack/ai-vue

npm i https://pkg.pr.new/@tanstack/ai-vue@655

@tanstack/ai-vue-ui

npm i https://pkg.pr.new/@tanstack/ai-vue-ui@655

@tanstack/openai-base

npm i https://pkg.pr.new/@tanstack/openai-base@655

@tanstack/preact-ai-devtools

npm i https://pkg.pr.new/@tanstack/preact-ai-devtools@655

@tanstack/react-ai-devtools

npm i https://pkg.pr.new/@tanstack/react-ai-devtools@655

@tanstack/solid-ai-devtools

npm i https://pkg.pr.new/@tanstack/solid-ai-devtools@655

commit: 8106603