@ai-sdk/google 4.0.0-canary.71 → 4.0.0-canary.72

package/docs/15-google.mdx

@@ -1897,6 +1897,29 @@ const { image } = await generateImage({
   details.
 </Note>
 
+#### Google Search Grounding
+
+Gemini image models support [Google Search grounding](#google-search) through `providerOptions.google.googleSearch`. The value matches the args of `google.tools.googleSearch(...)`; pass `{}` to enable with defaults, or `{ searchTypes: { imageSearch: {} } }` to ground on reference photos.
+
+```ts
+import { google } from '@ai-sdk/google';
+import { generateImage } from 'ai';
+
+const result = await generateImage({
+  model: google.image('gemini-3.1-flash-image-preview'),
+  prompt:
+    'Search for live footage of the 2026 Super Bowl halftime show artist, then generate a close-up in space.',
+  providerOptions: {
+    google: {
+      googleSearch: { searchTypes: { imageSearch: {} } },
+    },
+  },
+});
+
+// Grounding metadata is forwarded onto the image result:
+console.log(result.providerMetadata?.google?.groundingMetadata);
+```
+
 #### Gemini Image Model Capabilities
 
 | Model                            | Image Generation    | Image Editing       | Aspect Ratios                                       |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/google",
-  "version": "4.0.0-canary.71",
+  "version": "4.0.0-canary.72",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,

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

@@ -4,6 +4,7 @@ import {
   type InferSchema,
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
+import { googleSearchToolArgsBaseSchema } from './tool/google-search';
 
 // Note: For the initial GA launch of Imagen 3, safety filters are not configurable.
 // https://ai.google.dev/gemini-api/docs/imagen#imagen-model
@@ -14,6 +15,17 @@ export const googleImageModelOptionsSchema = lazySchema(() =>
         .enum(['dont_allow', 'allow_adult', 'allow_all'])
         .nullish(),
       aspectRatio: z.enum(['1:1', '3:4', '4:3', '9:16', '16:9']).nullish(),
+
+      /**
+       * Enable Google Search grounding for Gemini image models. The value is
+       * forwarded as the args of the `google.tools.googleSearch` provider
+       * tool on the underlying language-model call. Pass `{}` for defaults.
+       *
+       * `generateImage` does not accept a `tools` parameter, so this is the
+       * dedicated escape hatch for grounding image generation the same way
+       * `generateText` does.
+       */
+      googleSearch: googleSearchToolArgsBaseSchema.optional(),
     }),
   ),
 );

package/src/google-image-model.ts

@@ -156,7 +156,17 @@ export class GoogleImageModel implements ImageModelV4 {
     }
 
     if (googleOptions) {
-      Object.assign(parameters, googleOptions);
+      const { googleSearch: imagenGoogleSearch, ...imagenOptions } =
+        googleOptions;
+      if (imagenGoogleSearch != null) {
+        warnings.push({
+          type: 'unsupported',
+          feature: 'googleSearch',
+          details:
+            'Google Search grounding is only supported on Gemini image models.',
+        });
+      }
+      Object.assign(parameters, imagenOptions);
     }
 
     const body = {
@@ -283,6 +293,18 @@ export class GoogleImageModel implements ImageModelV4 {
       { role: 'user', content: userContent },
     ];
 
+    // Parse image-model-specific provider options so we can map them onto
+    // the underlying language-model call. `googleSearch` is the dedicated
+    // escape hatch for grounding (generateImage has no `tools` parameter).
+    const googleImageOptions = await parseProviderOptions({
+      provider: 'google',
+      providerOptions,
+      schema: googleImageModelOptionsSchema,
+    });
+
+    const { googleSearch: _strippedGoogleSearch, ...passthroughGoogleOptions } =
+      providerOptions?.google ?? {};
+
     // Instantiate language model
     const languageModel = new GoogleLanguageModel(this.modelId, {
       provider: this.config.provider,
@@ -306,12 +328,23 @@ export class GoogleImageModel implements ImageModelV4 {
                 >['aspectRatio'],
               }
             : undefined,
-          ...((providerOptions?.google as Omit<
+          ...(passthroughGoogleOptions as Omit<
             GoogleLanguageModelOptions,
             'responseModalities' | 'imageConfig'
-          >) ?? {}),
+          >),
         } satisfies GoogleLanguageModelOptions,
       },
+      tools:
+        googleImageOptions?.googleSearch != null
+          ? [
+              {
+                type: 'provider',
+                id: 'google.google_search',
+                name: 'google_search',
+                args: googleImageOptions.googleSearch,
+              },
+            ]
+          : undefined,
       headers,
       abortSignal,
     });
@@ -329,11 +362,17 @@ export class GoogleImageModel implements ImageModelV4 {
       }
     }
 
+    const languageModelGoogleMetadata =
+      (result.providerMetadata?.google as
+        | Record<string, unknown>
+        | undefined) ?? {};
+
     return {
       images,
       warnings,
       providerMetadata: {
         google: {
+          ...languageModelGoogleMetadata,
           images: images.map(() => ({})),
         },
       },

package/src/tool/google-search.ts

@@ -9,7 +9,7 @@ import { z } from 'zod/v4';
 // https://ai.google.dev/api/generate-content#GroundingSupport
 // https://cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-search
 
-const googleSearchToolArgsBaseSchema = z
+export const googleSearchToolArgsBaseSchema = z
   .object({
     searchTypes: z
       .object({