@ai-sdk/google-vertex 5.0.118 → 5.0.120

package/docs/16-google-vertex.mdx

@@ -1,11 +1,70 @@
 ---
 title: Google Vertex AI
-description: Learn how to use the Google Vertex AI provider.
+description: Learn how to use Google Vertex AI with AI Gateway and the direct provider.
 ---
 
 # Google Vertex Provider
 
 The Google Vertex provider for the [AI SDK](/docs) contains language model support for the [Google Vertex AI](https://cloud.google.com/vertex-ai) APIs. This includes support for [Google's Gemini models](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models), [Anthropic's Claude partner models](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-claude), [xAI's Grok partner models](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/grok), and [MaaS (Model as a Service) open models](https://cloud.google.com/vertex-ai/generative-ai/docs/maas/use-open-models).
+Start with [AI Gateway](/providers/ai-sdk-providers/ai-gateway) for models in its catalog (recommended), or use `@ai-sdk/google-vertex` to connect directly to Google Vertex AI.
+
+```ts provider="google-vertex" model="google/gemini-4-argon"
+import { generateText } from 'ai';
+__PROVIDER_IMPORT__;
+
+const { text } = await generateText({
+  model: __MODEL__,
+  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
+  __GATEWAY_OPTIONS__,
+});
+
+console.log(text);
+```
+
+## Using AI Gateway
+
+The AI SDK uses AI Gateway by default for model strings. Gateway provides access to models across providers through a single API key, with usage and cost tracking. Install `ai`:
+
+<InstallPackages packages="ai" />
+
+Set an [AI Gateway API key](https://vercel.com/docs/ai-gateway/getting-started) in your environment:
+
+```bash
+export AI_GATEWAY_API_KEY=your_api_key_here
+```
+
+Vercel deployments can also use [OIDC authentication](/providers/ai-sdk-providers/ai-gateway#oidc-authentication-vercel-deployments).
+See the [AI Gateway provider documentation](/providers/ai-sdk-providers/ai-gateway) for configuration and the [model catalog](https://vercel.com/ai-gateway/models) for available models.
+
+The example sets `providerOptions.gateway.order` to `['vertex']`. This sends the request to Google Vertex AI first, then falls back to other available providers of the same model if Google Vertex AI is unavailable or the request fails. `order` sets a preference; it does not restrict fallback to Google Vertex AI. See [provider ordering](https://vercel.com/docs/ai-gateway/models-and-providers/provider-filtering-and-ordering).
+
+The dropdown lists models served by Google Vertex AI through Gateway with a corresponding direct-provider example. Provider availability depends on the model and your team's [Provider Allowlist](https://vercel.com/docs/ai-gateway/models-and-providers/provider-filtering-and-ordering).
+
+Gateway uses the `vertex` route for Gemini on Google Vertex AI and handles Google Cloud authentication. The example does not use your `GOOGLE_VERTEX_PROJECT`, location, or service-account credentials; use the direct provider to connect to your own project.
+
+## Using `@ai-sdk/google-vertex`
+
+For direct access to Google Vertex AI, install `ai` and `@ai-sdk/google-vertex`:
+
+<InstallPackages packages="ai @ai-sdk/google-vertex" />
+
+Set your Google Cloud project, location, and the path to your service-account credentials file:
+
+```bash
+export GOOGLE_VERTEX_PROJECT=your_project_id
+export GOOGLE_VERTEX_LOCATION=us-central1
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
+```
+
+The Node.js provider uses Google Application Default Credentials. You can also authenticate locally with `gcloud auth application-default login`. See the runtime sections below for Edge and Express Mode authentication.
+
+Use the direct provider for Google Cloud authentication, Vertex deployments, partner models, or Vertex-specific APIs. Gateway requests do not use your project configuration.
+
+<Note>
+  The following sections document the direct `@ai-sdk/google-vertex` provider,
+  including its model factories and settings. Gateway model and feature
+  availability can differ.
+</Note>
 
 <Note>
   The Google Vertex provider is compatible with both Node.js and Edge runtimes.
@@ -16,12 +75,6 @@ The Google Vertex provider for the [AI SDK](/docs) contains language model suppo
   Runtime](#google-vertex-maas-edge-runtime) sections below.
 </Note>
 
-## Setup
-
-The Google Vertex, Google Vertex Anthropic, Google Vertex xAI, and Google Vertex MaaS providers are available in the `@ai-sdk/google-vertex` module. You can install it with
-
-<InstallPackages packages="@ai-sdk/google-vertex" />
-
 ## Google Vertex Provider Usage
 
 The Google Vertex provider instance is used to create model instances that call the Vertex AI API. The models available with this provider include [Google's Gemini models](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models). If you're looking to use [Anthropic's Claude models](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-claude), see the [Google Vertex Anthropic Provider](#google-vertex-anthropic-provider-usage) section below.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/google-vertex",
-  "version": "5.0.118",
+  "version": "5.0.120",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -71,11 +71,11 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/anthropic": "4.0.84",
-    "@ai-sdk/google": "4.0.101",
-    "@ai-sdk/openai-compatible": "3.0.74",
-    "@ai-sdk/provider": "4.0.31",
-    "@ai-sdk/provider-utils": "5.0.64",
+    "@ai-sdk/anthropic": "4.0.86",
+    "@ai-sdk/google": "4.0.103",
+    "@ai-sdk/openai-compatible": "3.0.76",
+    "@ai-sdk/provider": "4.0.32",
+    "@ai-sdk/provider-utils": "5.0.66",
     "google-auth-library": "^10.6.2"
   },
   "devDependencies": {

package/src/gemini-transcription/google-vertex-gemini-transcription-model-options.ts

@@ -1,3 +1,8 @@
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
 export type GoogleVertexGeminiTranscriptionModelId =
@@ -11,41 +16,45 @@ export type GoogleVertexGeminiTranscriptionModelId =
  * (`gemini-3.5-transcribe-live`) variants. Maps onto Google's
  * `AudioTranscriptionConfig`.
  */
-export const googleVertexGeminiTranscriptionModelOptions = z.object({
-  /**
-   * BCP-47 language codes providing hints about the languages present in the
-   * audio. If omitted or empty, defaults to automatic language detection.
-   */
-  languageCodes: z.array(z.string()).optional(),
+export const googleVertexGeminiTranscriptionModelOptions = lazySchema(() =>
+  zodSchema(
+    z.object({
+      /**
+       * BCP-47 language codes providing hints about the languages present in the
+       * audio. If omitted or empty, defaults to automatic language detection.
+       */
+      languageCodes: z.array(z.string()).optional(),
 
-  /**
-   * Custom vocabulary phrases, which bias the speech recognition model
-   * toward recognizing specific terms.
-   */
-  customVocabulary: z.array(z.string()).optional(),
+      /**
+       * Custom vocabulary phrases, which bias the speech recognition model
+       * toward recognizing specific terms.
+       */
+      customVocabulary: z.array(z.string()).optional(),
 
-  /**
-   * Enables word-level timestamp generation.
-   */
-  wordTimestamp: z.boolean().optional(),
+      /**
+       * Enables word-level timestamp generation.
+       */
+      wordTimestamp: z.boolean().optional(),
 
-  /**
-   * Enables speaker diarization.
-   */
-  diarization: z.boolean().optional(),
+      /**
+       * Enables speaker diarization.
+       */
+      diarization: z.boolean().optional(),
 
-  /**
-   * Transcription output formatting mode.
-   *
-   * - `VERBATIM` (default): exact literal transcript preserving filler
-   *   words, repetitions, and false starts.
-   * - `SMART`: cleans up and structures the transcript in real time —
-   *   disfluency removal, inline self-corrections, structured formatting
-   *   (lists, numbers, dates, paragraph breaks), and grammar/casing polish.
-   */
-  mode: z.enum(['SMART', 'VERBATIM']).optional(),
-});
+      /**
+       * Transcription output formatting mode.
+       *
+       * - `VERBATIM` (default): exact literal transcript preserving filler
+       *   words, repetitions, and false starts.
+       * - `SMART`: cleans up and structures the transcript in real time —
+       *   disfluency removal, inline self-corrections, structured formatting
+       *   (lists, numbers, dates, paragraph breaks), and grammar/casing polish.
+       */
+      mode: z.enum(['SMART', 'VERBATIM']).optional(),
+    }),
+  ),
+);
 
-export type GoogleVertexTranscriptionModelGeminiOptions = z.infer<
+export type GoogleVertexTranscriptionModelGeminiOptions = InferSchema<
   typeof googleVertexGeminiTranscriptionModelOptions
 >;

package/src/gemini-transcription/google-vertex-gemini-transcription-model.ts

@@ -7,6 +7,8 @@ import {
   type TranscriptionModelV4,
 } from '@ai-sdk/provider';
 import {
+  lazySchema,
+  zodSchema,
   combineHeaders,
   connectToWebSocket,
   convertToBase64,
@@ -674,39 +676,44 @@ function parseOffsetSeconds(
   return Number.isFinite(parsed) ? parsed : undefined;
 }
 
-const googleVertexGeminiTranscriptionWordSchema = z.object({
-  word: z.string().nullish(),
-  startOffset: z.string().nullish(),
-  endOffset: z.string().nullish(),
-});
-
-const googleVertexGeminiTranscriptionResponseSchema = z.object({
-  candidates: z
-    .array(
-      z.object({
-        content: z
-          .object({
-            parts: z
-              .array(
-                z.object({
-                  text: z.string().nullish(),
-                  audioTranscription: z
-                    .object({
+const googleVertexGeminiTranscriptionWordSchema = () =>
+  z.object({
+    word: z.string().nullish(),
+    startOffset: z.string().nullish(),
+    endOffset: z.string().nullish(),
+  });
+
+const googleVertexGeminiTranscriptionResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      candidates: z
+        .array(
+          z.object({
+            content: z
+              .object({
+                parts: z
+                  .array(
+                    z.object({
                       text: z.string().nullish(),
-                      languageCode: z.string().nullish(),
-                      speakerLabel: z.string().nullish(),
-                      words: z
-                        .array(googleVertexGeminiTranscriptionWordSchema)
+                      audioTranscription: z
+                        .object({
+                          text: z.string().nullish(),
+                          languageCode: z.string().nullish(),
+                          speakerLabel: z.string().nullish(),
+                          words: z
+                            .array(googleVertexGeminiTranscriptionWordSchema())
+                            .nullish(),
+                        })
                         .nullish(),
-                    })
-                    .nullish(),
-                }),
-              )
+                    }),
+                  )
+                  .nullish(),
+              })
               .nullish(),
-          })
-          .nullish(),
-      }),
-    )
-    .nullish(),
-  usageMetadata: z.record(z.string(), z.unknown()).nullish(),
-});
+          }),
+        )
+        .nullish(),
+      usageMetadata: z.record(z.string(), z.unknown()).nullish(),
+    }),
+  ),
+);

package/src/google-vertex-cloud-tts-speech-model.ts

@@ -1,5 +1,7 @@
 import type { SharedV4Warning, SpeechModelV4 } from '@ai-sdk/provider';
 import {
+  lazySchema,
+  zodSchema,
   combineHeaders,
   convertBase64ToUint8Array,
   createJsonResponseHandler,
@@ -183,6 +185,10 @@ export class GoogleVertexCloudTTSSpeechModel implements SpeechModelV4 {
 
 // Minimal schema: only the fields the implementation reads, with `.nullish()`
 // so provider API changes don't break parsing.
-const googleVertexCloudTTSResponseSchema = z.object({
-  audioContent: z.string().nullish(),
-});
+const googleVertexCloudTTSResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      audioContent: z.string().nullish(),
+    }),
+  ),
+);

package/src/google-vertex-embedding-model-options.ts

@@ -1,3 +1,8 @@
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
 // https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text-embeddings-api
@@ -15,52 +20,56 @@ export type GoogleVertexEmbeddingModelId =
   | 'gemini-embedding-2-preview'
   | (string & {});
 
-export const googleVertexEmbeddingModelOptions = z.object({
-  /**
-   * Optional. Optional reduced dimension for the output embedding.
-   * If set, excessive values in the output embedding are truncated from the end.
-   */
-  outputDimensionality: z.number().optional(),
+export const googleVertexEmbeddingModelOptions = lazySchema(() =>
+  zodSchema(
+    z.object({
+      /**
+       * Optional. Optional reduced dimension for the output embedding.
+       * If set, excessive values in the output embedding are truncated from the end.
+       */
+      outputDimensionality: z.number().optional(),
 
-  /**
-   * Optional. Specifies the task type for generating embeddings.
-   * Supported task types:
-   * - 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.
-   */
-  taskType: z
-    .enum([
-      'SEMANTIC_SIMILARITY',
-      'CLASSIFICATION',
-      'CLUSTERING',
-      'RETRIEVAL_DOCUMENT',
-      'RETRIEVAL_QUERY',
-      'QUESTION_ANSWERING',
-      'FACT_VERIFICATION',
-      'CODE_RETRIEVAL_QUERY',
-    ])
-    .optional(),
+      /**
+       * Optional. Specifies the task type for generating embeddings.
+       * Supported task types:
+       * - 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.
+       */
+      taskType: z
+        .enum([
+          'SEMANTIC_SIMILARITY',
+          'CLASSIFICATION',
+          'CLUSTERING',
+          'RETRIEVAL_DOCUMENT',
+          'RETRIEVAL_QUERY',
+          'QUESTION_ANSWERING',
+          'FACT_VERIFICATION',
+          'CODE_RETRIEVAL_QUERY',
+        ])
+        .optional(),
 
-  /**
-   * Optional. The title of the document being embedded.
-   * Only valid when task_type is set to 'RETRIEVAL_DOCUMENT'.
-   * Helps the model produce better embeddings by providing additional context.
-   */
-  title: z.string().optional(),
+      /**
+       * Optional. The title of the document being embedded.
+       * Only valid when task_type is set to 'RETRIEVAL_DOCUMENT'.
+       * Helps the model produce better embeddings by providing additional context.
+       */
+      title: z.string().optional(),
 
-  /**
-   * Optional. When set to true, input text will be truncated. When set to false,
-   * an error is returned if the input text is longer than the maximum length supported by the model. Defaults to true.
-   */
-  autoTruncate: z.boolean().optional(),
-});
+      /**
+       * Optional. When set to true, input text will be truncated. When set to false,
+       * an error is returned if the input text is longer than the maximum length supported by the model. Defaults to true.
+       */
+      autoTruncate: z.boolean().optional(),
+    }),
+  ),
+);
 
-export type GoogleVertexEmbeddingModelOptions = z.infer<
+export type GoogleVertexEmbeddingModelOptions = InferSchema<
   typeof googleVertexEmbeddingModelOptions
 >;

package/src/google-vertex-embedding-model.ts

@@ -3,6 +3,8 @@ import {
   type EmbeddingModelV4,
 } from '@ai-sdk/provider';
 import {
+  lazySchema,
+  zodSchema,
   combineHeaders,
   createJsonResponseHandler,
   postJsonToApi,
@@ -190,29 +192,37 @@ export class GoogleVertexEmbeddingModel implements EmbeddingModelV4 {
 
 // minimal version of the schema, focussed on what is needed for the implementation
 // this approach limits breakages when the API changes and increases efficiency
-const googleVertexTextEmbeddingResponseSchema = z.object({
-  predictions: z.array(
+const googleVertexTextEmbeddingResponseSchema = lazySchema(() =>
+  zodSchema(
     z.object({
-      embeddings: z.object({
-        values: z.array(z.number()),
-        statistics: z.object({
-          token_count: z.number(),
+      predictions: z.array(
+        z.object({
+          embeddings: z.object({
+            values: z.array(z.number()),
+            statistics: z.object({
+              token_count: z.number(),
+            }),
+          }),
         }),
+      ),
+    }),
+  ),
+);
+
+const googleVertexEmbedContentResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      embedding: z.object({
+        values: z.array(z.number()),
       }),
+      usageMetadata: z
+        .object({
+          promptTokenCount: z.number().nullish(),
+        })
+        .nullish(),
     }),
   ),
-});
-
-const googleVertexEmbedContentResponseSchema = z.object({
-  embedding: z.object({
-    values: z.array(z.number()),
-  }),
-  usageMetadata: z
-    .object({
-      promptTokenCount: z.number().nullish(),
-    })
-    .nullish(),
-});
+);
 
 function usesEmbedContentEndpoint(modelId: GoogleVertexEmbeddingModelId) {
   return (

package/src/google-vertex-error.ts

@@ -1,15 +1,26 @@
-import { createJsonErrorResponseHandler } from '@ai-sdk/provider-utils';
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+  createJsonErrorResponseHandler,
+} from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
-const googleVertexErrorDataSchema = z.object({
-  error: z.object({
-    code: z.number().nullable(),
-    message: z.string(),
-    status: z.string(),
-  }),
-});
+const googleVertexErrorDataSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      error: z.object({
+        code: z.number().nullable(),
+        message: z.string(),
+        status: z.string(),
+      }),
+    }),
+  ),
+);
 
-export type GoogleVertexErrorData = z.infer<typeof googleVertexErrorDataSchema>;
+export type GoogleVertexErrorData = InferSchema<
+  typeof googleVertexErrorDataSchema
+>;
 
 export const googleVertexFailedResponseHandler = createJsonErrorResponseHandler(
   {

package/src/google-vertex-transcription-model-options.ts

@@ -1,3 +1,8 @@
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
 // Google Cloud Speech-to-Text transcription models (Speech-to-Text v2).
@@ -8,40 +13,44 @@ export type GoogleVertexTranscriptionModelId =
   | 'telephony'
   | (string & {});
 
-export const googleVertexTranscriptionProviderOptionsSchema = z.object({
-  /**
-   * BCP-47 language codes to recognize (e.g. `['en-US']`), or `['auto']` to let
-   * Chirp auto-detect the spoken language. Defaults to `['auto']`. For
-   * `telephony`, pass a supported explicit language code.
-   */
-  languageCodes: z.array(z.string()).optional(),
+export const googleVertexTranscriptionProviderOptionsSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      /**
+       * BCP-47 language codes to recognize (e.g. `['en-US']`), or `['auto']` to let
+       * Chirp auto-detect the spoken language. Defaults to `['auto']`. For
+       * `telephony`, pass a supported explicit language code.
+       */
+      languageCodes: z.array(z.string()).optional(),
 
-  /**
-   * Whether to add punctuation to the transcript. Defaults to `true`.
-   */
-  enableAutomaticPunctuation: z.boolean().optional(),
+      /**
+       * Whether to add punctuation to the transcript. Defaults to `true`.
+       */
+      enableAutomaticPunctuation: z.boolean().optional(),
 
-  /**
-   * Whether to include word-level timestamps. Defaults to `true` so the
-   * transcription result can include segments.
-   *
-   * Enabling word-level timestamps can reduce transcription quality and speed
-   * for Chirp models.
-   */
-  enableWordTimeOffsets: z.boolean().optional(),
+      /**
+       * Whether to include word-level timestamps. Defaults to `true` so the
+       * transcription result can include segments.
+       *
+       * Enabling word-level timestamps can reduce transcription quality and speed
+       * for Chirp models.
+       */
+      enableWordTimeOffsets: z.boolean().optional(),
 
-  /**
-   * The Cloud Speech-to-Text region for the request (e.g. `'us'`, `'eu'`,
-   * `'us-central1'`). Defaults to the provider `location`. Must be a single
-   * DNS label (letters, digits, and hyphens).
-   *
-   * Note: Speech-to-Text regions differ from Vertex AI regions. Chirp is only
-   * available in specific Speech-to-Text regions and is not available in the
-   * `global` location.
-   */
-  region: z.string().optional(),
-});
+      /**
+       * The Cloud Speech-to-Text region for the request (e.g. `'us'`, `'eu'`,
+       * `'us-central1'`). Defaults to the provider `location`. Must be a single
+       * DNS label (letters, digits, and hyphens).
+       *
+       * Note: Speech-to-Text regions differ from Vertex AI regions. Chirp is only
+       * available in specific Speech-to-Text regions and is not available in the
+       * `global` location.
+       */
+      region: z.string().optional(),
+    }),
+  ),
+);
 
-export type GoogleVertexTranscriptionModelOptions = z.infer<
+export type GoogleVertexTranscriptionModelOptions = InferSchema<
   typeof googleVertexTranscriptionProviderOptionsSchema
 >;