Google Vertex AI

The Vertex adapter runs Gemini on Vertex AI. Use it when you need a regional endpoint, CMEK, or VPC-SC.

@tanstack/ai-vertex gives you the Gemini adapters with Vertex auth. Request mapping, tools, and streaming stay the same as in @tanstack/ai-gemini.

1. Install#

npm i @tanstack/ai-vertex

pnpm add @tanstack/ai-vertex

yarn add @tanstack/ai-vertex

bun add @tanstack/ai-vertex

2. Set the credentials#

Vertex uses Google Cloud credentials. It does not read GEMINI_API_KEY or GOOGLE_API_KEY, because those keys are for AI Studio.

1. Sign in with gcloud auth application-default login, or set GOOGLE_APPLICATION_CREDENTIALS to a service account JSON file.
2. Set the project and the region:

GOOGLE_CLOUD_PROJECT=my-project
GOOGLE_CLOUD_LOCATION=europe-west1

You can also pass project and location on each factory, as in the next step. For a service account in code or an express API key, see Authentication.

3. Stream a chat from the server#

Keep the Vertex credentials on the server. The browser only talks to your route.

import {
  chat,
  chatParamsFromRequest,
  toServerSentEventsResponse,
} from "@tanstack/ai";
import { vertexText } from "@tanstack/ai-vertex";

export async function POST(request: Request) {
  const { messages, threadId, runId } = await chatParamsFromRequest(request);

  const stream = chat({
    adapter: vertexText("gemini-3.7-flash", {
      project: "my-project",
      location: "europe-west1",
    }),
    messages,
    threadId,
    runId,
  });

  return toServerSentEventsResponse(stream);
}

4. Render the chat#

useChat does not know that this is Vertex. It reads the stream from your route, the same as for every provider:

import { useState } from "react";
import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";

export function Chat() {
  const [input, setInput] = useState("");
  const { messages, sendMessage } = useChat({
    connection: fetchServerSentEvents("/api/chat"),
    threadId: "support-chat",
  });

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        sendMessage(input);
        setInput("");
      }}
    >
      {messages.map((message) => (
        <p key={message.id}>
          {message.parts
            .map((part) => (part.type === "text" ? part.content : ""))
            .join("")}
        </p>
      ))}
      <input value={input} onChange={(event) => setInput(event.target.value)} />
    </form>
  );
}

For Vue, Solid, Svelte, Angular, and the other frameworks, see Quick Start.

You now have Gemini on Vertex, in the region that you chose.

Other Gemini activities#

Each factory takes the same auth object:

import {
  vertexAudio,
  vertexEmbedding,
  vertexImage,
  vertexSpeech,
  vertexSummarize,
  vertexText,
  vertexVideo,
} from "@tanstack/ai-vertex";

const auth = { project: "my-project", location: "europe-west1" };

vertexText("gemini-3.7-flash", auth);
vertexSummarize("gemini-3.7-flash", auth);
vertexImage("gemini-3.1-flash-image", auth);
vertexEmbedding("gemini-embedding-001", auth);
vertexSpeech("gemini-3.1-flash-tts-preview", auth);
vertexAudio("lyria-3-pro-preview", auth);
vertexVideo("veo-3.1-generate-preview", auth);

• vertexSpeech, vertexAudio, and vertexVideo are experimental.
• vertexText ignores wrapFetch, because the @google/genai SDK does not take a custom fetch.

Models and options#

The model ids and the provider options are the same as in @tanstack/ai-gemini. Image options that only Vertex has (for example 9:21) do not work in this release.

Advanced#

Authentication#

Vertex factories accept every auth option that @google/genai accepts.

Application Default Credentials#

This is the usual Google Cloud path. Sign in with gcloud auth application-default login, or set GOOGLE_APPLICATION_CREDENTIALS to a service account JSON file. Then pass project and location on the factory, or set them in the environment:

import { vertexText } from "@tanstack/ai-vertex";

const adapter = vertexText("gemini-3.7-flash", {
  project: "my-project",
  location: "europe-west1",
});

Service account fields#

import { vertexText } from "@tanstack/ai-vertex";

const adapter = vertexText("gemini-3.7-flash", {
  project: "my-project",
  location: "europe-west1",
  googleAuthOptions: {
    credentials: {
      client_email: "sa@my-project.iam.gserviceaccount.com",
      private_key: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
    },
  },
});

Express API key#

Vertex express mode uses an API key. It needs no project and no location.

import { vertexText } from "@tanstack/ai-vertex";

const adapter = vertexText("gemini-3.7-flash", {
  apiKey: "vertex-express-key",
});

You can also set GOOGLE_VERTEX_API_KEY.

Environment variables#

Claude on Vertex#

Use anthropicVertexText from @tanstack/ai-anthropic/vertex.

Grok on Vertex#

Use grokVertexText from @tanstack/ai-grok/vertex.

• Vertex Grok uses the OpenAI-compatible Responses endpoint.
• For summarize, use grokVertexSummarize from the same entry.
• The factory accepts only the Grok chat models in the Vertex catalog: grok-4.3, grok-4.20-reasoning, grok-4.20-non-reasoning, grok-4.1-fast-reasoning, and grok-4.1-fast-non-reasoning.

Mistral on Vertex#

Use mistralVertexText from @tanstack/ai-mistral/vertex.

• Vertex Mistral uses the publisher rawPredict path.
• It is regional only: us-central1 or europe-west4.
• The factory accepts only the Mistral chat models in the Vertex catalog: mistral-medium-3, mistral-small-2503, and codestral-2.

API reference#

config accepts project, location, apiKey, googleAuthOptions, httpOptions, and the other @google/genai client fields. The factory always sets vertexai: true.