@tanstack/ai-gemini 0.12.1 → 0.14.0

package/dist/esm/adapters/tts.js.map

@@ -1 +1 @@
-{"version":3,"file":"tts.js","sources":["../../../src/adapters/tts.ts"],"sourcesContent":["import { BaseTTSAdapter } from '@tanstack/ai/adapters'\nimport {\n  createGeminiClient,\n  generateId,\n  getGeminiApiKeyFromEnv,\n} from '../utils'\nimport { GEMINI_TTS_VOICES } from '../model-meta'\nimport type { GEMINI_TTS_MODELS, GeminiTTSVoice } from '../model-meta'\nimport type { TTSOptions, TTSResult } from '@tanstack/ai'\nimport type { GoogleGenAI, SpeechConfig } from '@google/genai'\nimport type { GeminiClientConfig } from '../utils'\n\n/**\n * Configuration for a single speaker in a multi-speaker dialogue.\n * Supported by Gemini 3.1 Flash TTS Preview and the 2.5 TTS models.\n */\nexport interface GeminiSpeakerVoiceConfig {\n  /** A name used in the prompt to refer to this speaker */\n  speaker: string\n  /** Voice configuration for this speaker */\n  voiceConfig: {\n    prebuiltVoiceConfig: {\n      voiceName: GeminiTTSVoice\n    }\n  }\n}\n\n/**\n * Provider-specific options for Gemini TTS\n *\n * @experimental Gemini TTS is an experimental feature.\n * @see https://ai.google.dev/gemini-api/docs/speech-generation\n * @see https://ai.google.dev/gemini-api/docs/models/gemini-3.1-flash-tts-preview\n */\nexport interface GeminiTTSProviderOptions {\n  /**\n   * Voice configuration for single-speaker TTS.\n   * Choose from 30 available voices with different characteristics.\n   *\n   * Use `multiSpeakerVoiceConfig` instead for dialogues.\n   */\n  voiceConfig?: {\n    prebuiltVoiceConfig?: {\n      /**\n       * The voice name to use for speech synthesis.\n       * @see https://ai.google.dev/gemini-api/docs/speech-generation#voices\n       */\n      voiceName?: GeminiTTSVoice\n    }\n  }\n\n  /**\n   * Multi-speaker voice configuration (up to 2 speakers).\n   * Supported by Gemini 3.1 Flash TTS Preview and the 2.5 TTS models.\n   *\n   * Each speaker's lines in the prompt are prefixed with the name defined\n   * here, e.g.:\n   *\n   * ```text\n   * Joe: Hey, how's it going?\n   * Jane: Not bad, you?\n   * ```\n   */\n  multiSpeakerVoiceConfig?: {\n    speakerVoiceConfigs: Array<GeminiSpeakerVoiceConfig>\n  }\n\n  /**\n   * System instruction for controlling speech style.\n   * Use natural language to describe the desired speaking style,\n   * pace, tone, accent, or other characteristics.\n   *\n   * With Gemini 3.1 Flash TTS, you can also use inline audio tags like\n   * `[whispering]`, `[laughs]`, `[excited]` directly in the input text\n   * to control delivery.\n   *\n   * @example \"Speak slowly and calmly, as if telling a bedtime story\"\n   * @example \"Use an upbeat, enthusiastic tone with moderate pace\"\n   * @example \"Speak with a British accent\"\n   */\n  systemInstruction?: string\n\n  /**\n   * Language code hint for the speech synthesis.\n   * Gemini 3.1 Flash TTS supports 70+ languages with auto-detection;\n   * the 2.5 TTS models support 24 languages.\n   *\n   * @example \"en-US\" for American English\n   * @example \"es-ES\" for Spanish (Spain)\n   * @example \"ja-JP\" for Japanese\n   */\n  languageCode?: string\n}\n\n/**\n * Configuration for Gemini TTS adapter\n *\n * @experimental Gemini TTS is an experimental feature.\n */\nexport interface GeminiTTSConfig extends GeminiClientConfig {}\n\n/** Model type for Gemini TTS */\nexport type GeminiTTSModel = (typeof GEMINI_TTS_MODELS)[number]\n\n/**\n * Gemini Text-to-Speech Adapter\n *\n * Tree-shakeable adapter for Gemini TTS functionality.\n *\n * **IMPORTANT**: Gemini TTS uses the Live API (WebSocket-based) which requires\n * different handling than traditional REST APIs. This adapter provides a\n * simplified interface but may have limitations.\n *\n * @experimental Gemini TTS is an experimental feature and may change.\n *\n * Models:\n * - gemini-2.5-flash-preview-tts\n */\nexport class GeminiTTSAdapter<\n  TModel extends GeminiTTSModel,\n> extends BaseTTSAdapter<TModel, GeminiTTSProviderOptions> {\n  readonly name = 'gemini' as const\n\n  private readonly client: GoogleGenAI\n\n  constructor(config: GeminiTTSConfig, model: TModel) {\n    super(model, config)\n    this.client = createGeminiClient(config)\n  }\n\n  /**\n   * Generate speech from text using Gemini's TTS model.\n   *\n   * @experimental This implementation is experimental and may change.\n   * @see https://ai.google.dev/gemini-api/docs/speech-generation\n   */\n  async generateSpeech(\n    options: TTSOptions<GeminiTTSProviderOptions>,\n  ): Promise<TTSResult> {\n    const { model, text, modelOptions, voice, logger } = options\n\n    logger.request(`activity=generateSpeech provider=gemini model=${model}`, {\n      provider: 'gemini',\n      model,\n    })\n\n    const speechConfig: SpeechConfig = {}\n\n    if (modelOptions?.multiSpeakerVoiceConfig) {\n      // Validate multi-speaker config: 1 or 2 speakers allowed.\n      const speakerConfigs =\n        modelOptions.multiSpeakerVoiceConfig.speakerVoiceConfigs\n      if (\n        !Array.isArray(speakerConfigs) ||\n        speakerConfigs.length < 1 ||\n        speakerConfigs.length > 2\n      ) {\n        throw new Error(\n          `Gemini TTS multiSpeakerVoiceConfig.speakerVoiceConfigs must contain 1 or 2 speakers; received ${Array.isArray(speakerConfigs) ? speakerConfigs.length : 'non-array'}.`,\n        )\n      }\n      speechConfig.multiSpeakerVoiceConfig =\n        modelOptions.multiSpeakerVoiceConfig\n    } else {\n      // Honor the standard TTSOptions.voice (used by every other TTS adapter)\n      // as a fallback for the prebuilt voice name. If an explicit\n      // modelOptions.voiceConfig is supplied its values win — but we still\n      // fall back to `voice` / 'Kore' if the supplied voiceConfig is missing\n      // prebuiltVoiceConfig.voiceName.\n      if (\n        voice !== undefined &&\n        !(GEMINI_TTS_VOICES as ReadonlyArray<string>).includes(voice)\n      ) {\n        throw new Error(\n          `Invalid Gemini TTS voice \"${voice}\". Valid voices are: ${GEMINI_TTS_VOICES.join(', ')}.`,\n        )\n      }\n      const defaultVoiceName = (voice as GeminiTTSVoice | undefined) ?? 'Kore'\n      const supplied = modelOptions?.voiceConfig\n      const resolvedVoiceName =\n        supplied?.prebuiltVoiceConfig?.voiceName ?? defaultVoiceName\n      speechConfig.voiceConfig = {\n        prebuiltVoiceConfig: { voiceName: resolvedVoiceName },\n      }\n    }\n\n    if (modelOptions?.languageCode) {\n      speechConfig.languageCode = modelOptions.languageCode\n    }\n\n    try {\n      const response = await this.client.models.generateContent({\n        model,\n        contents: [\n          {\n            role: 'user',\n            parts: [{ text }],\n          },\n        ],\n        config: {\n          responseModalities: ['AUDIO'],\n          speechConfig,\n          // systemInstruction belongs inside `config` per the @google/genai\n          // contract — matches sibling Gemini adapters (summarize, text).\n          ...(modelOptions?.systemInstruction && {\n            systemInstruction: modelOptions.systemInstruction,\n          }),\n        },\n      })\n\n      // Extract audio data from response\n      const candidate = response.candidates?.[0]\n      const parts = candidate?.content?.parts\n\n      if (!parts || parts.length === 0) {\n        throw new Error('No audio output received from Gemini TTS')\n      }\n\n      // Look for inline data (audio)\n      const audioPart = parts.find((part: any) =>\n        part.inlineData?.mimeType?.startsWith('audio/'),\n      )\n\n      if (!audioPart || !audioPart.inlineData || !audioPart.inlineData.data) {\n        throw new Error('No audio data in Gemini TTS response')\n      }\n\n      const audioBase64 = audioPart.inlineData.data\n      // mime is guaranteed by the `startsWith('audio/')` find predicate above.\n      const mimeType = audioPart.inlineData.mimeType as string\n\n      // Gemini TTS models return raw 16-bit LE PCM with a mime type like\n      // `audio/L16;codec=pcm;rate=24000`. That isn't playable in an <audio>\n      // element and the bare string isn't a usable file extension, so we\n      // prepend a RIFF/WAV header here and normalize the result to audio/wav.\n      const pcm = parsePcmMimeType(mimeType)\n      if (pcm) {\n        const wavBase64 = wrapPcmBase64AsWav(\n          audioBase64,\n          pcm.sampleRate,\n          pcm.channels,\n          pcm.bitsPerSample,\n        )\n        return {\n          id: generateId(this.name),\n          model,\n          audio: wavBase64,\n          format: 'wav',\n          contentType: 'audio/wav',\n        }\n      }\n\n      // Strip any mime parameters (e.g. `audio/ogg;codec=opus`) before pulling\n      // the subtype out as the file format. `String.split` always returns at\n      // least one element, so [0] is defined.\n      const format = (mimeType.split(';')[0] ?? '').split('/')[1] || 'wav'\n\n      return {\n        id: generateId(this.name),\n        model,\n        audio: audioBase64,\n        format,\n        contentType: mimeType,\n      }\n    } catch (error) {\n      logger.errors('gemini.generateSpeech fatal', {\n        error,\n        source: 'gemini.generateSpeech',\n      })\n      throw error\n    }\n  }\n}\n\nfunction parsePcmMimeType(\n  mimeType: string,\n): { sampleRate: number; channels: number; bitsPerSample: number } | undefined {\n  const normalized = mimeType.toLowerCase()\n  const subtype = (normalized.split(';')[0] ?? '').split('/')[1] ?? ''\n  // Exclude containerized wav (e.g. `audio/wav;codec=pcm`) — those already\n  // carry a RIFF header and must not be re-wrapped.\n  if (subtype.includes('wav')) return undefined\n\n  // Accept the variants Gemini and other providers actually emit:\n  //   - audio/L16;codec=pcm;rate=24000 (IANA PCM with bit depth in the type)\n  //   - audio/L24 and friends\n  //   - audio/pcm and audio/x-pcm\n  //   - anything else that explicitly tags codec=pcm and isn't wav-containered\n  const bitDepthMatch = /^audio\\/l(\\d+)/.exec(normalized)\n  const isPcm =\n    bitDepthMatch !== null ||\n    normalized.startsWith('audio/pcm') ||\n    normalized.startsWith('audio/x-pcm') ||\n    normalized.includes('codec=pcm')\n  if (!isPcm) return undefined\n\n  const rateMatch = /rate=(\\d+)/.exec(normalized)\n  const channelsMatch = /channels=(\\d+)/.exec(normalized)\n  // Default to 16-bit when the mime type doesn't specify — matches Gemini's\n  // audio/L16;codec=pcm;rate=24000 response.\n  const bitsPerSample = bitDepthMatch ? Number(bitDepthMatch[1]) : 16\n  return {\n    sampleRate: rateMatch ? Number(rateMatch[1]) : 24000,\n    channels: channelsMatch ? Number(channelsMatch[1]) : 1,\n    bitsPerSample,\n  }\n}\n\nfunction wrapPcmBase64AsWav(\n  pcmBase64: string,\n  sampleRate: number,\n  channels = 1,\n  bitsPerSample = 16,\n): string {\n  // The WAV writer below emits a 16-bit PCM fmt chunk. If the source claims a\n  // different bit depth we'd be lying about the payload, so bail out loudly\n  // rather than producing a corrupt file.\n  if (bitsPerSample !== 16) {\n    throw new Error(\n      `Unsupported PCM bit depth ${bitsPerSample}: only 16-bit PCM can be wrapped as WAV.`,\n    )\n  }\n\n  const pcmBytes =\n    typeof Buffer !== 'undefined'\n      ? new Uint8Array(Buffer.from(pcmBase64, 'base64'))\n      : decodeBase64(pcmBase64)\n\n  const byteRate = (sampleRate * channels * bitsPerSample) / 8\n  const blockAlign = (channels * bitsPerSample) / 8\n  const dataSize = pcmBytes.byteLength\n  const buffer = new ArrayBuffer(44 + dataSize)\n  const view = new DataView(buffer)\n\n  writeAscii(view, 0, 'RIFF')\n  view.setUint32(4, 36 + dataSize, true)\n  writeAscii(view, 8, 'WAVE')\n  writeAscii(view, 12, 'fmt ')\n  view.setUint32(16, 16, true)\n  view.setUint16(20, 1, true)\n  view.setUint16(22, channels, true)\n  view.setUint32(24, sampleRate, true)\n  view.setUint32(28, byteRate, true)\n  view.setUint16(32, blockAlign, true)\n  view.setUint16(34, bitsPerSample, true)\n  writeAscii(view, 36, 'data')\n  view.setUint32(40, dataSize, true)\n  new Uint8Array(buffer, 44).set(pcmBytes)\n\n  if (typeof Buffer !== 'undefined') {\n    return Buffer.from(buffer).toString('base64')\n  }\n  let binary = ''\n  const bytes = new Uint8Array(buffer)\n  for (const byte of bytes) {\n    binary += String.fromCharCode(byte)\n  }\n  return btoa(binary)\n}\n\nfunction decodeBase64(b64: string): Uint8Array {\n  const binary = atob(b64)\n  const out = new Uint8Array(binary.length)\n  for (let i = 0; i < binary.length; i += 1) out[i] = binary.charCodeAt(i)\n  return out\n}\n\nfunction writeAscii(view: DataView, offset: number, text: string): void {\n  for (let i = 0; i < text.length; i += 1) {\n    view.setUint8(offset + i, text.charCodeAt(i))\n  }\n}\n\n/**\n * Creates a Gemini TTS adapter with explicit API key.\n * Type resolution happens here at the call site.\n *\n * @experimental Gemini TTS is an experimental feature and may change.\n *\n * @param model - The model name (e.g., 'gemini-2.5-flash-preview-tts')\n * @param apiKey - Your Google API key\n * @param config - Optional additional configuration\n * @returns Configured Gemini TTS adapter instance with resolved types\n *\n * @example\n * ```typescript\n * const adapter = createGeminiSpeech('gemini-2.5-flash-preview-tts', \"your-api-key\");\n *\n * const result = await generateSpeech({\n *   adapter,\n *   text: 'Hello, world!'\n * });\n * ```\n */\nexport function createGeminiSpeech<TModel extends GeminiTTSModel>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<GeminiTTSConfig, 'apiKey'>,\n): GeminiTTSAdapter<TModel> {\n  // Put apiKey LAST so caller-supplied config can't silently override the\n  // explicit argument.\n  return new GeminiTTSAdapter({ ...config, apiKey }, model)\n}\n\n/**\n * Creates a Gemini speech adapter with automatic API key detection from environment variables.\n * Type resolution happens here at the call site.\n *\n * @experimental Gemini TTS is an experimental feature and may change.\n *\n * Looks for `GOOGLE_API_KEY` or `GEMINI_API_KEY` in:\n * - `process.env` (Node.js)\n * - `window.env` (Browser with injected env)\n *\n * @param model - The model name (e.g., 'gemini-2.5-flash-preview-tts')\n * @param config - Optional configuration (excluding apiKey which is auto-detected)\n * @returns Configured Gemini speech adapter instance with resolved types\n * @throws Error if GOOGLE_API_KEY or GEMINI_API_KEY is not found in environment\n *\n * @example\n * ```typescript\n * // Automatically uses GOOGLE_API_KEY from environment\n * const adapter = geminiSpeech('gemini-2.5-flash-preview-tts');\n *\n * const result = await generateSpeech({\n *   adapter,\n *   text: 'Welcome to TanStack AI!'\n * });\n * ```\n */\nexport function geminiSpeech<TModel extends GeminiTTSModel>(\n  model: TModel,\n  config?: Omit<GeminiTTSConfig, 'apiKey'>,\n): GeminiTTSAdapter<TModel> {\n  const apiKey = getGeminiApiKeyFromEnv()\n  return createGeminiSpeech(model, apiKey, config)\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"tts.js","sources":["../../../src/adapters/tts.ts"],"sourcesContent":["import { BaseTTSAdapter } from '@tanstack/ai/adapters'\nimport {\n  createGeminiClient,\n  generateId,\n  getGeminiApiKeyFromEnv,\n} from '../utils'\nimport { GEMINI_TTS_VOICES } from '../model-meta'\nimport { buildGeminiUsage } from '../usage'\nimport type { GEMINI_TTS_MODELS, GeminiTTSVoice } from '../model-meta'\nimport type { TTSOptions, TTSResult } from '@tanstack/ai'\nimport type { GoogleGenAI, SpeechConfig } from '@google/genai'\nimport type { GeminiClientConfig } from '../utils'\n\n/**\n * Configuration for a single speaker in a multi-speaker dialogue.\n * Supported by Gemini 3.1 Flash TTS Preview and the 2.5 TTS models.\n */\nexport interface GeminiSpeakerVoiceConfig {\n  /** A name used in the prompt to refer to this speaker */\n  speaker: string\n  /** Voice configuration for this speaker */\n  voiceConfig: {\n    prebuiltVoiceConfig: {\n      voiceName: GeminiTTSVoice\n    }\n  }\n}\n\n/**\n * Provider-specific options for Gemini TTS\n *\n * @experimental Gemini TTS is an experimental feature.\n * @see https://ai.google.dev/gemini-api/docs/speech-generation\n * @see https://ai.google.dev/gemini-api/docs/models/gemini-3.1-flash-tts-preview\n */\nexport interface GeminiTTSProviderOptions {\n  /**\n   * Voice configuration for single-speaker TTS.\n   * Choose from 30 available voices with different characteristics.\n   *\n   * Use `multiSpeakerVoiceConfig` instead for dialogues.\n   */\n  voiceConfig?: {\n    prebuiltVoiceConfig?: {\n      /**\n       * The voice name to use for speech synthesis.\n       * @see https://ai.google.dev/gemini-api/docs/speech-generation#voices\n       */\n      voiceName?: GeminiTTSVoice\n    }\n  }\n\n  /**\n   * Multi-speaker voice configuration (up to 2 speakers).\n   * Supported by Gemini 3.1 Flash TTS Preview and the 2.5 TTS models.\n   *\n   * Each speaker's lines in the prompt are prefixed with the name defined\n   * here, e.g.:\n   *\n   * ```text\n   * Joe: Hey, how's it going?\n   * Jane: Not bad, you?\n   * ```\n   */\n  multiSpeakerVoiceConfig?: {\n    speakerVoiceConfigs: Array<GeminiSpeakerVoiceConfig>\n  }\n\n  /**\n   * System instruction for controlling speech style.\n   * Use natural language to describe the desired speaking style,\n   * pace, tone, accent, or other characteristics.\n   *\n   * With Gemini 3.1 Flash TTS, you can also use inline audio tags like\n   * `[whispering]`, `[laughs]`, `[excited]` directly in the input text\n   * to control delivery.\n   *\n   * @example \"Speak slowly and calmly, as if telling a bedtime story\"\n   * @example \"Use an upbeat, enthusiastic tone with moderate pace\"\n   * @example \"Speak with a British accent\"\n   */\n  systemInstruction?: string\n\n  /**\n   * Language code hint for the speech synthesis.\n   * Gemini 3.1 Flash TTS supports 70+ languages with auto-detection;\n   * the 2.5 TTS models support 24 languages.\n   *\n   * @example \"en-US\" for American English\n   * @example \"es-ES\" for Spanish (Spain)\n   * @example \"ja-JP\" for Japanese\n   */\n  languageCode?: string\n}\n\n/**\n * Configuration for Gemini TTS adapter\n *\n * @experimental Gemini TTS is an experimental feature.\n */\nexport interface GeminiTTSConfig extends GeminiClientConfig {}\n\n/** Model type for Gemini TTS */\nexport type GeminiTTSModel = (typeof GEMINI_TTS_MODELS)[number]\n\n/**\n * Gemini Text-to-Speech Adapter\n *\n * Tree-shakeable adapter for Gemini TTS functionality.\n *\n * **IMPORTANT**: Gemini TTS uses the Live API (WebSocket-based) which requires\n * different handling than traditional REST APIs. This adapter provides a\n * simplified interface but may have limitations.\n *\n * @experimental Gemini TTS is an experimental feature and may change.\n *\n * Models:\n * - gemini-2.5-flash-preview-tts\n */\nexport class GeminiTTSAdapter<\n  TModel extends GeminiTTSModel,\n> extends BaseTTSAdapter<TModel, GeminiTTSProviderOptions> {\n  readonly name = 'gemini' as const\n\n  private readonly client: GoogleGenAI\n\n  constructor(config: GeminiTTSConfig, model: TModel) {\n    super(model, config)\n    this.client = createGeminiClient(config)\n  }\n\n  /**\n   * Generate speech from text using Gemini's TTS model.\n   *\n   * @experimental This implementation is experimental and may change.\n   * @see https://ai.google.dev/gemini-api/docs/speech-generation\n   */\n  async generateSpeech(\n    options: TTSOptions<GeminiTTSProviderOptions>,\n  ): Promise<TTSResult> {\n    const { model, text, modelOptions, voice, logger } = options\n\n    logger.request(`activity=generateSpeech provider=gemini model=${model}`, {\n      provider: 'gemini',\n      model,\n    })\n\n    const speechConfig: SpeechConfig = {}\n\n    if (modelOptions?.multiSpeakerVoiceConfig) {\n      // Validate multi-speaker config: 1 or 2 speakers allowed.\n      const speakerConfigs =\n        modelOptions.multiSpeakerVoiceConfig.speakerVoiceConfigs\n      if (\n        !Array.isArray(speakerConfigs) ||\n        speakerConfigs.length < 1 ||\n        speakerConfigs.length > 2\n      ) {\n        throw new Error(\n          `Gemini TTS multiSpeakerVoiceConfig.speakerVoiceConfigs must contain 1 or 2 speakers; received ${Array.isArray(speakerConfigs) ? speakerConfigs.length : 'non-array'}.`,\n        )\n      }\n      speechConfig.multiSpeakerVoiceConfig =\n        modelOptions.multiSpeakerVoiceConfig\n    } else {\n      // Honor the standard TTSOptions.voice (used by every other TTS adapter)\n      // as a fallback for the prebuilt voice name. If an explicit\n      // modelOptions.voiceConfig is supplied its values win — but we still\n      // fall back to `voice` / 'Kore' if the supplied voiceConfig is missing\n      // prebuiltVoiceConfig.voiceName.\n      if (\n        voice !== undefined &&\n        !(GEMINI_TTS_VOICES as ReadonlyArray<string>).includes(voice)\n      ) {\n        throw new Error(\n          `Invalid Gemini TTS voice \"${voice}\". Valid voices are: ${GEMINI_TTS_VOICES.join(', ')}.`,\n        )\n      }\n      const defaultVoiceName = (voice as GeminiTTSVoice | undefined) ?? 'Kore'\n      const supplied = modelOptions?.voiceConfig\n      const resolvedVoiceName =\n        supplied?.prebuiltVoiceConfig?.voiceName ?? defaultVoiceName\n      speechConfig.voiceConfig = {\n        prebuiltVoiceConfig: { voiceName: resolvedVoiceName },\n      }\n    }\n\n    if (modelOptions?.languageCode) {\n      speechConfig.languageCode = modelOptions.languageCode\n    }\n\n    try {\n      const response = await this.client.models.generateContent({\n        model,\n        contents: [\n          {\n            role: 'user',\n            parts: [{ text }],\n          },\n        ],\n        config: {\n          responseModalities: ['AUDIO'],\n          speechConfig,\n          // systemInstruction belongs inside `config` per the @google/genai\n          // contract — matches sibling Gemini adapters (summarize, text).\n          ...(modelOptions?.systemInstruction && {\n            systemInstruction: modelOptions.systemInstruction,\n          }),\n        },\n      })\n\n      // Extract audio data from response\n      const candidate = response.candidates?.[0]\n      const parts = candidate?.content?.parts\n\n      if (!parts || parts.length === 0) {\n        throw new Error('No audio output received from Gemini TTS')\n      }\n\n      // Look for inline data (audio)\n      const audioPart = parts.find((part: any) =>\n        part.inlineData?.mimeType?.startsWith('audio/'),\n      )\n\n      if (!audioPart || !audioPart.inlineData || !audioPart.inlineData.data) {\n        throw new Error('No audio data in Gemini TTS response')\n      }\n\n      const audioBase64 = audioPart.inlineData.data\n      // mime is guaranteed by the `startsWith('audio/')` find predicate above.\n      const mimeType = audioPart.inlineData.mimeType as string\n\n      // Surface token usage (with per-modality breakdown) when Gemini reports\n      // it. Spread conditionally for exactOptionalPropertyTypes — shared by both\n      // the PCM→WAV and pass-through return paths below.\n      const usageField = response.usageMetadata\n        ? { usage: buildGeminiUsage(response.usageMetadata) }\n        : {}\n\n      // Gemini TTS models return raw 16-bit LE PCM with a mime type like\n      // `audio/L16;codec=pcm;rate=24000`. That isn't playable in an <audio>\n      // element and the bare string isn't a usable file extension, so we\n      // prepend a RIFF/WAV header here and normalize the result to audio/wav.\n      const pcm = parsePcmMimeType(mimeType)\n      if (pcm) {\n        const wavBase64 = wrapPcmBase64AsWav(\n          audioBase64,\n          pcm.sampleRate,\n          pcm.channels,\n          pcm.bitsPerSample,\n        )\n        return {\n          id: generateId(this.name),\n          model,\n          audio: wavBase64,\n          format: 'wav',\n          contentType: 'audio/wav',\n          ...usageField,\n        }\n      }\n\n      // Strip any mime parameters (e.g. `audio/ogg;codec=opus`) before pulling\n      // the subtype out as the file format. `String.split` always returns at\n      // least one element, so [0] is defined.\n      const format = (mimeType.split(';')[0] ?? '').split('/')[1] || 'wav'\n\n      return {\n        id: generateId(this.name),\n        model,\n        audio: audioBase64,\n        format,\n        contentType: mimeType,\n        ...usageField,\n      }\n    } catch (error) {\n      logger.errors('gemini.generateSpeech fatal', {\n        error,\n        source: 'gemini.generateSpeech',\n      })\n      throw error\n    }\n  }\n}\n\nfunction parsePcmMimeType(\n  mimeType: string,\n): { sampleRate: number; channels: number; bitsPerSample: number } | undefined {\n  const normalized = mimeType.toLowerCase()\n  const subtype = (normalized.split(';')[0] ?? '').split('/')[1] ?? ''\n  // Exclude containerized wav (e.g. `audio/wav;codec=pcm`) — those already\n  // carry a RIFF header and must not be re-wrapped.\n  if (subtype.includes('wav')) return undefined\n\n  // Accept the variants Gemini and other providers actually emit:\n  //   - audio/L16;codec=pcm;rate=24000 (IANA PCM with bit depth in the type)\n  //   - audio/L24 and friends\n  //   - audio/pcm and audio/x-pcm\n  //   - anything else that explicitly tags codec=pcm and isn't wav-containered\n  const bitDepthMatch = /^audio\\/l(\\d+)/.exec(normalized)\n  const isPcm =\n    bitDepthMatch !== null ||\n    normalized.startsWith('audio/pcm') ||\n    normalized.startsWith('audio/x-pcm') ||\n    normalized.includes('codec=pcm')\n  if (!isPcm) return undefined\n\n  const rateMatch = /rate=(\\d+)/.exec(normalized)\n  const channelsMatch = /channels=(\\d+)/.exec(normalized)\n  // Default to 16-bit when the mime type doesn't specify — matches Gemini's\n  // audio/L16;codec=pcm;rate=24000 response.\n  const bitsPerSample = bitDepthMatch ? Number(bitDepthMatch[1]) : 16\n  return {\n    sampleRate: rateMatch ? Number(rateMatch[1]) : 24000,\n    channels: channelsMatch ? Number(channelsMatch[1]) : 1,\n    bitsPerSample,\n  }\n}\n\nfunction wrapPcmBase64AsWav(\n  pcmBase64: string,\n  sampleRate: number,\n  channels = 1,\n  bitsPerSample = 16,\n): string {\n  // The WAV writer below emits a 16-bit PCM fmt chunk. If the source claims a\n  // different bit depth we'd be lying about the payload, so bail out loudly\n  // rather than producing a corrupt file.\n  if (bitsPerSample !== 16) {\n    throw new Error(\n      `Unsupported PCM bit depth ${bitsPerSample}: only 16-bit PCM can be wrapped as WAV.`,\n    )\n  }\n\n  const pcmBytes =\n    typeof Buffer !== 'undefined'\n      ? new Uint8Array(Buffer.from(pcmBase64, 'base64'))\n      : decodeBase64(pcmBase64)\n\n  const byteRate = (sampleRate * channels * bitsPerSample) / 8\n  const blockAlign = (channels * bitsPerSample) / 8\n  const dataSize = pcmBytes.byteLength\n  const buffer = new ArrayBuffer(44 + dataSize)\n  const view = new DataView(buffer)\n\n  writeAscii(view, 0, 'RIFF')\n  view.setUint32(4, 36 + dataSize, true)\n  writeAscii(view, 8, 'WAVE')\n  writeAscii(view, 12, 'fmt ')\n  view.setUint32(16, 16, true)\n  view.setUint16(20, 1, true)\n  view.setUint16(22, channels, true)\n  view.setUint32(24, sampleRate, true)\n  view.setUint32(28, byteRate, true)\n  view.setUint16(32, blockAlign, true)\n  view.setUint16(34, bitsPerSample, true)\n  writeAscii(view, 36, 'data')\n  view.setUint32(40, dataSize, true)\n  new Uint8Array(buffer, 44).set(pcmBytes)\n\n  if (typeof Buffer !== 'undefined') {\n    return Buffer.from(buffer).toString('base64')\n  }\n  let binary = ''\n  const bytes = new Uint8Array(buffer)\n  for (const byte of bytes) {\n    binary += String.fromCharCode(byte)\n  }\n  return btoa(binary)\n}\n\nfunction decodeBase64(b64: string): Uint8Array {\n  const binary = atob(b64)\n  const out = new Uint8Array(binary.length)\n  for (let i = 0; i < binary.length; i += 1) out[i] = binary.charCodeAt(i)\n  return out\n}\n\nfunction writeAscii(view: DataView, offset: number, text: string): void {\n  for (let i = 0; i < text.length; i += 1) {\n    view.setUint8(offset + i, text.charCodeAt(i))\n  }\n}\n\n/**\n * Creates a Gemini TTS adapter with explicit API key.\n * Type resolution happens here at the call site.\n *\n * @experimental Gemini TTS is an experimental feature and may change.\n *\n * @param model - The model name (e.g., 'gemini-2.5-flash-preview-tts')\n * @param apiKey - Your Google API key\n * @param config - Optional additional configuration\n * @returns Configured Gemini TTS adapter instance with resolved types\n *\n * @example\n * ```typescript\n * const adapter = createGeminiSpeech('gemini-2.5-flash-preview-tts', \"your-api-key\");\n *\n * const result = await generateSpeech({\n *   adapter,\n *   text: 'Hello, world!'\n * });\n * ```\n */\nexport function createGeminiSpeech<TModel extends GeminiTTSModel>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<GeminiTTSConfig, 'apiKey'>,\n): GeminiTTSAdapter<TModel> {\n  // Put apiKey LAST so caller-supplied config can't silently override the\n  // explicit argument.\n  return new GeminiTTSAdapter({ ...config, apiKey }, model)\n}\n\n/**\n * Creates a Gemini speech adapter with automatic API key detection from environment variables.\n * Type resolution happens here at the call site.\n *\n * @experimental Gemini TTS is an experimental feature and may change.\n *\n * Looks for `GOOGLE_API_KEY` or `GEMINI_API_KEY` in:\n * - `process.env` (Node.js)\n * - `window.env` (Browser with injected env)\n *\n * @param model - The model name (e.g., 'gemini-2.5-flash-preview-tts')\n * @param config - Optional configuration (excluding apiKey which is auto-detected)\n * @returns Configured Gemini speech adapter instance with resolved types\n * @throws Error if GOOGLE_API_KEY or GEMINI_API_KEY is not found in environment\n *\n * @example\n * ```typescript\n * // Automatically uses GOOGLE_API_KEY from environment\n * const adapter = geminiSpeech('gemini-2.5-flash-preview-tts');\n *\n * const result = await generateSpeech({\n *   adapter,\n *   text: 'Welcome to TanStack AI!'\n * });\n * ```\n */\nexport function geminiSpeech<TModel extends GeminiTTSModel>(\n  model: TModel,\n  config?: Omit<GeminiTTSConfig, 'apiKey'>,\n): GeminiTTSAdapter<TModel> {\n  const apiKey = getGeminiApiKeyFromEnv()\n  return createGeminiSpeech(model, apiKey, config)\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/index.d.ts

@@ -23,3 +23,4 @@ export type { GeminiChatModelProviderOptionsByName, GeminiChatModelToolCapabilit
 export type { GeminiStructuredOutputOptions, GeminiThinkingOptions, } from './text/text-provider-options.js';
 export type { GoogleGeminiTool } from './tools/index.js';
 export type { GeminiTextMetadata, GeminiImageMetadata, GeminiAudioMetadata, GeminiVideoMetadata, GeminiDocumentMetadata, GeminiMessageMetadataByModality, } from './message-types.js';
+export type { GeminiProviderUsageDetails } from './usage.js';

package/dist/esm/usage.d.ts

@@ -0,0 +1,67 @@
+import { TokenUsage } from '@tanstack/ai';
+import { GenerateContentResponseUsageMetadata, ModalityTokenCount } from '@google/genai';
+/**
+ * Flattened modality token counts for normalized usage reporting.
+ * Maps Gemini's ModalityTokenCount array to individual fields.
+ */
+export interface FlattenedModalityTokens {
+    /** Text tokens */
+    textTokens?: number;
+    /** Image tokens */
+    imageTokens?: number;
+    /** Audio tokens */
+    audioTokens?: number;
+    /** Video tokens */
+    videoTokens?: number;
+    /** Document tokens (e.g. PDF inputs) */
+    documentTokens?: number;
+}
+/**
+ * Flattens Gemini's ModalityTokenCount array into individual token fields.
+ * Extracts TEXT, IMAGE, AUDIO, VIDEO, DOCUMENT modality counts into a
+ * normalized structure.
+ */
+export declare function flattenModalityTokenCounts(modalities?: Array<ModalityTokenCount>): FlattenedModalityTokens;
+/**
+ * Checks if a FlattenedModalityTokens object has any values set.
+ */
+export declare function hasModalityTokens(tokens: FlattenedModalityTokens): boolean;
+/**
+ * Gemini-specific provider usage details.
+ * These fields are unique to Gemini and placed in providerUsageDetails.
+ */
+export type GeminiProviderUsageDetails = {
+    /**
+     * The traffic type for this request.
+     * Can indicate whether request was handled by different service tiers.
+     */
+    trafficType?: string;
+    /**
+     * Number of tokens in the results from tool executions,
+     * which are provided back to the model as input.
+     */
+    toolUsePromptTokenCount?: number;
+    /**
+     * Detailed breakdown by modality of the token counts from
+     * the results of tool executions.
+     */
+    toolUsePromptTokensDetails?: Array<{
+        modality: string;
+        tokenCount: number;
+    }>;
+    /**
+     * Detailed breakdown of cache tokens by modality.
+     * More granular than the normalized cachedTokens field.
+     */
+    cacheTokensDetails?: Array<{
+        modality: string;
+        tokenCount: number;
+    }>;
+};
+/**
+ * Build normalized TokenUsage from Gemini's usageMetadata.
+ * Handles modality breakdowns and thinking tokens. Returns `undefined` when the
+ * provider reported no usage metadata, so callers omit the field rather than
+ * fabricating zeroed totals.
+ */
+export declare function buildGeminiUsage(usageMetadata: GenerateContentResponseUsageMetadata | undefined | null): TokenUsage<GeminiProviderUsageDetails> | undefined;

package/dist/esm/usage.js

@@ -0,0 +1,94 @@
+import { buildBaseUsage } from "@tanstack/ai";
+function flattenModalityTokenCounts(modalities) {
+  if (!modalities || modalities.length === 0) {
+    return {};
+  }
+  const result = {};
+  for (const item of modalities) {
+    if (!item.modality || item.tokenCount === void 0) {
+      continue;
+    }
+    const modality = item.modality.toUpperCase();
+    const count = item.tokenCount;
+    switch (modality) {
+      case "TEXT":
+        result.textTokens = (result.textTokens ?? 0) + count;
+        break;
+      case "IMAGE":
+        result.imageTokens = (result.imageTokens ?? 0) + count;
+        break;
+      case "AUDIO":
+        result.audioTokens = (result.audioTokens ?? 0) + count;
+        break;
+      case "VIDEO":
+        result.videoTokens = (result.videoTokens ?? 0) + count;
+        break;
+      case "DOCUMENT":
+        result.documentTokens = (result.documentTokens ?? 0) + count;
+        break;
+    }
+  }
+  return result;
+}
+function hasModalityTokens(tokens) {
+  return tokens.textTokens !== void 0 || tokens.imageTokens !== void 0 || tokens.audioTokens !== void 0 || tokens.videoTokens !== void 0 || tokens.documentTokens !== void 0;
+}
+function buildGeminiUsage(usageMetadata) {
+  if (!usageMetadata) return void 0;
+  const promptTokens = usageMetadata.promptTokenCount ?? 0;
+  const completionTokens = usageMetadata.candidatesTokenCount ?? 0;
+  const result = buildBaseUsage({
+    promptTokens,
+    completionTokens,
+    totalTokens: usageMetadata.totalTokenCount ?? promptTokens + completionTokens
+  });
+  const promptModalities = flattenModalityTokenCounts(
+    usageMetadata.promptTokensDetails
+  );
+  const cachedTokens = usageMetadata.cachedContentTokenCount;
+  const promptTokensDetails = {
+    ...hasModalityTokens(promptModalities) ? promptModalities : {},
+    ...cachedTokens !== void 0 && cachedTokens > 0 ? { cachedTokens } : {}
+  };
+  const completionModalities = flattenModalityTokenCounts(
+    usageMetadata.candidatesTokensDetails
+  );
+  const thoughtsTokens = usageMetadata.thoughtsTokenCount;
+  const completionTokensDetails = {
+    ...hasModalityTokens(completionModalities) ? completionModalities : {},
+    // Map thoughtsTokenCount to reasoningTokens for consistency with OpenAI
+    ...thoughtsTokens !== void 0 && thoughtsTokens > 0 ? { reasoningTokens: thoughtsTokens } : {}
+  };
+  const providerDetails = {
+    ...usageMetadata.trafficType ? { trafficType: usageMetadata.trafficType } : {},
+    ...usageMetadata.toolUsePromptTokenCount !== void 0 && usageMetadata.toolUsePromptTokenCount > 0 ? { toolUsePromptTokenCount: usageMetadata.toolUsePromptTokenCount } : {},
+    ...usageMetadata.toolUsePromptTokensDetails && usageMetadata.toolUsePromptTokensDetails.length > 0 ? {
+      toolUsePromptTokensDetails: usageMetadata.toolUsePromptTokensDetails.map((item) => ({
+        modality: item.modality || "UNKNOWN",
+        tokenCount: item.tokenCount ?? 0
+      }))
+    } : {},
+    ...usageMetadata.cacheTokensDetails && usageMetadata.cacheTokensDetails.length > 0 ? {
+      cacheTokensDetails: usageMetadata.cacheTokensDetails.map((item) => ({
+        modality: item.modality || "UNKNOWN",
+        tokenCount: item.tokenCount ?? 0
+      }))
+    } : {}
+  };
+  if (Object.keys(promptTokensDetails).length > 0) {
+    result.promptTokensDetails = promptTokensDetails;
+  }
+  if (Object.keys(providerDetails).length > 0) {
+    result.providerUsageDetails = providerDetails;
+  }
+  if (Object.keys(completionTokensDetails).length > 0) {
+    result.completionTokensDetails = completionTokensDetails;
+  }
+  return result;
+}
+export {
+  buildGeminiUsage,
+  flattenModalityTokenCounts,
+  hasModalityTokens
+};
+//# sourceMappingURL=usage.js.map

package/dist/esm/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sources":["../../src/usage.ts"],"sourcesContent":["import { buildBaseUsage } from '@tanstack/ai'\nimport type { TokenUsage } from '@tanstack/ai'\nimport type {\n  GenerateContentResponseUsageMetadata,\n  ModalityTokenCount,\n} from '@google/genai'\n\n/**\n * Flattened modality token counts for normalized usage reporting.\n * Maps Gemini's ModalityTokenCount array to individual fields.\n */\nexport interface FlattenedModalityTokens {\n  /** Text tokens */\n  textTokens?: number\n  /** Image tokens */\n  imageTokens?: number\n  /** Audio tokens */\n  audioTokens?: number\n  /** Video tokens */\n  videoTokens?: number\n  /** Document tokens (e.g. PDF inputs) */\n  documentTokens?: number\n}\n\n/**\n * Flattens Gemini's ModalityTokenCount array into individual token fields.\n * Extracts TEXT, IMAGE, AUDIO, VIDEO, DOCUMENT modality counts into a\n * normalized structure.\n */\nexport function flattenModalityTokenCounts(\n  modalities?: Array<ModalityTokenCount>,\n): FlattenedModalityTokens {\n  if (!modalities || modalities.length === 0) {\n    return {}\n  }\n\n  const result: FlattenedModalityTokens = {}\n\n  for (const item of modalities) {\n    if (!item.modality || item.tokenCount === undefined) {\n      continue\n    }\n\n    const modality = item.modality.toUpperCase()\n    const count = item.tokenCount\n\n    switch (modality) {\n      case 'TEXT':\n        result.textTokens = (result.textTokens ?? 0) + count\n        break\n      case 'IMAGE':\n        result.imageTokens = (result.imageTokens ?? 0) + count\n        break\n      case 'AUDIO':\n        result.audioTokens = (result.audioTokens ?? 0) + count\n        break\n      case 'VIDEO':\n        result.videoTokens = (result.videoTokens ?? 0) + count\n        break\n      case 'DOCUMENT':\n        result.documentTokens = (result.documentTokens ?? 0) + count\n        break\n    }\n  }\n\n  return result\n}\n\n/**\n * Checks if a FlattenedModalityTokens object has any values set.\n */\nexport function hasModalityTokens(tokens: FlattenedModalityTokens): boolean {\n  return (\n    tokens.textTokens !== undefined ||\n    tokens.imageTokens !== undefined ||\n    tokens.audioTokens !== undefined ||\n    tokens.videoTokens !== undefined ||\n    tokens.documentTokens !== undefined\n  )\n}\n\n/**\n * Gemini-specific provider usage details.\n * These fields are unique to Gemini and placed in providerUsageDetails.\n */\nexport type GeminiProviderUsageDetails = {\n  /**\n   * The traffic type for this request.\n   * Can indicate whether request was handled by different service tiers.\n   */\n  trafficType?: string\n  /**\n   * Number of tokens in the results from tool executions,\n   * which are provided back to the model as input.\n   */\n  toolUsePromptTokenCount?: number\n  /**\n   * Detailed breakdown by modality of the token counts from\n   * the results of tool executions.\n   */\n  toolUsePromptTokensDetails?: Array<{\n    modality: string\n    tokenCount: number\n  }>\n  /**\n   * Detailed breakdown of cache tokens by modality.\n   * More granular than the normalized cachedTokens field.\n   */\n  cacheTokensDetails?: Array<{\n    modality: string\n    tokenCount: number\n  }>\n}\n\n/**\n * Build normalized TokenUsage from Gemini's usageMetadata.\n * Handles modality breakdowns and thinking tokens. Returns `undefined` when the\n * provider reported no usage metadata, so callers omit the field rather than\n * fabricating zeroed totals.\n */\nexport function buildGeminiUsage(\n  usageMetadata: GenerateContentResponseUsageMetadata | undefined | null,\n): TokenUsage<GeminiProviderUsageDetails> | undefined {\n  if (!usageMetadata) return undefined\n\n  const promptTokens = usageMetadata.promptTokenCount ?? 0\n  const completionTokens = usageMetadata.candidatesTokenCount ?? 0\n\n  const result = buildBaseUsage<GeminiProviderUsageDetails>({\n    promptTokens: promptTokens,\n    completionTokens: completionTokens,\n    totalTokens:\n      usageMetadata.totalTokenCount ?? promptTokens + completionTokens,\n  })\n\n  // Add prompt token details\n  // Flatten modality breakdown for prompt\n  const promptModalities = flattenModalityTokenCounts(\n    usageMetadata.promptTokensDetails,\n  )\n  const cachedTokens = usageMetadata.cachedContentTokenCount\n\n  const promptTokensDetails = {\n    ...(hasModalityTokens(promptModalities) ? promptModalities : {}),\n    ...(cachedTokens !== undefined && cachedTokens > 0 ? { cachedTokens } : {}),\n  }\n\n  // Add completion token details\n  // Flatten modality breakdown for candidates (output)\n  const completionModalities = flattenModalityTokenCounts(\n    usageMetadata.candidatesTokensDetails,\n  )\n  const thoughtsTokens = usageMetadata.thoughtsTokenCount\n\n  const completionTokensDetails = {\n    ...(hasModalityTokens(completionModalities) ? completionModalities : {}),\n    // Map thoughtsTokenCount to reasoningTokens for consistency with OpenAI\n    ...(thoughtsTokens !== undefined && thoughtsTokens > 0\n      ? { reasoningTokens: thoughtsTokens }\n      : {}),\n  }\n\n  // Add provider-specific details\n  const providerDetails: GeminiProviderUsageDetails = {\n    ...(usageMetadata.trafficType\n      ? { trafficType: usageMetadata.trafficType }\n      : {}),\n    ...(usageMetadata.toolUsePromptTokenCount !== undefined &&\n    usageMetadata.toolUsePromptTokenCount > 0\n      ? { toolUsePromptTokenCount: usageMetadata.toolUsePromptTokenCount }\n      : {}),\n    ...(usageMetadata.toolUsePromptTokensDetails &&\n    usageMetadata.toolUsePromptTokensDetails.length > 0\n      ? {\n          toolUsePromptTokensDetails:\n            usageMetadata.toolUsePromptTokensDetails.map((item) => ({\n              modality: item.modality || 'UNKNOWN',\n              tokenCount: item.tokenCount ?? 0,\n            })),\n        }\n      : {}),\n    ...(usageMetadata.cacheTokensDetails &&\n    usageMetadata.cacheTokensDetails.length > 0\n      ? {\n          cacheTokensDetails: usageMetadata.cacheTokensDetails.map((item) => ({\n            modality: item.modality || 'UNKNOWN',\n            tokenCount: item.tokenCount ?? 0,\n          })),\n        }\n      : {}),\n  }\n\n  // Add prompt token details if available\n  if (Object.keys(promptTokensDetails).length > 0) {\n    result.promptTokensDetails = promptTokensDetails\n  }\n  // Add provider details if available\n  if (Object.keys(providerDetails).length > 0) {\n    result.providerUsageDetails = providerDetails\n  }\n  // Add completion token details if available\n  if (Object.keys(completionTokensDetails).length > 0) {\n    result.completionTokensDetails = completionTokensDetails\n  }\n\n  return result\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-gemini",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "Google Gemini adapter for TanStack AI chat, images, speech, audio generation, and structured outputs.",
   "author": "",
   "license": "MIT",
@@ -50,13 +50,13 @@
     "@tanstack/ai-utils": "0.2.1"
   },
   "peerDependencies": {
-    "@tanstack/ai": "^0.23.0"
+    "@tanstack/ai": "^0.25.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "4.0.14",
     "vite": "^7.3.3",
     "zod": "^4.2.0",
-    "@tanstack/ai": "0.23.0"
+    "@tanstack/ai": "0.25.0"
   },
   "scripts": {
     "build": "vite build",

package/src/adapters/audio.ts

@@ -4,6 +4,7 @@ import {
   generateId,
   getGeminiApiKeyFromEnv,
 } from '../utils'
+import { buildGeminiUsage } from '../usage'
 import type { GEMINI_AUDIO_MODELS } from '../model-meta'
 import type {
   AudioGenerationOptions,
@@ -122,6 +123,11 @@ export class GeminiAudioAdapter<
           b64Json: audioPart.inlineData.data,
           ...(contentType !== undefined && { contentType }),
         },
+        // Surface token usage (with per-modality breakdown) when Gemini reports
+        // it. Spread conditionally for exactOptionalPropertyTypes.
+        ...(response.usageMetadata
+          ? { usage: buildGeminiUsage(response.usageMetadata) }
+          : {}),
       }
     } catch (error) {
       logger.errors('gemini.generateAudio fatal', {

package/src/adapters/image.ts

@@ -4,6 +4,7 @@ import {
   generateId,
   getGeminiApiKeyFromEnv,
 } from '../utils'
+import { buildGeminiUsage } from '../usage'
 import {
   parseNativeImageSize,
   sizeToAspectRatio,
@@ -214,16 +215,13 @@ 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,
-        },
-      }),
+      // Surface token usage (with per-modality breakdown) 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: buildGeminiUsage(response.usageMetadata) }
+        : {}),
     }
   }
 

package/src/adapters/text.ts

@@ -1,7 +1,9 @@
 import { FinishReason } from '@google/genai'
 import { EventType, normalizeSystemPrompts } from '@tanstack/ai'
+import { toRunErrorRawEvent } from '@tanstack/ai/adapter-internals'
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
 import { convertToolsToProviderFormat } from '../tools/tool-converter'
+import { buildGeminiUsage } from '../usage'
 import {
   createGeminiClient,
   generateId,
@@ -133,6 +135,7 @@ export class GeminiTextAdapter<
 
       yield* this.processStreamChunks(result, options, logger)
     } catch (error) {
+      const rawEvent = toRunErrorRawEvent(error)
       logger.errors('gemini.chatStream fatal', {
         error,
         source: 'gemini.chatStream',
@@ -145,6 +148,9 @@ export class GeminiTextAdapter<
           error instanceof Error
             ? error.message
             : 'An unknown error occurred during the chat stream.',
+        // Forward the provider's structured error body when present (see
+        // toRunErrorRawEvent); omitted otherwise.
+        ...(rawEvent !== undefined && { rawEvent }),
         error: {
           message:
             error instanceof Error
@@ -199,6 +205,9 @@ export class GeminiTextAdapter<
       return {
         data: parsed,
         rawText,
+        usage: result.usageMetadata
+          ? buildGeminiUsage(result.usageMetadata)
+          : undefined,
       }
     } catch (error) {
       logger.errors('gemini.structuredOutput fatal', {
@@ -628,11 +637,7 @@ export class GeminiTextAdapter<
           // exactOptionalPropertyTypes; only include it when usageMetadata is
           // present rather than assigning an explicit `undefined`.
           ...(chunk.usageMetadata && {
-            usage: {
-              promptTokens: chunk.usageMetadata.promptTokenCount ?? 0,
-              completionTokens: chunk.usageMetadata.candidatesTokenCount ?? 0,
-              totalTokens: chunk.usageMetadata.totalTokenCount ?? 0,
-            },
+            usage: buildGeminiUsage(chunk.usageMetadata),
           }),
         }
       }
@@ -744,15 +749,52 @@ export class GeminiTextAdapter<
       if (msg.role === 'tool' && msg.toolCallId) {
         const functionName =
           toolCallIdToName.get(msg.toolCallId) || msg.toolCallId
-        parts.push({
-          functionResponse: {
-            id: msg.toolCallId,
-            name: functionName,
-            response: {
-              content: msg.content || '',
+        const toolContent = msg.content
+        if (Array.isArray(toolContent)) {
+          const textChunks: Array<string> = []
+          const mediaParts: Array<Part> = []
+          for (const part of toolContent) {
+            if (part.type === 'text') {
+              textChunks.push(part.content)
+            } else if (part.source.type === 'data') {
+              mediaParts.push({
+                inlineData: {
+                  data: part.source.value,
+                  mimeType: part.source.mimeType,
+                },
+              })
+            } else {
+              const defaultMimeType = {
+                image: 'image/jpeg',
+                audio: 'audio/mp3',
+                video: 'video/mp4',
+                document: 'application/pdf',
+              }[part.type]
+              mediaParts.push({
+                fileData: {
+                  fileUri: part.source.value,
+                  mimeType: part.source.mimeType ?? defaultMimeType,
+                },
+              })
+            }
+          }
+          parts.push({
+            functionResponse: {
+              id: msg.toolCallId,
+              name: functionName,
+              response: { content: textChunks.join('\n') },
+              ...(mediaParts.length > 0 && { parts: mediaParts }),
             },
-          },
-        })
+          })
+        } else {
+          parts.push({
+            functionResponse: {
+              id: msg.toolCallId,
+              name: functionName,
+              response: { content: toolContent || '' },
+            },
+          })
+        }
       }
 
       return {

package/src/adapters/tts.ts

@@ -5,6 +5,7 @@ import {
   getGeminiApiKeyFromEnv,
 } from '../utils'
 import { GEMINI_TTS_VOICES } from '../model-meta'
+import { buildGeminiUsage } from '../usage'
 import type { GEMINI_TTS_MODELS, GeminiTTSVoice } from '../model-meta'
 import type { TTSOptions, TTSResult } from '@tanstack/ai'
 import type { GoogleGenAI, SpeechConfig } from '@google/genai'
@@ -229,6 +230,13 @@ export class GeminiTTSAdapter<
       // mime is guaranteed by the `startsWith('audio/')` find predicate above.
       const mimeType = audioPart.inlineData.mimeType as string
 
+      // Surface token usage (with per-modality breakdown) when Gemini reports
+      // it. Spread conditionally for exactOptionalPropertyTypes — shared by both
+      // the PCM→WAV and pass-through return paths below.
+      const usageField = response.usageMetadata
+        ? { usage: buildGeminiUsage(response.usageMetadata) }
+        : {}
+
       // Gemini TTS models return raw 16-bit LE PCM with a mime type like
       // `audio/L16;codec=pcm;rate=24000`. That isn't playable in an <audio>
       // element and the bare string isn't a usable file extension, so we
@@ -247,6 +255,7 @@ export class GeminiTTSAdapter<
           audio: wavBase64,
           format: 'wav',
           contentType: 'audio/wav',
+          ...usageField,
         }
       }
 
@@ -261,6 +270,7 @@ export class GeminiTTSAdapter<
         audio: audioBase64,
         format,
         contentType: mimeType,
+        ...usageField,
       }
     } catch (error) {
       logger.errors('gemini.generateSpeech fatal', {

package/src/index.ts

@@ -97,3 +97,6 @@ export type {
   GeminiDocumentMetadata,
   GeminiMessageMetadataByModality,
 } from './message-types'
+
+// Export provider usage types
+export type { GeminiProviderUsageDetails } from './usage'