--- title: Google description: Learn how to use Google Provider. --- # Google Provider The [Google](https://ai.google.dev) provider contains language and embedding model support for the [Google](https://ai.google.dev/api/rest) APIs. ## Setup The Google provider is available in the `@ai-sdk/google` module. You can install it with ## Provider Instance You can import the default provider instance `google` from `@ai-sdk/google`: ```ts import { google } from '@ai-sdk/google'; ``` If you need a customized setup, you can import `createGoogle` from `@ai-sdk/google` and create a provider instance with your settings: ```ts import { createGoogle } from '@ai-sdk/google'; const google = createGoogle({ // custom settings }); ``` You can use the following optional settings to customize the Google provider instance: - **baseURL** _string_ Use a different URL prefix for API calls, e.g. to use proxy servers. The default prefix is `https://generativelanguage.googleapis.com/v1beta`. - **apiKey** _string_ API key that is being sent using the `x-goog-api-key` header. It defaults to the `GOOGLE_GENERATIVE_AI_API_KEY` environment variable. - **headers** _Record<string,string>_ Custom headers to include in the requests. - **fetch** _(input: RequestInfo, init?: RequestInit) => Promise<Response>_ Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation. Defaults to the global `fetch` function. You can use it as a middleware to intercept requests, or to provide a custom fetch implementation for e.g. testing. - **generateId** _() => string_ Optional function to generate unique IDs for each request. Defaults to the SDK's built-in ID generator. - **name** _string_ Custom provider name. Defaults to `'google.generative-ai'`. ## Language Models You can create models that call the [Google Generative AI API](https://ai.google.dev/api/rest) using the provider instance. The first argument is the model id, e.g. `gemini-2.5-flash`. The models support tool calls and some have multi-modal capabilities. ```ts const model = google('gemini-2.5-flash'); ``` You can use Google language models to generate text with the `generateText` function: ```ts import { google } from '@ai-sdk/google'; import { generateText } from 'ai'; const { text } = await generateText({ model: google('gemini-2.5-flash'), prompt: 'Write a vegetarian lasagna recipe for 4 people.', }); ``` Google language models can also be used in the `streamText` function and support structured data generation with [`Output`](/docs/reference/ai-sdk-core/output) (see [AI SDK Core](/docs/ai-sdk-core)). Google also supports some model specific settings that are not part of the [standard call settings](/docs/ai-sdk-core/settings). You can pass them as an options argument: ```ts import { google, type GoogleLanguageModelOptions } from '@ai-sdk/google'; const model = google('gemini-2.5-flash'); await generateText({ model, providerOptions: { google: { safetySettings: [ { category: 'HARM_CATEGORY_UNSPECIFIED', threshold: 'BLOCK_LOW_AND_ABOVE', }, ], } satisfies GoogleLanguageModelOptions, }, }); ``` The following optional provider options are available for Google models: - **cachedContent** _string_ Optional. The name of the cached content used as context to serve the prediction. Format: cachedContents/\{cachedContent\} - **structuredOutputs** _boolean_ Optional. Enable structured output. Default is true. This is useful when the JSON Schema contains elements that are not supported by the OpenAPI schema version that Google uses. You can use this to disable structured outputs if you need to. See [Troubleshooting: Schema Limitations](#schema-limitations) for more details. - **safetySettings** _Array\<\{ category: string; threshold: string \}\>_ Optional. Safety settings for the model. - **category** _string_ The category of the safety setting. Can be one of the following: - `HARM_CATEGORY_UNSPECIFIED` - `HARM_CATEGORY_HATE_SPEECH` - `HARM_CATEGORY_DANGEROUS_CONTENT` - `HARM_CATEGORY_HARASSMENT` - `HARM_CATEGORY_SEXUALLY_EXPLICIT` - `HARM_CATEGORY_CIVIC_INTEGRITY` - **threshold** _string_ The threshold of the safety setting. Can be one of the following: - `HARM_BLOCK_THRESHOLD_UNSPECIFIED` - `BLOCK_LOW_AND_ABOVE` - `BLOCK_MEDIUM_AND_ABOVE` - `BLOCK_ONLY_HIGH` - `BLOCK_NONE` - `OFF` - **responseModalities** _string[]_ The modalities to use for the response. The following modalities are supported: `TEXT`, `IMAGE`. When not defined or empty, the model defaults to returning only text. - **thinkingConfig** _\{ thinkingLevel?: 'minimal' | 'low' | 'medium' | 'high'; thinkingBudget?: number; includeThoughts?: boolean \}_ Optional. Configuration for the model's thinking process. Only supported by specific [Google models](https://ai.google.dev/gemini-api/docs/thinking). - **thinkingLevel** _'minimal' | 'low' | 'medium' | 'high'_ Optional. Controls the thinking depth for Gemini 3 models. Gemini 3.1 Pro supports 'low', 'medium', and 'high', Gemini 3 Pro supports 'low' and 'high', while Gemini 3 Flash supports all four levels: 'minimal', 'low', 'medium', and 'high'. Only supported by Gemini 3 models. - **thinkingBudget** _number_ Optional. Gives the model guidance on the number of thinking tokens it can use when generating a response. Setting it to 0 disables thinking, if the model supports it. For more information about the possible value ranges for each model see [Google thinking documentation](https://ai.google.dev/gemini-api/docs/thinking#set-budget). This option is for Gemini 2.5 models. Gemini 3 models should use `thinkingLevel` instead. - **includeThoughts** _boolean_ Optional. If set to true, thought summaries are returned, which are synthesized versions of the model's raw thoughts and offer insights into the model's internal reasoning process. - **imageConfig** _\{ aspectRatio?: string, imageSize?: string \}_ Optional. Configuration for the models image generation. Only supported by specific [Google models](https://ai.google.dev/gemini-api/docs/image-generation). - **aspectRatio** _string_ Model defaults to generate 1:1 squares, or to matching the output image size to that of your input image. Can be one of the following: - 1:1 - 2:3 - 3:2 - 3:4 - 4:3 - 4:5 - 5:4 - 9:16 - 16:9 - 21:9 - **imageSize** _string_ Controls the output image resolution. Defaults to 1K. Can be one of the following: - 1K - 2K - 4K - **audioTimestamp** _boolean_ Optional. Enables timestamp understanding for audio-only files. See [Google Cloud audio understanding documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/audio-understanding). - **mediaResolution** _string_ Optional. If specified, the media resolution specified will be used. Can be one of the following: - `MEDIA_RESOLUTION_UNSPECIFIED` - `MEDIA_RESOLUTION_LOW` - `MEDIA_RESOLUTION_MEDIUM` - `MEDIA_RESOLUTION_HIGH` See [Google API MediaResolution documentation](https://ai.google.dev/api/generate-content#MediaResolution). - **labels** _Record<string, string>_ Optional. Defines labels used in billing reports. Available on Vertex AI only. See [Google Cloud labels documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/add-labels-to-api-calls). - **serviceTier** _'standard' | 'flex' | 'priority'_ Optional. The service tier to use for the request. Set to `'flex'` for 50% cheaper processing at the cost of increased latency. Set to `'priority'` for ultra-low latency at a 75-100% price premium over `'standard'`. Because Priority can be gracefully downgraded to Standard under load, the tier the request actually ran on is surfaced on `result.providerMetadata.google.serviceTier`. See [Priority inference](https://ai.google.dev/gemini-api/docs/priority-inference) and [Flex inference](https://ai.google.dev/gemini-api/docs/flex-inference). - **threshold** _string_ Optional. Standalone threshold setting that can be used independently of `safetySettings`. Uses the same values as the `safetySettings` threshold. ### Thinking The Gemini 2.5 and Gemini 3 series models use an internal "thinking process" that significantly improves their reasoning and multi-step planning abilities, making them highly effective for complex tasks such as coding, advanced mathematics, and data analysis. For more information see [Google thinking documentation](https://ai.google.dev/gemini-api/docs/thinking). #### Gemini 3 Models For Gemini 3 models, use the `thinkingLevel` parameter to control the depth of reasoning: ```ts import { google, GoogleLanguageModelOptions } from '@ai-sdk/google'; import { generateText } from 'ai'; const model = google('gemini-3.1-pro-preview'); const { text, reasoning } = await generateText({ model: model, prompt: 'What is the sum of the first 10 prime numbers?', providerOptions: { google: { thinkingConfig: { thinkingLevel: 'high', includeThoughts: true, }, } satisfies GoogleLanguageModelOptions, }, }); console.log(text); console.log(reasoning); // Reasoning summary ``` #### Gemini 2.5 Models For Gemini 2.5 models, use the `thinkingBudget` parameter to control the number of thinking tokens: ```ts import { google, GoogleLanguageModelOptions } from '@ai-sdk/google'; import { generateText } from 'ai'; const model = google('gemini-2.5-flash'); const { text, reasoning } = await generateText({ model: model, prompt: 'What is the sum of the first 10 prime numbers?', providerOptions: { google: { thinkingConfig: { thinkingBudget: 8192, includeThoughts: true, }, } satisfies GoogleLanguageModelOptions, }, }); console.log(text); console.log(reasoning); // Reasoning summary ``` ### File Inputs The Google provider supports file inputs, e.g. PDF files. ```ts import { google } from '@ai-sdk/google'; import { generateText } from 'ai'; const result = await generateText({ model: google('gemini-2.5-flash'), messages: [ { role: 'user', content: [ { type: 'text', text: 'What is an embedding model according to this document?', }, { type: 'file', data: fs.readFileSync('./data/ai.pdf'), mediaType: 'application/pdf', }, ], }, ], }); ``` You can also use YouTube URLs directly: ```ts import { google } from '@ai-sdk/google'; import { generateText } from 'ai'; const result = await generateText({ model: google('gemini-2.5-flash'), messages: [ { role: 'user', content: [ { type: 'text', text: 'Summarize this video', }, { type: 'file', data: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ', mediaType: 'video/mp4', }, ], }, ], }); ``` The AI SDK will automatically download URLs if you pass them as data, except for `https://generativelanguage.googleapis.com/v1beta/files/` and YouTube URLs. You can use the Google Generative AI Files API to upload larger files to that location. YouTube URLs (public or unlisted videos) are supported directly - you can specify one YouTube video URL per request. See [File Parts](/docs/foundations/prompts#file-parts) for details on how to use files in prompts. ### Cached Content Google supports both explicit and implicit caching to help reduce costs on repetitive content. #### Implicit Caching Gemini 2.5 models automatically provide cache cost savings without needing to create an explicit cache. When you send requests that share common prefixes with previous requests, you'll receive a 75% token discount on cached content. To maximize cache hits with implicit caching: - Keep content at the beginning of requests consistent - Add variable content (like user questions) at the end of prompts - Ensure requests meet minimum token requirements: - Gemini 2.5 Flash: 1024 tokens minimum - Gemini 2.5 Pro: 2048 tokens minimum ```ts import { google } from '@ai-sdk/google'; import { generateText } from 'ai'; // Structure prompts with consistent content at the beginning const baseContext = 'You are a cooking assistant with expertise in Italian cuisine. Here are 1000 lasagna recipes for reference...'; const { text: veggieLasagna } = await generateText({ model: google('gemini-2.5-pro'), prompt: `${baseContext}\n\nWrite a vegetarian lasagna recipe for 4 people.`, }); // Second request with same prefix - eligible for cache hit const { text: meatLasagna, providerMetadata } = await generateText({ model: google('gemini-2.5-pro'), prompt: `${baseContext}\n\nWrite a meat lasagna recipe for 12 people.`, }); // Check cached token count in usage metadata console.log('Cached tokens:', providerMetadata.google); // e.g. // { // groundingMetadata: null, // safetyRatings: null, // usageMetadata: { // cachedContentTokenCount: 2027, // thoughtsTokenCount: 702, // promptTokenCount: 2152, // candidatesTokenCount: 710, // totalTokenCount: 3564 // } // } ``` Usage metadata was added to `providerMetadata` in `@ai-sdk/google@1.2.23`. If you are using an older version, usage metadata is available in the raw HTTP `response` body returned as part of the return value from `generateText`. #### Explicit Caching For guaranteed cost savings, you can still use explicit caching with Gemini 2.5 and 2.0 models. See the [models page](https://ai.google.dev/gemini-api/docs/models) to check if caching is supported for the used model: ```ts import { google, type GoogleLanguageModelOptions } from '@ai-sdk/google'; import { GoogleGenAI } from '@google/genai'; import { generateText } from 'ai'; const ai = new GoogleGenAI({ apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY, }); const model = 'gemini-2.5-pro'; // Create a cache with the content you want to reuse const cache = await ai.caches.create({ model, config: { contents: [ { role: 'user', parts: [{ text: '1000 Lasagna Recipes...' }], }, ], ttl: '300s', // Cache expires after 5 minutes }, }); const { text: veggieLasagnaRecipe } = await generateText({ model: google(model), prompt: 'Write a vegetarian lasagna recipe for 4 people.', providerOptions: { google: { cachedContent: cache.name, } satisfies GoogleLanguageModelOptions, }, }); const { text: meatLasagnaRecipe } = await generateText({ model: google(model), prompt: 'Write a meat lasagna recipe for 12 people.', providerOptions: { google: { cachedContent: cache.name, } satisfies GoogleLanguageModelOptions, }, }); ``` ### Code Execution With [Code Execution](https://ai.google.dev/gemini-api/docs/code-execution), certain models can generate and execute Python code to perform calculations, solve problems, or provide more accurate information. You can enable code execution by adding the `code_execution` tool to your request. ```ts import { google } from '@ai-sdk/google'; import { googleTools } from '@ai-sdk/google/internal'; import { generateText } from 'ai'; const { text, toolCalls, toolResults } = await generateText({ model: google('gemini-2.5-pro'), tools: { code_execution: google.tools.codeExecution({}) }, prompt: 'Use python to calculate the 20th fibonacci number.', }); ``` The response will contain the tool calls and results from the code execution. ### Google Search With [Google Search grounding](https://ai.google.dev/gemini-api/docs/google-search), the model has access to the latest information using Google Search. ```ts highlight="8,17-20" import { google } from '@ai-sdk/google'; import { GoogleProviderMetadata } from '@ai-sdk/google'; import { generateText } from 'ai'; const { text, sources, providerMetadata } = await generateText({ model: google('gemini-2.5-flash'), tools: { google_search: google.tools.googleSearch({}), }, prompt: 'List the top 5 San Francisco news from the past week.' + 'You must include the date of each article.', }); // access the grounding metadata. Casting to the provider metadata type // is optional but provides autocomplete and type safety. const metadata = providerMetadata?.google as GoogleProviderMetadata | undefined; const groundingMetadata = metadata?.groundingMetadata; const safetyRatings = metadata?.safetyRatings; ``` The `googleSearch` tool accepts the following optional configuration options: - **searchTypes** _object_ Enables specific search types. Both can be combined. - `webSearch`: Enable web search grounding (pass `{}` to enable). This is the default. - `imageSearch`: Enable [image search grounding](https://ai.google.dev/gemini-api/docs/image-generation#image-search) (pass `{}` to enable). - **timeRangeFilter** _object_ Restricts search results to a specific time range. Both `startTime` and `endTime` are required. - `startTime`: Start time in ISO 8601 format (e.g. `'2025-01-01T00:00:00Z'`). - `endTime`: End time in ISO 8601 format (e.g. `'2025-12-31T23:59:59Z'`). ```ts google.tools.googleSearch({ searchTypes: { webSearch: {} }, timeRangeFilter: { startTime: '2025-01-01T00:00:00Z', endTime: '2025-12-31T23:59:59Z', }, }); ``` When Google Search grounding is enabled, the model will include sources in the response. Additionally, the grounding metadata includes detailed information about how search results were used to ground the model's response. Here are the available fields: - **`webSearchQueries`** (`string[] | null`) - Array of search queries used to retrieve information - Example: `["What's the weather in Chicago this weekend?"]` - **`searchEntryPoint`** (`{ renderedContent: string } | null`) - Contains the main search result content used as an entry point - The `renderedContent` field contains the formatted content - **`groundingSupports`** (Array of support objects | null) - Contains details about how specific response parts are supported by search results - Each support object includes: - **`segment`**: Information about the grounded text segment - `text`: The actual text segment - `startIndex`: Starting position in the response - `endIndex`: Ending position in the response - **`groundingChunkIndices`**: References to supporting search result chunks - **`confidenceScores`**: Confidence scores (0-1) for each supporting chunk Example response: ```json { "groundingMetadata": { "webSearchQueries": ["What's the weather in Chicago this weekend?"], "searchEntryPoint": { "renderedContent": "..." }, "groundingSupports": [ { "segment": { "startIndex": 0, "endIndex": 65, "text": "Chicago weather changes rapidly, so layers let you adjust easily." }, "groundingChunkIndices": [0], "confidenceScores": [0.99] } ] } } ``` ### Enterprise Web Search With [Enterprise Web Search](https://cloud.google.com/vertex-ai/generative-ai/docs/grounding/web-grounding-enterprise), the model has access to a compliance-focused web index designed for highly-regulated industries such as finance, healthcare, and public sector. Enterprise Web Search is only available on Vertex AI. You must use the Google Vertex provider (`@ai-sdk/google-vertex`) instead of the standard Google provider (`@ai-sdk/google`) to use this feature. Requires Gemini 2.0 or newer models. ```ts import { createGoogleVertex } from '@ai-sdk/google-vertex'; import { generateText } from 'ai'; const vertex = createGoogleVertex({ project: 'my-project', location: 'us-central1', }); const { text, sources, providerMetadata } = await generateText({ model: vertex('gemini-2.5-flash'), tools: { enterprise_web_search: vertex.tools.enterpriseWebSearch({}), }, prompt: 'What are the latest regulatory updates for financial services?', }); ``` Enterprise Web Search provides the following benefits: - Does not log customer data - Supports VPC service controls - Compliance-focused web index for regulated industries ### File Search The [File Search tool](https://ai.google.dev/gemini-api/docs/file-search) lets Gemini retrieve context from your own documents that you have indexed in File Search stores. Only Gemini 2.5 and Gemini 3 models support this feature. ```ts highlight="9-13" import { google } from '@ai-sdk/google'; import { generateText } from 'ai'; const { text, sources } = await generateText({ model: google('gemini-2.5-pro'), tools: { file_search: google.tools.fileSearch({ fileSearchStoreNames: [ 'projects/my-project/locations/us/fileSearchStores/my-store', ], metadataFilter: 'author = "Robert Graves"', topK: 8, }), }, prompt: "Summarise the key themes of 'I, Claudius'.", }); ``` File Search responses include citations via the normal `sources` field and expose raw [grounding metadata](#google-search) in `providerMetadata.google.groundingMetadata`. ### URL Context Google provides a provider-defined URL context tool. The URL context tool allows you to provide specific URLs that you want the model to analyze directly in from the prompt. ```ts highlight="9,13-17" import { google } from '@ai-sdk/google'; import { generateText } from 'ai'; const { text, sources, providerMetadata } = await generateText({ model: google('gemini-2.5-flash'), prompt: `Based on the document: https://ai.google.dev/gemini-api/docs/url-context. Answer this question: How many links we can consume in one request?`, tools: { url_context: google.tools.urlContext({}), }, }); const metadata = providerMetadata?.google as GoogleProviderMetadata | undefined; const groundingMetadata = metadata?.groundingMetadata; const urlContextMetadata = metadata?.urlContextMetadata; ``` The URL context metadata includes detailed information about how the model used the URL context to generate the response. Here are the available fields: - **`urlMetadata`** (`{ retrievedUrl: string; urlRetrievalStatus: string; }[] | null`) - Array of URL context metadata - Each object includes: - **`retrievedUrl`**: The URL of the context - **`urlRetrievalStatus`**: The status of the URL retrieval Example response: ```json { "urlMetadata": [ { "retrievedUrl": "https://ai-sdk.dev/providers/ai-sdk-providers/google", "urlRetrievalStatus": "URL_RETRIEVAL_STATUS_SUCCESS" } ] } ``` With the URL context tool, you will also get the `groundingMetadata`. ```json "groundingMetadata": { "groundingChunks": [ { "web": { "uri": "https://ai-sdk.dev/providers/ai-sdk-providers/google", "title": "Google - AI SDK Providers" } } ], "groundingSupports": [ { "segment": { "startIndex": 67, "endIndex": 157, "text": "**Installation**: Install the `@ai-sdk/google` module using your preferred package manager" }, "groundingChunkIndices": [ 0 ] }, ] } ``` You can add up to 20 URLs per request. The URL context tool is only supported for Gemini 2.0 Flash models and above. Check the [supported models for URL context tool](https://ai.google.dev/gemini-api/docs/url-context#supported-models). #### Combine URL Context with Search Grounding You can combine the URL context tool with search grounding to provide the model with the latest information from the web. ```ts highlight="9-10" import { google } from '@ai-sdk/google'; import { generateText } from 'ai'; const { text, sources, providerMetadata } = await generateText({ model: google('gemini-2.5-flash'), prompt: `Based on this context: https://ai-sdk.dev/providers/ai-sdk-providers/google, tell me how to use Gemini with AI SDK. Also, provide the latest news about AI SDK V5.`, tools: { google_search: google.tools.googleSearch({}), url_context: google.tools.urlContext({}), }, }); const metadata = providerMetadata?.google as GoogleProviderMetadata | undefined; const groundingMetadata = metadata?.groundingMetadata; const urlContextMetadata = metadata?.urlContextMetadata; ``` ### Google Maps Grounding With [Google Maps grounding](https://ai.google.dev/gemini-api/docs/maps-grounding), the model has access to Google Maps data for location-aware responses. This enables providing local data and geospatial context, such as finding nearby restaurants. ```ts highlight="7-16" import { google, type GoogleLanguageModelOptions } from '@ai-sdk/google'; import { GoogleProviderMetadata } from '@ai-sdk/google'; import { generateText } from 'ai'; const { text, sources, providerMetadata } = await generateText({ model: google('gemini-2.5-flash'), tools: { google_maps: google.tools.googleMaps({}), }, providerOptions: { google: { retrievalConfig: { latLng: { latitude: 34.090199, longitude: -117.881081 }, }, } satisfies GoogleLanguageModelOptions, }, prompt: 'What are the best Italian restaurants within a 15-minute walk from here?', }); const metadata = providerMetadata?.google as GoogleProviderMetadata | undefined; const groundingMetadata = metadata?.groundingMetadata; ``` The optional `retrievalConfig.latLng` provider option provides location context for queries about nearby places. This configuration applies to any grounding tools that support location context, including Google Maps and Google Search. When Google Maps grounding is enabled, the model's response will include sources pointing to Google Maps URLs. The grounding metadata includes `maps` chunks with place information: ```json { "groundingMetadata": { "groundingChunks": [ { "maps": { "uri": "https://maps.google.com/?cid=12345", "title": "Restaurant Name", "placeId": "places/ChIJ..." } } ] } } ``` Google Maps grounding is supported on Gemini 2.0 and newer models. ### RAG Engine Grounding With [RAG Engine Grounding](https://cloud.google.com/vertex-ai/generative-ai/docs/rag-engine/use-vertexai-search#generate-content-using-gemini-api), the model has access to your custom knowledge base using the Vertex RAG Engine. This enables the model to provide answers based on your specific data sources and documents. RAG Engine Grounding is only supported with Vertex Gemini models. You must use the Google Vertex provider (`@ai-sdk/google-vertex`) instead of the standard Google provider (`@ai-sdk/google`) to use this feature. ```ts highlight="8,17-20" import { createGoogleVertex } from '@ai-sdk/google-vertex'; import { GoogleProviderMetadata } from '@ai-sdk/google'; import { generateText } from 'ai'; const vertex = createGoogleVertex({ project: 'my-project', location: 'us-central1', }); const { text, sources, providerMetadata } = await generateText({ model: vertex('gemini-2.5-flash'), tools: { vertex_rag_store: vertex.tools.vertexRagStore({ ragCorpus: 'projects/my-project/locations/us-central1/ragCorpora/my-rag-corpus', topK: 5, }), }, prompt: 'What are the key features of our product according to our documentation?', }); // access the grounding metadata. Casting to the provider metadata type // is optional but provides autocomplete and type safety. const metadata = providerMetadata?.google as GoogleProviderMetadata | undefined; const groundingMetadata = metadata?.groundingMetadata; const safetyRatings = metadata?.safetyRatings; ``` When RAG Engine Grounding is enabled, the model will include sources from your RAG corpus in the response. Additionally, the grounding metadata includes detailed information about how RAG results were used to ground the model's response. Here are the available fields: - **`groundingChunks`** (Array of chunk objects | null) - Contains the retrieved context chunks from your RAG corpus - Each chunk includes: - **`retrievedContext`**: Information about the retrieved context - `uri`: The URI or identifier of the source document - `title`: The title of the source document (optional) - `text`: The actual text content of the chunk - **`groundingSupports`** (Array of support objects | null) - Contains details about how specific response parts are supported by RAG results - Each support object includes: - **`segment`**: Information about the grounded text segment - `text`: The actual text segment - `startIndex`: Starting position in the response - `endIndex`: Ending position in the response - **`groundingChunkIndices`**: References to supporting RAG result chunks - **`confidenceScores`**: Confidence scores (0-1) for each supporting chunk Example response: ```json { "groundingMetadata": { "groundingChunks": [ { "retrievedContext": { "uri": "gs://my-bucket/docs/product-guide.pdf", "title": "Product User Guide", "text": "Our product includes advanced AI capabilities, real-time processing, and enterprise-grade security features." } } ], "groundingSupports": [ { "segment": { "startIndex": 0, "endIndex": 45, "text": "Our product includes advanced AI capabilities and real-time processing." }, "groundingChunkIndices": [0], "confidenceScores": [0.95] } ] } } ``` #### Configuration Options The `vertexRagStore` tool accepts the following configuration options: - **`ragCorpus`** (`string`, required) - The RagCorpus resource name in the format: `projects/{project}/locations/{location}/ragCorpora/{rag_corpus}` - This identifies your specific RAG corpus to search against - **`topK`** (`number`, optional) - The number of top contexts to retrieve from your RAG corpus - Defaults to the corpus configuration if not specified ### 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. ```ts import { google } from '@ai-sdk/google'; import { generateText } from 'ai'; const result = await generateText({ model: google('gemini-2.5-flash-image'), prompt: 'Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme', }); for (const file of result.files) { if (file.mediaType.startsWith('image/')) { console.log('Generated image:', file); } } ``` If you primarily want to generate images without text output, you can also use Gemini image models with the `generateImage()` function. See [Gemini Image Models](#gemini-image-models) for details. ### Safety Ratings The safety ratings provide insight into the safety of the model's response. See [Google AI documentation on safety settings](https://ai.google.dev/gemini-api/docs/safety-settings). Example response excerpt: ```json { "safetyRatings": [ { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE", "probabilityScore": 0.11027937, "severity": "HARM_SEVERITY_LOW", "severityScore": 0.28487435 }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "HIGH", "blocked": true, "probabilityScore": 0.95422274, "severity": "HARM_SEVERITY_MEDIUM", "severityScore": 0.43398145 }, { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE", "probabilityScore": 0.11085559, "severity": "HARM_SEVERITY_NEGLIGIBLE", "severityScore": 0.19027223 }, { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE", "probabilityScore": 0.22901751, "severity": "HARM_SEVERITY_NEGLIGIBLE", "severityScore": 0.09089675 } ] } ``` ### Troubleshooting #### Schema Limitations The Google Generative AI API uses a subset of the OpenAPI 3.0 schema, which does not support features such as unions. The errors that you get in this case look like this: `GenerateContentRequest.generation_config.response_schema.properties[occupation].type: must be specified` By default, structured outputs are enabled (and for tool calling they are required). You can disable structured outputs for object generation as a workaround: ```ts highlight="3,8" const { output } = await generateText({ model: google('gemini-2.5-flash'), providerOptions: { google: { structuredOutputs: false, } satisfies GoogleLanguageModelOptions, }, output: Output.object({ schema: z.object({ name: z.string(), age: z.number(), contact: z.union([ z.object({ type: z.literal('email'), value: z.string(), }), z.object({ type: z.literal('phone'), value: z.string(), }), ]), }), }), prompt: 'Generate an example person for testing.', }); ``` The following Zod features are known to not work with Google: - `z.union` - `z.record` ### Model Capabilities | Model | Image Input | Object Generation | Tool Usage | Tool Streaming | Google Search | URL Context | | ------------------------------------- | ------------------- | ------------------- | ------------------- | ------------------- | ------------------- | ------------------- | | `gemini-3.5-flash` | | | | | | | | `gemini-3.1-pro-preview` | | | | | | | | `gemini-3.1-flash-image-preview` | | | | | | | | `gemini-3.1-flash-lite-preview` | | | | | | | | `gemini-3-pro-preview` | | | | | | | | `gemini-3-pro-image-preview` | | | | | | | | `gemini-3-flash-preview` | | | | | | | | `gemini-2.5-pro` | | | | | | | | `gemini-2.5-flash` | | | | | | | | `gemini-2.5-flash-lite` | | | | | | | | `gemini-2.5-flash-lite-preview-06-17` | | | | | | | | `gemini-2.0-flash` | | | | | | | The table above lists popular models. Please see the [Google Generative AI docs](https://ai.google.dev/gemini-api/docs/models/) for a full list of available models. The table above lists popular models. You can also pass any available provider model ID as a string if needed. ## Interactions API The [Gemini Interactions API](https://ai.google.dev/gemini-api/docs/interactions) (`POST /v1beta/interactions`) is a separate Google endpoint with server-side state, unified content blocks, first-class built-in tools, agent presets, managed agents that run in a sandboxed Linux environment, and native multimodal image output. It is reached via the `google.interactions(...)` factory: ```ts import { google } from '@ai-sdk/google'; import { generateText } from 'ai'; const { text } = await generateText({ model: google.interactions('gemini-2.5-flash'), prompt: 'Hello, how are you?', }); ``` `google.interactions(...)` accepts a model ID string (e.g. `'gemini-2.5-flash'`, `'gemini-3-pro-preview'`), `{ agent: }` to use a Gemini [agent preset](#agent-presets), or `{ managedAgent: }` to invoke a [managed agent](#managed-agents) you created on Google's side. The returned model can be passed to `generateText` and `streamText` like any other AI SDK language model. Use `google(...)` for the standard `:generateContent` / `:streamGenerateContent` endpoints, and `google.interactions(...)` for the new Interactions endpoint. Pick one per model instance — they target different request bodies and SSE event vocabularies. ### Provider Options The Interactions model reads its options from the shared `providerOptions.google.*` namespace. Validate them with the `GoogleLanguageModelInteractionsOptions` type: ```ts import { google, type GoogleLanguageModelInteractionsOptions, } from '@ai-sdk/google'; import { generateText } from 'ai'; await generateText({ model: google.interactions('gemini-2.5-flash'), prompt: 'What color is the sky in one word?', providerOptions: { google: { serviceTier: 'priority', } satisfies GoogleLanguageModelInteractionsOptions, }, }); ``` The following optional provider options are available: - **previousInteractionId** _string_ Server-side interaction id from a prior turn. When set, the server pulls prior context from its own state and only the new user message is sent on the wire. Pair with the default `store: true` to chain stateful conversations. See [Stateful chaining](#stateful-chaining). - **store** _boolean_ Whether the server should persist the interaction. Defaults to `true`. Set to `false` for stateless multi-turn conversations where the full message history is re-sent on every turn. - **agent** _string_ Name of a Gemini agent preset (e.g. `'deep-research-pro-preview-12-2025'`). Prefer the factory form `google.interactions({ agent: '...' })` over setting `agent` in provider options — the factory is type-checked against the supported agent names. - **agentConfig** _object_ Per-agent configuration. Currently supports `{ type: 'dynamic' }` and `{ type: 'deep-research', thinkingSummaries?, visualization?, collaborativePlanning? }`. - **thinkingLevel** _'minimal' | 'low' | 'medium' | 'high'_ Controls reasoning depth for thinking-enabled models. Mapped onto the Interactions request's `thinking_level`. - **thinkingSummaries** _'auto' | 'none'_ Whether the model returns synthesized thought summaries on reasoning parts. Defaults to the API default. - **responseFormat** _Array\<\{ type: 'text' | 'image' | 'audio'; mimeType?: string; schema?: unknown; aspectRatio?: string; imageSize?: '1K' \| '2K' \| '4K' \| '512' \}\>_ Output-format entries that map directly to the API's `response_format` array. Use this for fine-grained control over image, audio, or non-JSON text outputs (e.g. `aspectRatio` and `imageSize` for image generation). The AI SDK call-level `responseFormat: { type: 'json', schema }` still drives JSON-mode automatically and prepends a matching text entry; entries listed here are appended. `aspectRatio` accepts `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`, `1:8`, `8:1`, `1:4`, `4:1`. - **imageConfig** _\{ aspectRatio?: string; imageSize?: '1K' | '2K' | '4K' | '512' \}_ (deprecated) Use **responseFormat** with a `{ type: 'image', ... }` entry instead. Retained for backwards compatibility; the SDK translates `imageConfig` into a matching `response_format` image entry and emits a warning when set. Ignored when `responseFormat` already supplies an image entry. - **mediaResolution** _'low' | 'medium' | 'high' | 'ultra_high'_ Media resolution applied to image inputs / outputs. - **serviceTier** _'flex' | 'standard' | 'priority'_ Service tier for the request. Mirrored back on `result.providerMetadata.google.serviceTier` for observability. - **systemInstruction** _string_ Alternative to the AI SDK `system` message. If both are set, the AI SDK `system` message wins and a warning is emitted. - **background** _boolean_ Run the interaction in the background. Required for agents whose server-side workflow cannot complete within a single request/response; rejected by agents that only support synchronous calls. When `true`, the POST returns a non-terminal status and the SDK polls `GET /interactions/{id}` until the work completes. - **environment** _string \| object_ Sandbox environment configuration for [managed agents](#managed-agents). Pass `'remote'` to provision a fresh sandbox, an `environment_id` string to reuse an existing one, or an object of the form `{ type: 'remote', sources?, network? }` to preload files and/or constrain outbound traffic. Only applies to agent calls. - **pollingTimeoutMs** _number_ Maximum time, in milliseconds, to poll a background interaction before giving up. Defaults to 30 minutes (1,800,000 ms). Long-running agents may need longer. ### Provider Metadata `result.providerMetadata.google` (typed via `GoogleInteractionsProviderMetadata`) exposes: - **interactionId** _string_ Server-side interaction id. Pass this back as `previousInteractionId` on the next turn to chain. - **serviceTier** _string_ Service tier the request actually ran on. - **signature** _string_ Per-block signature hash, set by the SDK on output reasoning and tool-call parts. Round-tripped automatically on the next turn. ### Stateful chaining With the default `store: true`, the server retains the prior turn so the next request only needs to send the new user message and the `previousInteractionId`: ```ts import { google, type GoogleLanguageModelInteractionsOptions, } from '@ai-sdk/google'; import { generateText } from 'ai'; const turn1 = await generateText({ model: google.interactions('gemini-2.5-flash'), prompt: 'What are the three largest cities in Spain?', }); const interactionId = turn1.providerMetadata?.google?.interactionId as | string | undefined; const turn2 = await generateText({ model: google.interactions('gemini-2.5-flash'), prompt: 'What is the most famous landmark in the second one?', providerOptions: { google: { previousInteractionId: interactionId, } satisfies GoogleLanguageModelInteractionsOptions, }, }); ``` For stateless multi-turn conversations, set `store: false` and re-send the full message history on every turn (no `previousInteractionId`): ```ts import { google, type GoogleLanguageModelInteractionsOptions, } from '@ai-sdk/google'; import { generateText, type ModelMessage } from 'ai'; const messages: Array = [ { role: 'user', content: 'What are the three largest cities in Spain?' }, ]; const turn1 = await generateText({ model: google.interactions('gemini-2.5-flash'), messages, providerOptions: { google: { store: false } satisfies GoogleLanguageModelInteractionsOptions, }, }); messages.push(...turn1.responseMessages); messages.push({ role: 'user', content: 'What is the most famous landmark in the second one?', }); const turn2 = await generateText({ model: google.interactions('gemini-2.5-flash'), messages, providerOptions: { google: { store: false } satisfies GoogleLanguageModelInteractionsOptions, }, }); ``` ### Built-in Tools The Interactions API ships a built-in tool catalog. The provider-defined tools under `google.tools.*` map onto Interactions tool descriptors: | AI SDK tool | Interactions tool type | Notes | | ------------------------------------- | ---------------------- | ----------------------------------------- | | `google.tools.googleSearch` | `google_search` | Web / image search grounding. | | `google.tools.codeExecution` | `code_execution` | Server-side Python execution. | | `google.tools.urlContext` | `url_context` | Fetch URLs referenced in the prompt. | | `google.tools.fileSearch` | `file_search` | Retrieval from File Search stores. | | `google.tools.googleMaps` | `google_maps` | Maps grounding for nearby-places queries. | | _provider tool_ `google.computer_use` | `computer_use` | Computer use (browser environment). | | _provider tool_ `google.mcp_server` | `mcp_server` | Remote MCP server passthrough. | | _provider tool_ `google.retrieval` | `retrieval` | Vertex AI Search retrieval. | Function tools (`type: 'function'`) defined with the AI SDK `tool(...)` helper are translated to Interactions `function` tool descriptors. Other tool kinds emit a warning and are dropped. ```ts import { google } from '@ai-sdk/google'; import { generateText } from 'ai'; const { text, sources } = await generateText({ model: google.interactions('gemini-2.5-flash'), tools: { google_search: google.tools.googleSearch({}), }, prompt: "What's a notable AI development from this past week? " + 'Include the date for each item you mention.', }); ``` Function tools work the same way as on the standard provider: ```ts import { google } from '@ai-sdk/google'; import { generateText, stepCountIs, tool } from 'ai'; import { z } from 'zod'; const weatherTool = tool({ description: 'Get the weather for a city.', inputSchema: z.object({ city: z.string() }), execute: async ({ city }) => `It is sunny in ${city}.`, }); const { text, toolCalls } = await generateText({ model: google.interactions('gemini-2.5-flash'), tools: { getWeather: weatherTool }, stopWhen: stepCountIs(5), prompt: 'What is the weather in San Francisco right now?', }); ``` ### Image output via Interactions Add a `{ type: 'image' }` entry to `responseFormat` on a Gemini image-capable model to get images as `LanguageModelV4FilePart` files in the response. No tool wrapping is required, and the entry doubles as the place to set `aspectRatio`, `imageSize`, and `mimeType`. ```ts import { google, type GoogleLanguageModelInteractionsOptions, } from '@ai-sdk/google'; import { generateText } from 'ai'; const result = await generateText({ model: google.interactions('gemini-3-pro-image-preview'), prompt: 'Generate an image of a comic cat in a spaceship.', providerOptions: { google: { responseFormat: [{ type: 'image' }], } satisfies GoogleLanguageModelInteractionsOptions, }, }); for (const file of result.files) { if (file.mediaType.startsWith('image/')) { // file.uint8Array | file.base64 | file.mediaType } } ``` To control aspect ratio, image size, or output mime type, add those fields to the same image entry: ```ts import { google, type GoogleLanguageModelInteractionsOptions, } from '@ai-sdk/google'; import { generateText } from 'ai'; const result = await generateText({ model: google.interactions('gemini-3-pro-image-preview'), prompt: 'Generate a high-quality landscape photo of mountains at sunset.', providerOptions: { google: { responseFormat: [ { type: 'image', aspectRatio: '16:9', imageSize: '4K', }, ], } satisfies GoogleLanguageModelInteractionsOptions, }, }); ``` For multimodal output, list one entry per modality. The model returns text in `result.text` and the accompanying image(s) in `result.files`: ```ts import { google, type GoogleLanguageModelInteractionsOptions, } from '@ai-sdk/google'; import { generateText } from 'ai'; const result = await generateText({ model: google.interactions('gemini-2.5-flash-image'), prompt: 'Tell me a three sentence bedtime story about a unicorn, accompanied by a suitable illustration.', providerOptions: { google: { responseFormat: [ { type: 'text' }, { type: 'image', aspectRatio: '16:9' }, ], } satisfies GoogleLanguageModelInteractionsOptions, }, }); console.log(result.text); const images = result.files.filter(file => file.mediaType.startsWith('image/')); // images[0].uint8Array | images[0].base64 | images[0].mediaType ``` Iterative image editing pairs naturally with stateful chaining — keep `previousInteractionId` set across turns and the model edits its prior output: ```ts import { google, type GoogleLanguageModelInteractionsOptions, } from '@ai-sdk/google'; import { generateText } from 'ai'; const model = google.interactions('gemini-3-pro-image-preview'); const turn1 = await generateText({ model, prompt: 'Generate an image of a comic cat in a spaceship.', providerOptions: { google: { responseFormat: [{ type: 'image' }], } satisfies GoogleLanguageModelInteractionsOptions, }, }); const interactionId = turn1.providerMetadata?.google?.interactionId as | string | undefined; const turn2 = await generateText({ model, prompt: 'now make the cat red', providerOptions: { google: { responseFormat: [{ type: 'image' }], previousInteractionId: interactionId, } satisfies GoogleLanguageModelInteractionsOptions, }, }); ``` ### Agent presets Pass `{ agent: }` to target a Gemini agent preset. The factory type-checks the agent name against the supported set: ```ts import { google, type GoogleLanguageModelInteractionsOptions, } from '@ai-sdk/google'; import { generateText } from 'ai'; const result = await generateText({ model: google.interactions({ agent: 'deep-research-pro-preview-12-2025', }), prompt: 'Briefly summarize the most-cited papers on retrieval-augmented generation since 2024 (2-3 sentences).', providerOptions: { google: { background: true, } satisfies GoogleLanguageModelInteractionsOptions, }, }); ``` Whether an agent runs synchronously or in the background depends on the agent. Long-running presets (such as the `deep-research-*` family) require `background: true` — the POST returns a non-terminal status and the SDK polls `GET /interactions/{id}` internally until the interaction completes. Other agents accept synchronous calls only and will reject `background: true`. Set the flag explicitly via `providerOptions.google.background`. The default polling timeout is 30 minutes; raise it via `pollingTimeoutMs` for slower agents: ```ts import { google, type GoogleLanguageModelInteractionsOptions, } from '@ai-sdk/google'; import { generateText } from 'ai'; await generateText({ model: google.interactions({ agent: 'deep-research-max-preview-04-2026' }), prompt: 'Produce a long-form research brief on ...', providerOptions: { google: { background: true, pollingTimeoutMs: 60 * 60 * 1000, // 1 hour } satisfies GoogleLanguageModelInteractionsOptions, }, }); ``` Agents also chain through `previousInteractionId` like model-id calls. ### Managed Agents [Managed agents](https://ai.google.dev/gemini-api/docs/agents) run inside a sandboxed Linux environment provisioned per interaction. Pass the `environment` provider option to control how the sandbox is set up; the option is only accepted on agent calls. The simplest form provisions a fresh sandbox: ```ts import { google, type GoogleLanguageModelInteractionsOptions, } from '@ai-sdk/google'; import { generateText } from 'ai'; const result = await generateText({ model: google.interactions({ agent: 'antigravity-preview-05-2026' }), prompt: 'What is 2 + 2?', providerOptions: { google: { environment: 'remote', } satisfies GoogleLanguageModelInteractionsOptions, }, }); ``` `environment` accepts three shapes: - `'remote'` — provision a fresh sandbox for this call. - any other string — an `environment_id` to reuse, forking the previous sandbox so its filesystem and installed packages persist. - an object — provision a fresh sandbox and optionally preload `sources` and/or constrain outbound traffic via `network`: ```ts import { google, type GoogleLanguageModelInteractionsOptions, } from '@ai-sdk/google'; import { generateText } from 'ai'; await generateText({ model: google.interactions({ agent: 'antigravity-preview-05-2026' }), prompt: 'Read the file at /data/note.txt and tell me exactly what it contains.', providerOptions: { google: { environment: { type: 'remote', sources: [ { type: 'inline', content: 'hello from the AI SDK example\n', target: '/data/note.txt', }, ], }, } satisfies GoogleLanguageModelInteractionsOptions, }, }); ``` Three source types are supported: `inline` (write a string into the sandbox at `target`), `repository` (clone a git repository — pass the URL as `source`), and `gcs` (mount a Google Cloud Storage prefix). The `network` field accepts the string `'disabled'` to block all outbound traffic, or an object with an `allowlist` array whose entries each carry a `domain` plus an optional `transform` array of header objects to inject into matching requests. #### Custom managed agents For user-defined agents that you created on Google's side via the Gemini API's `/v1beta/agents` endpoint, pass the agent's name through the dedicated `managedAgent` factory shape instead of `agent` (which only accepts known preset names): ```ts import { google, type GoogleLanguageModelInteractionsOptions, } from '@ai-sdk/google'; import { generateText } from 'ai'; const result = await generateText({ model: google.interactions({ managedAgent: 'my-custom-agent' }), prompt: 'Hello!', providerOptions: { google: { environment: 'remote', } satisfies GoogleLanguageModelInteractionsOptions, }, }); ``` ### Streaming `streamText` is supported. The stream's `finish` part exposes `interactionId` on `providerMetadata.google` so callers can chain. ```ts import { google } from '@ai-sdk/google'; import { streamText } from 'ai'; const result = streamText({ model: google.interactions('gemini-2.5-flash'), prompt: 'Hello, how are you?', }); for await (const textPart of result.textStream) { process.stdout.write(textPart); } const googleMetadata = (await result.providerMetadata)?.google; console.log('Interaction id:', googleMetadata?.interactionId); ``` ## Gemma Models You can use [Gemma models](https://deepmind.google/models/gemma/) with the Google Generative AI API. The following Gemma models are available: - `gemma-3-27b-it` - `gemma-3-12b-it` Gemma models don't natively support the `systemInstruction` parameter, but the provider automatically handles system instructions by prepending them to the first user message. This allows you to use system instructions with Gemma models seamlessly: ```ts import { google } from '@ai-sdk/google'; import { generateText } from 'ai'; const { text } = await generateText({ model: google('gemma-3-27b-it'), system: 'You are a helpful assistant that responds concisely.', prompt: 'What is machine learning?', }); ``` The system instruction is automatically formatted and included in the conversation, so Gemma models can follow the guidance without any additional configuration. ## Embedding Models You can create models that call the [Google Generative AI embeddings API](https://ai.google.dev/gemini-api/docs/embeddings) using the `.embedding()` factory method. ```ts const model = google.embedding('gemini-embedding-001'); ``` The Google provider sends API calls to the right endpoint based on the type of embedding: - **Single embeddings**: When embedding a single value with `embed()`, the provider uses the single `:embedContent` endpoint, which typically has higher rate limits compared to the batch endpoint. - **Batch embeddings**: When embedding multiple values with `embedMany()` or multiple values in `embed()`, the provider uses the `:batchEmbedContents` endpoint. Google embedding models support additional settings. You can pass them as an options argument: ```ts import { google, type GoogleEmbeddingModelOptions } from '@ai-sdk/google'; import { embed } from 'ai'; const model = google.embedding('gemini-embedding-001'); const { embedding } = await embed({ model, value: 'sunny day at the beach', providerOptions: { google: { outputDimensionality: 512, // optional, number of dimensions for the embedding taskType: 'SEMANTIC_SIMILARITY', // optional, specifies the task type for generating embeddings content: [[{ text: 'additional context' }]], // optional, per-value multimodal content (only 1 here, since `value` is only a single one) } satisfies GoogleEmbeddingModelOptions, }, }); ``` When using `embedMany`, provide per-value multimodal content via the `content` option. Each entry corresponds to a value at the same index; use `null` for text-only entries: ```ts import { google, type GoogleEmbeddingModelOptions } from '@ai-sdk/google'; import { embedMany } from 'ai'; const { embeddings } = await embedMany({ model: google.embedding('gemini-embedding-2-preview'), values: ['sunny day at the beach', 'rainy afternoon in the city'], providerOptions: { google: { // content array must have the same length as values content: [ [{ inlineData: { mimeType: 'image/png', data: '' } }], // pairs with values[0] null, // text-only, pairs with values[1] ], } satisfies GoogleEmbeddingModelOptions, }, }); ``` The following optional provider options are available for Google embedding models: - **outputDimensionality**: _number_ Optional reduced dimension for the output embedding. If set, excessive values in the output embedding are truncated from the end. - **taskType**: _string_ Optional. Specifies the task type for generating embeddings. Supported task types include: - `SEMANTIC_SIMILARITY`: Optimized for text similarity. - `CLASSIFICATION`: Optimized for text classification. - `CLUSTERING`: Optimized for clustering texts based on similarity. - `RETRIEVAL_DOCUMENT`: Optimized for document retrieval. - `RETRIEVAL_QUERY`: Optimized for query-based retrieval. - `QUESTION_ANSWERING`: Optimized for answering questions. - `FACT_VERIFICATION`: Optimized for verifying factual information. - `CODE_RETRIEVAL_QUERY`: Optimized for retrieving code blocks based on natural language queries. - **content**: _array_ Optional. Per-value multimodal content parts for embedding non-text content (images, video, PDF, audio). Each entry corresponds to the embedding value at the same index — its parts are merged with the text value in the request. Use `null` for entries that are text-only. The array length must match the number of values being embedded. Each non-null entry is an array of parts, where each part can be `{ text: string }`, `{ inlineData: { mimeType: string, data: string } }` for inline base64 data, or `{ fileData: { fileUri: string, mimeType: string } }` to reference remote content via HTTP URL or Google Cloud Storage URI (`gs://...`). Supported by `gemini-embedding-2-preview`. ### Model Capabilities | Model | Default Dimensions | Custom Dimensions | Multimodal | | ---------------------------- | ------------------ | ------------------- | ------------------- | | `gemini-embedding-001` | 3072 | | | | `gemini-embedding-2` | 3072 | | | | `gemini-embedding-2-preview` | 3072 | | | ## Image Models You can create image models that call the Google Generative AI API using the `.image()` factory method. For more on image generation with the AI SDK see [generateImage()](/docs/reference/ai-sdk-core/generate-image). The Google provider supports two types of image models: - **Imagen models**: Dedicated image generation models using the `:predict` API - **Gemini image models**: Multimodal language models with image output capabilities using the `:generateContent` API ### Imagen Models [Imagen](https://ai.google.dev/gemini-api/docs/imagen) models are dedicated image generation models. ```ts import { google } from '@ai-sdk/google'; import { generateImage } from 'ai'; const { image } = await generateImage({ model: google.image('imagen-4.0-generate-001'), prompt: 'A futuristic cityscape at sunset', aspectRatio: '16:9', }); ``` Further configuration can be done using Google provider options. You can validate the provider options using the `GoogleImageModelOptions` type. ```ts import { google } from '@ai-sdk/google'; import { GoogleImageModelOptions } from '@ai-sdk/google'; import { generateImage } from 'ai'; const { image } = await generateImage({ model: google.image('imagen-4.0-generate-001'), providerOptions: { google: { personGeneration: 'dont_allow', } satisfies GoogleImageModelOptions, }, // ... }); ``` The following provider options are available for Imagen models: - **personGeneration** `allow_adult` | `allow_all` | `dont_allow` Whether to allow person generation. Defaults to `allow_adult`. Imagen models do not support the `size` parameter. Use the `aspectRatio` parameter instead. #### Imagen Model Capabilities | Model | Aspect Ratios | | ------------------------------- | ------------------------- | | `imagen-4.0-generate-001` | 1:1, 3:4, 4:3, 9:16, 16:9 | | `imagen-4.0-ultra-generate-001` | 1:1, 3:4, 4:3, 9:16, 16:9 | | `imagen-4.0-fast-generate-001` | 1:1, 3:4, 4:3, 9:16, 16:9 | ### 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']`. ```ts import { google } from '@ai-sdk/google'; import { generateImage } from 'ai'; const { image } = await generateImage({ model: google.image('gemini-2.5-flash-image'), prompt: 'A photorealistic image of a cat wearing a wizard hat', aspectRatio: '1:1', }); ``` Gemini image models also support image editing by providing input images: ```ts import { google } from '@ai-sdk/google'; import { generateImage } from 'ai'; import fs from 'node:fs'; const sourceImage = fs.readFileSync('./cat.png'); const { image } = await generateImage({ model: google.image('gemini-2.5-flash-image'), prompt: { text: 'Add a small wizard hat to this cat', images: [sourceImage], }, }); ``` You can also use URLs for input images: ```ts import { google } from '@ai-sdk/google'; import { generateImage } from 'ai'; const { image } = await generateImage({ model: google.image('gemini-2.5-flash-image'), prompt: { text: 'Add a small wizard hat to this cat', images: ['https://example.com/cat.png'], }, }); ``` Gemini image models do not support the `size` or `n` parameters. Use `aspectRatio` instead of `size`. Mask-based inpainting is also not supported. For more advanced use cases where you need both text and image outputs, or want more control over the generation process, you can use Gemini image models directly with `generateText()`. See [Image Outputs](#image-outputs) for details. #### 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 | | -------------------------------- | ------------------- | ------------------- | --------------------------------------------------- | | `gemini-2.5-flash-image` | | | 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 | | `gemini-3-pro-image-preview` | | | 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 | | `gemini-3.1-flash-image-preview` | | | 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 | `gemini-3-pro-image-preview` supports additional features including up to 14 reference images for editing (6 objects, 5 humans), resolution options (1K, 2K, 4K via `providerOptions.google.imageConfig.imageSize`), and Google Search grounding. ## Speech Models 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`. ```ts const model = google.speech('gemini-2.5-flash-preview-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`. ```ts highlight="6" import { experimental_generateSpeech as generateSpeech } from 'ai'; import { google } from '@ai-sdk/google'; const result = await generateSpeech({ model: google.speech('gemini-2.5-flash-preview-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`. 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`. ### 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`. ```ts highlight="8-23" import { experimental_generateSpeech as 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!', providerOptions: { google: { multiSpeakerVoiceConfig: { speakerVoiceConfigs: [ { speaker: 'Joe', voiceConfig: { prebuiltVoiceConfig: { voiceName: 'Kore' } }, }, { speaker: 'Jane', voiceConfig: { prebuiltVoiceConfig: { voiceName: 'Puck' } }, }, ], }, } satisfies GoogleSpeechModelOptions, }, }); ``` Gemini TTS models do not support the `speed` or `language` options; passing them adds a warning to `result.warnings`. Language is detected automatically from the input text. ### Model Capabilities | Model | Multi-speaker | Style via instructions | | ------------------------------ | ------------------- | ---------------------- | | `gemini-2.5-flash-preview-tts` | | | | `gemini-2.5-pro-preview-tts` | | | | `gemini-3.1-flash-tts-preview` | | |