@ai-sdk/google 4.0.78 → 4.0.80

package/docs/15-google.mdx

@@ -923,14 +923,14 @@ The `vertexRagStore` tool accepts the following configuration options:
 
 ### Image Outputs
 
-Gemini models with image generation capabilities (e.g. `gemini-2.5-flash-image`) support generating images as part of a multimodal response. Images are exposed as files in the response.
+Gemini models with image generation capabilities (e.g. `gemini-3.1-flash-image-preview`) support generating images as part of a multimodal response. Images are exposed as files in the response.
 
 ```ts
 import { google } from '@ai-sdk/google';
 import { generateText } from 'ai';
 
 const result = await generateText({
-  model: google('gemini-2.5-flash-image'),
+  model: google('gemini-3.1-flash-image-preview'),
   prompt:
     'Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme',
 });
@@ -1088,7 +1088,7 @@ You can pass a `webhookUrl` to receive a notification when the batch reaches a t
 import { google } from '@ai-sdk/google';
 import { experimental_startBatch as startBatch } from 'ai';
 
-const model = 'gemini-3.6-flash';
+const model = 'gemini-3.8-flash';
 
 const batch = await startBatch({
   provider: google,
@@ -1578,7 +1578,7 @@ import { google, type GoogleInteractionsVideoOptions } from '@ai-sdk/google';
 import { generateText } from 'ai';
 
 const result = await generateText({
-  model: google.interactions('gemini-3.7-flash'),
+  model: google.interactions('gemini-3.8-flash'),
   messages: [
     {
       role: 'user',
@@ -1778,7 +1778,7 @@ import {
 import { generateText } from 'ai';
 
 const result = await generateText({
-  model: google.interactions('gemini-2.5-flash-image'),
+  model: google.interactions('gemini-3.1-flash-image-preview'),
   prompt:
     'Tell me a three sentence bedtime story about a unicorn, accompanied by a suitable illustration.',
   providerOptions: {
@@ -2042,7 +2042,7 @@ You can create models that call the [Google Generative AI embeddings API](https:
 using the `.embedding()` factory method.
 
 ```ts
-const model = google.embedding('gemini-embedding-001');
+const model = google.embedding('gemini-embedding-2');
 ```
 
 The Google provider sends API calls to the right endpoint based on the type of embedding:
@@ -2078,7 +2078,7 @@ import { google, type GoogleEmbeddingModelOptions } from '@ai-sdk/google';
 import { embedMany } from 'ai';
 
 const { embeddings } = await embedMany({
-  model: google.embedding('gemini-embedding-2-preview'),
+  model: google.embedding('gemini-embedding-2'),
   values: ['sunny day at the beach', 'rainy afternoon in the city'],
   providerOptions: {
     google: {
@@ -2132,14 +2132,14 @@ output capabilities through the `:generateContent` API.
 
 ### Gemini Image Models
 
-[Gemini image models](https://ai.google.dev/gemini-api/docs/image-generation) (e.g. `gemini-2.5-flash-image`) are technically multimodal output language models, but they can be used with the `generateImage()` function for a simpler image generation experience. Internally, the provider calls the language model API with `responseModalities: ['IMAGE']`.
+[Gemini image models](https://ai.google.dev/gemini-api/docs/image-generation) (e.g. `gemini-3.1-flash-image-preview`) are technically multimodal output language models, but they can be used with the `generateImage()` function for a simpler image generation experience. Internally, the provider calls the language model API with `responseModalities: ['IMAGE']`.
 
 ```ts
 import { google } from '@ai-sdk/google';
 import { generateImage } from 'ai';
 
 const { image } = await generateImage({
-  model: google.image('gemini-2.5-flash-image'),
+  model: google.image('gemini-3.1-flash-image-preview'),
   prompt: 'A photorealistic image of a cat wearing a wizard hat',
   aspectRatio: '1:1',
 });
@@ -2155,7 +2155,7 @@ import fs from 'node:fs';
 const sourceImage = fs.readFileSync('./cat.png');
 
 const { image } = await generateImage({
-  model: google.image('gemini-2.5-flash-image'),
+  model: google.image('gemini-3.1-flash-image-preview'),
   prompt: {
     text: 'Add a small wizard hat to this cat',
     images: [sourceImage],
@@ -2170,7 +2170,7 @@ import { google } from '@ai-sdk/google';
 import { generateImage } from 'ai';
 
 const { image } = await generateImage({
-  model: google.image('gemini-2.5-flash-image'),
+  model: google.image('gemini-3.1-flash-image-preview'),
   prompt: {
     text: 'Add a small wizard hat to this cat',
     images: ['https://example.com/cat.png'],
@@ -2233,45 +2233,100 @@ console.log(result.providerMetadata?.google?.groundingMetadata);
 You can create models that call the [Gemini text-to-speech API](https://ai.google.dev/gemini-api/docs/speech-generation)
 using the `.speech()` factory method.
 
-The first argument is the model id e.g. `gemini-2.5-flash-preview-tts`.
+The first argument is the model ID, such as `gemini-3.8-flash-tts` or
+`gemini-3.8-flash-lite-tts`. Speech generation uses the `generateContent` API.
 
 ```ts
-const model = google.speech('gemini-2.5-flash-preview-tts');
+const model = google.speech('gemini-3.8-flash-tts');
 ```
 
 The `voice` argument can be set to one of Gemini's [30 prebuilt voices](https://ai.google.dev/gemini-api/docs/speech-generation#voices)
-e.g. `Kore`, `Puck`, `Zephyr`, or `Charon`. Voice names are case-sensitive. It defaults to `Kore`.
+e.g. `Kore`, `Puck`, `Zephyr`, or `Charon`. Voice names are case-sensitive.
+The default voice is `Kore`. Custom voice IDs and replication keys are not supported.
 
 ```ts highlight="6"
 import { generateSpeech } from 'ai';
 import { google } from '@ai-sdk/google';
 
 const result = await generateSpeech({
-  model: google.speech('gemini-2.5-flash-preview-tts'),
+  model: google.speech('gemini-3.8-flash-tts'),
   text: 'Hello, world!',
   voice: 'Kore', // Gemini voice name
 });
 ```
 
-By default the generated audio is returned as a playable WAV file (`result.audio.mediaType` is
-`audio/wav`). Set `outputFormat: 'pcm'` to receive the raw signed 16-bit little-endian mono PCM
-bytes instead; the sample rate is reported in `result.providerMetadata.google.sampleRate`.
+By default the generated audio is returned as a playable WAV file
+(`result.audio.mediaType` is `audio/wav`). Gemini 3.8 returns a complete WAV file;
+the provider passes those bytes through unchanged. Older models return raw PCM,
+which the provider wraps in a WAV container. Write `result.audio.uint8Array`
+directly to disk without adding another WAV header.
+
+Gemini 3.8 supports the following `outputFormat` values:
 
-Gemini honors natural-language style direction. The `instructions` argument is prepended to the
-spoken text, so `instructions: 'Say cheerfully'` with `text: 'Hello'` speaks `Say cheerfully: Hello`.
+| Format | Values                 | Result                       |
+| ------ | ---------------------- | ---------------------------- |
+| WAV    | `wav`, `audio/wav`     | WAV with a RIFF header       |
+| PCM    | `pcm`, `audio/l16`     | Headerless signed 16-bit PCM |
+| Mu-law | `mulaw`, `audio/mulaw` | Headerless mu-law audio      |
+| A-law  | `alaw`, `audio/alaw`   | Headerless A-law audio       |
+
+These map to `generationConfig.responseFormat.audio.mimeType` in
+`generateContent`. Older models support `wav` and `pcm`. The source MIME type and
+sample rate are available in `result.providerMetadata.google`.
+
+Gemini 2.5 and 3.1 model IDs retain the legacy request format. Other model IDs,
+including custom aliases, use the structured speech format.
+
+### Speech directions in Gemini 3.8
+
+Gemini 3.8 treats text as a verbatim transcript. The provider sends `instructions`
+as `speechMetadata.style`, leaving the text unchanged. You can also supply
+`providerOptions.google.speechMetadata` with `style` and `speaker` fields.
+An explicit style overrides `instructions`, including an empty style string.
+
+```ts
+const result = await generateSpeech({
+  model: google.speech('gemini-3.8-flash-tts'),
+  text: 'Welcome back. <short pause> It is good to see you. <laugh>',
+  instructions: 'Warm, relaxed, and speaking slowly',
+});
+```
+
+Put sustained delivery directions such as whispering, speaking slowly, or being
+out of breath in metadata. Keep momentary vocal events and pauses such as
+`<laugh>`, `<sigh>`, `<cough>`, `<breath>`, and `<short pause>` in the transcript.
+Avoid sound-effect tags such as applause or thuds. The provider preserves inline
+tags as written.
+
+For Gemini 3.1 and earlier, the provider retains the existing behavior of
+prepending `instructions` to single-speaker text. It ignores instructions with a
+warning for older multi-speaker requests. Structured `turns` and `speechMetadata`
+require Gemini 3.8.
 
 ### Multi-speaker audio
 
-For multi-speaker dialogue, pass a `multiSpeakerVoiceConfig` through `providerOptions`. Each speaker
-name must match a name used in the input text. When set, it overrides the top-level `voice`.
+For Gemini 3.8 dialogue, pass `multiSpeakerVoiceConfig` and `turns` through
+`providerOptions.google`. Every turn must include `speechMetadata.speaker`
+matching a configured speaker; missing or unknown speakers produce an error
+before the request is sent. Speaker labels belong in metadata, not the text.
 
-```ts highlight="7-22"
+The `turns` array replaces the top-level text, so pass `text: ''`. The combined
+turn text must be non-empty. Passing
+nonempty top-level text with turns produces a warning. Put metadata on each turn
+instead of combining turns with top-level `speechMetadata`. Each turn's style
+overrides `instructions`; turns without a style inherit `instructions`.
+
+`multiSpeakerVoiceConfig` overrides the top-level `voice`. Each `voiceConfig`
+uses `prebuiltVoiceConfig: { voiceName: 'Kore' }`. Google supports up to two
+prebuilt voices in a multi-speaker request.
+
+```ts
 import { generateSpeech } from 'ai';
 import { google, type GoogleSpeechModelOptions } from '@ai-sdk/google';
 
 const result = await generateSpeech({
-  model: google.speech('gemini-2.5-flash-preview-tts'),
-  text: 'Joe: How are you? Jane: Doing great, thanks!',
+  model: google.speech('gemini-3.8-flash-lite-tts'),
+  text: '',
   providerOptions: {
     google: {
       multiSpeakerVoiceConfig: {
@@ -2286,11 +2341,25 @@ const result = await generateSpeech({
           },
         ],
       },
+      turns: [
+        {
+          text: 'How are you?',
+          speechMetadata: { speaker: 'Joe', style: 'curious' },
+        },
+        {
+          text: '<laugh> Doing great, thanks!',
+          speechMetadata: { speaker: 'Jane', style: 'cheerful' },
+        },
+      ],
     } satisfies GoogleSpeechModelOptions,
   },
 });
 ```
 
+Older models continue to use labelled transcripts, such as
+`text: 'Joe: How are you? Jane: Doing great, thanks!'`, with
+`multiSpeakerVoiceConfig` and without `turns`.
+
 <Note>
   Gemini TTS models do not support the `speed` or `language` options; passing
   them adds a warning to `result.warnings`. Language is detected automatically
@@ -2304,6 +2373,8 @@ const result = await generateSpeech({
 | `gemini-2.5-flash-preview-tts` | <Check />     | <Check />              |
 | `gemini-2.5-pro-preview-tts`   | <Check />     | <Check />              |
 | `gemini-3.1-flash-tts-preview` | <Check />     | <Check />              |
+| `gemini-3.8-flash-tts`         | <Check />     | <Check />              |
+| `gemini-3.8-flash-lite-tts`    | <Check />     | <Check />              |
 
 ## Evaluation Models
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/google",
-  "version": "4.0.78",
+  "version": "4.0.80",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "4.0.18",
-    "@ai-sdk/provider-utils": "5.0.46"
+    "@ai-sdk/provider-utils": "5.0.47"
   },
   "devDependencies": {
     "@ai-sdk/test-server": "2.0.1",

package/src/convert-to-google-messages.ts

@@ -1,5 +1,6 @@
 import {
   UnsupportedFunctionalityError,
+  type JSONValue,
   type LanguageModelV4Prompt,
   type LanguageModelV4ToolResultOutput,
   type SharedV4Warning,
@@ -18,6 +19,10 @@ import type {
   GoogleFunctionResponsePart,
   GooglePrompt,
 } from './google-prompt';
+import {
+  codeExecutionInputSchema,
+  codeExecutionOutputSchema,
+} from './tool/code-execution';
 
 /**
  * Sentinel value Google documents for replaying functionCall parts whose
@@ -63,6 +68,30 @@ function convertUrlToolResultPart(
   };
 }
 
+function containsJSONSchemaReference(value: JSONValue | undefined): boolean {
+  if (Array.isArray(value)) {
+    return value.some(containsJSONSchemaReference);
+  }
+
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  return Object.entries(value).some(
+    ([key, nestedValue]) =>
+      key === '$ref' || containsJSONSchemaReference(nestedValue),
+  );
+}
+
+function serializeFunctionResponseContent(
+  value: JSONValue,
+): JSONValue | string {
+  // Google reserves { $ref: displayName } in structured function responses for
+  // multimodal parts. This conflicts with JSON Schema $ref, so serialize the
+  // result to preserve it without triggering Google's reference handling.
+  return containsJSONSchemaReference(value) ? JSON.stringify(value) : value;
+}
+
 /*
  * Appends tool result content parts to the message using the functionResponse
  * format with support for multimodal parts (e.g. inline images/files alongside
@@ -465,6 +494,19 @@ export function convertToGoogleMessages(
                 }
 
                 case 'tool-call': {
+                  if (
+                    part.providerExecuted === true &&
+                    part.toolName === 'code_execution'
+                  ) {
+                    return {
+                      executableCode: codeExecutionInputSchema.parse(
+                        typeof part.input === 'string'
+                          ? secureJsonParse(part.input)
+                          : part.input,
+                      ),
+                    };
+                  }
+
                   const serverToolCallId =
                     providerOpts?.serverToolCallId != null
                       ? String(providerOpts.serverToolCallId)
@@ -520,6 +562,17 @@ export function convertToGoogleMessages(
                 }
 
                 case 'tool-result': {
+                  if (
+                    part.toolName === 'code_execution' &&
+                    part.output.type === 'json'
+                  ) {
+                    return {
+                      codeExecutionResult: codeExecutionOutputSchema.parse(
+                        part.output.value,
+                      ),
+                    };
+                  }
+
                   const serverToolCallId =
                     providerOpts?.serverToolCallId != null
                       ? String(providerOpts.serverToolCallId)
@@ -626,7 +679,7 @@ export function convertToGoogleMessages(
                   content:
                     output.type === 'execution-denied'
                       ? (output.reason ?? 'Tool call execution denied.')
-                      : output.value,
+                      : serializeFunctionResponseContent(output.value),
                 },
               },
             });

package/src/google-embedding-model.ts

@@ -5,6 +5,8 @@ import {
 import {
   combineHeaders,
   createJsonResponseHandler,
+  type EmbeddingModelProviderOptionsTransformer,
+  EXPERIMENTAL_EMBEDDING_MODEL_PROVIDER_OPTIONS_TRANSFORMER,
   lazySchema,
   parseProviderOptions,
   postJsonToApi,
@@ -33,6 +35,28 @@ export class GoogleEmbeddingModel implements EmbeddingModelV4 {
   readonly modelId: GoogleEmbeddingModelId;
   readonly maxEmbeddingsPerCall = 100;
   readonly supportsParallelCalls = true;
+  readonly [EXPERIMENTAL_EMBEDDING_MODEL_PROVIDER_OPTIONS_TRANSFORMER]: EmbeddingModelProviderOptionsTransformer =
+    ({ providerOptions, values, startIndex, endIndex }) => {
+      const multimodalContent = providerOptions?.google?.content;
+
+      // Leave schema validation to doEmbed, after middleware transforms options.
+      if (!Array.isArray(multimodalContent)) {
+        return providerOptions;
+      }
+
+      validateMultimodalContentLength({
+        multimodalContent,
+        values,
+      });
+
+      return {
+        ...providerOptions,
+        google: {
+          ...providerOptions?.google,
+          content: multimodalContent.slice(startIndex, endIndex),
+        },
+      };
+    };
 
   private readonly config: GoogleEmbeddingConfig;
 
@@ -89,14 +113,7 @@ export class GoogleEmbeddingModel implements EmbeddingModelV4 {
 
     const multimodalContent = googleOptions?.content;
 
-    if (
-      multimodalContent != null &&
-      multimodalContent.length !== values.length
-    ) {
-      throw new Error(
-        `The number of multimodal content entries (${multimodalContent.length}) must match the number of values (${values.length}).`,
-      );
-    }
+    validateMultimodalContentLength({ multimodalContent, values });
 
     // For single embeddings, use the single endpoint
     if (values.length === 1) {
@@ -199,3 +216,17 @@ const googleGenerativeAISingleEmbeddingResponseSchema = lazySchema(() =>
     }),
   ),
 );
+
+function validateMultimodalContentLength({
+  multimodalContent,
+  values,
+}: {
+  multimodalContent: Array<unknown> | undefined;
+  values: Array<string>;
+}) {
+  if (multimodalContent != null && multimodalContent.length !== values.length) {
+    throw new Error(
+      `The number of multimodal content entries (${multimodalContent.length}) must match the number of values (${values.length}).`,
+    );
+  }
+}

package/src/google-json-accumulator.ts

@@ -367,5 +367,4 @@ function resolvePartialArgValue(arg: {
   const value = arg.stringValue ?? arg.numberValue ?? arg.boolValue;
   if (value != null) return { value, json: JSON.stringify(value) };
   if ('nullValue' in arg) return { value: null, json: 'null' };
-  return undefined;
 }

package/src/google-prompt.ts

@@ -59,6 +59,18 @@ export type GoogleContentPart =
         id: string;
       };
       thoughtSignature?: string;
+    }
+  | {
+      executableCode: {
+        language: string;
+        code: string;
+      };
+    }
+  | {
+      codeExecutionResult: {
+        outcome: string;
+        output: string;
+      };
     };
 
 export type GoogleFunctionResponsePart = {

package/src/google-speech-api.ts

@@ -4,7 +4,8 @@ import { z } from 'zod/v4';
 /**
  * Response schema for the Gemini `:generateContent` endpoint when called with
  * `responseModalities: ['AUDIO']`. The generated audio is returned as base64
- * encoded raw PCM in the first inline-data part.
+ * encoded audio in the first inline-data part (WAV by default on Gemini 3.8,
+ * raw PCM on older models).
  */
 export const googleSpeechResponseSchema = lazySchema(() =>
   zodSchema(

package/src/google-speech-input.ts

@@ -0,0 +1,64 @@
+/**
+ * Inspects speech input without replacing provider option validation. This is
+ * also used by intermediaries that need the transcript or voice kind before
+ * invoking a model. Model support for structured turns is validated separately.
+ */
+export function getGoogleSpeechInput({
+  text,
+  voice,
+  providerOptions,
+}: {
+  text: string;
+  voice?: string;
+  providerOptions?: Record<string, unknown>;
+}): { text: string; usesCustomVoice: boolean } {
+  const google = providerOptions?.google;
+  const options =
+    google != null && typeof google === 'object' ? google : undefined;
+  const turns = options && 'turns' in options ? options.turns : undefined;
+  const turnTexts: string[] = [];
+  if (Array.isArray(turns) && turns.length > 0) {
+    for (const turn of turns as unknown[]) {
+      if (
+        turn == null ||
+        typeof turn !== 'object' ||
+        !('text' in turn) ||
+        typeof turn.text !== 'string'
+      ) {
+        break;
+      }
+      turnTexts.push(turn.text);
+    }
+    if (turnTexts.length === turns.length) {
+      text = turnTexts.join('');
+    }
+  }
+
+  const config =
+    options && 'multiSpeakerVoiceConfig' in options
+      ? options.multiSpeakerVoiceConfig
+      : undefined;
+  const speakers =
+    config != null &&
+    typeof config === 'object' &&
+    'speakerVoiceConfigs' in config &&
+    Array.isArray(config.speakerVoiceConfigs)
+      ? (config.speakerVoiceConfigs as unknown[])
+      : [];
+
+  return {
+    text,
+    usesCustomVoice:
+      voice?.startsWith('voice_') === true ||
+      voice?.startsWith('voicekey_') === true ||
+      speakers.some(
+        speaker =>
+          speaker != null &&
+          typeof speaker === 'object' &&
+          'voiceConfig' in speaker &&
+          speaker.voiceConfig != null &&
+          typeof speaker.voiceConfig === 'object' &&
+          'voice' in speaker.voiceConfig,
+      ),
+  };
+}

package/src/google-speech-model-options.ts

@@ -9,6 +9,8 @@ export type GoogleSpeechModelId =
   | 'gemini-2.5-flash-preview-tts'
   | 'gemini-2.5-pro-preview-tts'
   | 'gemini-3.1-flash-tts-preview'
+  | 'gemini-3.8-flash-tts'
+  | 'gemini-3.8-flash-lite-tts'
   | (string & {});
 
 const prebuiltVoiceConfigSchema = z.object({
@@ -17,15 +19,40 @@ const prebuiltVoiceConfigSchema = z.object({
 
 const voiceConfigSchema = z.object({
   prebuiltVoiceConfig: prebuiltVoiceConfigSchema,
+  voice: z.never().optional(),
+});
+
+const speechMetadataSchema = z.object({
+  speaker: z.string().min(1).optional(),
+  style: z.string().optional(),
 });
 
 export const googleSpeechProviderOptionsSchema = lazySchema(() =>
   zodSchema(
     z.object({
+      /** Turn-level directions for the top-level text, for Gemini 3.8 TTS. */
+      speechMetadata: speechMetadataSchema.optional(),
+
+      /**
+       * Structured transcript for Gemini 3.8 TTS. Replaces the top-level text;
+       * pass text: '' when using turns. Each multi-speaker turn must name a
+       * configured speaker in speechMetadata. Per-turn styles override instructions.
+       */
+      turns: z
+        .array(
+          z.object({
+            text: z.string(),
+            speechMetadata: speechMetadataSchema.optional(),
+          }),
+        )
+        .min(1)
+        .optional(),
+
       /**
        * Multi-speaker configuration for dialogue audio. When provided, this
        * overrides the top-level `voice`. The Gemini TTS API supports up to two
-       * speakers; each speaker name must match a name used in the input text.
+       * speakers. For Gemini 3.8, each turn's speechMetadata.speaker must match
+       * a configured speaker; older models use speaker labels in the text.
        *
        * https://ai.google.dev/gemini-api/docs/speech-generation#multi-speaker
        */