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

The Gemini image adapter hardcoded `usage: undefined`, so the `image:usage`
devtools event never fired for Gemini image generation even though the
`generateContent` response carries `usageMetadata`.

Parse `usageMetadata` (promptTokenCount / candidatesTokenCount /
totalTokenCount) into `ImageGenerationResult.usage` on the native path,
matching the convention used by the Gemini text adapter. The Imagen
(`generateImages`) path is left as-is because that SDK response type does
not expose `usageMetadata`.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tombeckenham

.changeset/gemini-image-usage.md

@@ -0,0 +1,8 @@
+---
+'@tanstack/ai-gemini': patch
+---
+
+Surface token usage from the Gemini image adapter's `generateContent` path
+(e.g. Nano Banana) by parsing `usageMetadata` from the response instead of
+omitting `usage`. The Imagen (`generateImages`) path is unchanged — that SDK
+response type does not expose `usageMetadata`. Fixes #330.

packages/ai-gemini/src/adapters/image.ts

@@ -214,6 +214,16 @@ export class GeminiImageAdapter<
       id: generateId(this.name),
       model,
       images,
+      // Surface token usage when the model reports it (e.g. Nano Banana via
+      // generateContent). Conditionally spread to satisfy
+      // exactOptionalPropertyTypes — only include usage when present. See #330.
+      ...(response.usageMetadata && {
+        usage: {
+          inputTokens: response.usageMetadata.promptTokenCount ?? 0,
+          outputTokens: response.usageMetadata.candidatesTokenCount ?? 0,
+          totalTokens: response.usageMetadata.totalTokenCount ?? 0,
+        },
+      }),
     }
   }
 

packages/ai-gemini/tests/image-adapter.test.ts

@@ -302,6 +302,52 @@ describe('Gemini Image Adapter', () => {
       expect(result.images[0]!.b64Json).toBe('gemini-base64-image')
     })
 
+    it('surfaces token usage from usageMetadata (#330)', async () => {
+      const mockResponse = {
+        candidates: [
+          {
+            content: {
+              parts: [
+                {
+                  inlineData: { mimeType: 'image/png', data: 'img' },
+                },
+              ],
+            },
+          },
+        ],
+        usageMetadata: {
+          promptTokenCount: 12,
+          candidatesTokenCount: 34,
+          totalTokenCount: 46,
+        },
+      }
+
+      const adapter = createGeminiImage(
+        'gemini-3.1-flash-image-preview',
+        'test-api-key',
+      )
+      ;(
+        adapter as unknown as {
+          client: { models: { generateContent: unknown } }
+        }
+      ).client = {
+        models: {
+          generateContent: vi.fn().mockResolvedValueOnce(mockResponse),
+        },
+      }
+
+      const result = await generateImage({
+        adapter,
+        prompt: 'A futuristic city',
+      })
+
+      expect(result.usage).toEqual({
+        inputTokens: 12,
+        outputTokens: 34,
+        totalTokens: 46,
+      })
+    })
+
     it('calls generateContent without imageConfig when no size provided', async () => {
       const mockResponse = {
         candidates: [