> ## Documentation Index
> Fetch the complete documentation index at: https://docs.core-ai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Google on Vertex AI

> Create and configure the Google provider for Gemini, embedding, and image models hosted on Vertex AI

## Overview

The Google on Vertex AI provider gives you access to Gemini chat, embedding,
and native image models as well as Imagen through Google Cloud. It uses the
same model behavior as `@core-ai/google-genai`, while configuring the Google
SDK for Vertex AI authentication and regional endpoints.

## Installation

```bash theme={null}
npm install @core-ai/google-vertex
```

## createGoogleVertex()

Create a Google provider targeting one Google Cloud project and region.

```typescript theme={null}
import { createGoogleVertex } from '@core-ai/google-vertex';

const googleVertex = createGoogleVertex({
    projectId: process.env.GOOGLE_VERTEX_PROJECT,
    region: 'europe-west1',
});
```

### Options

<ParamField path="projectId" type="string" optional>
  Google Cloud project ID. Required unless a preconfigured client is supplied.
</ParamField>

<ParamField path="region" type="string" optional>
  Vertex AI location, such as `europe-west1` or `us-central1`. Required unless
  a preconfigured client is supplied.
</ParamField>

<ParamField path="credentials" type="GoogleVertexServiceAccountCredentials" optional>
  Parsed service-account JSON. When omitted, the Google SDK uses Application
  Default Credentials.
</ParamField>

<ParamField path="client" type="GoogleGenAIClient" optional>
  A preconfigured Google client. When supplied, `projectId`, `region`, and
  `credentials` are not used.
</ParamField>

### Returns

`GoogleVertexProvider` with `chatModel()`, `embeddingModel()`, and `imageModel()` methods.

## Authentication

### Application Default Credentials

Without explicit credentials, the provider uses [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials):

```typescript theme={null}
const googleVertex = createGoogleVertex({
    projectId: process.env.GOOGLE_VERTEX_PROJECT,
    region: 'europe-west1',
});
```

ADC is recommended for workloads running on Google Cloud. For local development, configure ADC with the Google Cloud CLI:

```bash theme={null}
gcloud auth application-default login
```

### Service-account credentials

Parse a service-account JSON key and pass the resulting object:

```typescript theme={null}
const rawCredentials = process.env.GOOGLE_APPLICATION_CREDENTIALS_JSON;
const credentialsJson = rawCredentials?.trim().startsWith('{')
    ? rawCredentials
    : Buffer.from(rawCredentials ?? '', 'base64').toString('utf8');

const googleVertex = createGoogleVertex({
    projectId: process.env.GOOGLE_VERTEX_PROJECT,
    region: 'europe-west1',
    credentials: JSON.parse(credentialsJson),
});
```

<Note>
  `GOOGLE_APPLICATION_CREDENTIALS_JSON` accepts either plain JSON or
  base64-encoded JSON. This is separate from Google's standard
  `GOOGLE_APPLICATION_CREDENTIALS` env var, which points to a credentials file
  path for ADC.
</Note>

### Custom client

You can inject a preconfigured Google client:

```typescript theme={null}
import { GoogleGenAI } from '@google/genai';
import { createGoogleVertex } from '@core-ai/google-vertex';

const googleVertex = createGoogleVertex({
    client: new GoogleGenAI({
        vertexai: true,
        project: 'my-project',
        location: 'europe-west1',
    }),
});
```

## Models and regions

Use model IDs available to your project in the selected Vertex AI region:

```typescript theme={null}
const chat = googleVertex.chatModel('gemini-2.5-flash');
const embeddings = googleVertex.embeddingModel('gemini-embedding-001');
const image = googleVertex.imageModel('gemini-2.5-flash-image');
```

Model availability varies by region. Since a provider instance targets one
region, create separate providers for models hosted in different locations.
Imagen models such as `imagen-4.0-generate-001` are also supported when they
are available to the selected project and region.

## Examples

### Chat and streaming

```typescript theme={null}
import { generate, stream } from '@core-ai/core-ai';

const model = googleVertex.chatModel('gemini-2.5-flash');

const result = await generate({
    model,
    messages: [{ role: 'user', content: 'Explain vector databases.' }],
});

const chatStream = await stream({
    model,
    messages: [{ role: 'user', content: 'Write a short story.' }],
});
```

### Embeddings

```typescript theme={null}
import { embed } from '@core-ai/core-ai';

const result = await embed({
    model: googleVertex.embeddingModel('gemini-embedding-001'),
    input: 'Text to embed',
});
```

### Image generation

```typescript theme={null}
import { generateImage } from '@core-ai/core-ai';

const result = await generateImage({
    model: googleVertex.imageModel('gemini-2.5-flash-image'),
    prompt: 'A serene mountain landscape at dawn',
    size: '1024x1024',
});
```

Gemini image models return base64 image data and do not support requesting
multiple outputs with `n`. Imagen model IDs use the dedicated Imagen API and
support `n`.

## Provider-specific options

Provider options remain namespaced under `google`, matching `@core-ai/google-genai`:

```typescript theme={null}
const result = await generate({
    model: googleVertex.chatModel('gemini-2.5-flash'),
    messages: [{ role: 'user', content: 'Hello' }],
    providerOptions: {
        google: {
            topK: 40,
            seed: 42,
        },
    },
});
```

The Google provider-option schemas, `GoogleReasoningMetadata`, and `getGoogleModelCapabilities()` are exported by `@core-ai/google-vertex`.

## Error handling

Errors are wrapped as `ProviderError` with provider ID `google-vertex`:

```typescript theme={null}
import { ProviderError } from '@core-ai/core-ai';

try {
    await generate({
        model: googleVertex.chatModel('gemini-2.5-flash'),
        messages: [{ role: 'user', content: 'Hello!' }],
    });
} catch (error) {
    if (error instanceof ProviderError) {
        console.error(error.provider);
        console.error(error.message);
    }
}
```

## Related

<CardGroup cols={2}>
  <Card title="Google GenAI Provider" icon="google" href="/api/providers/google-genai">
    Use Gemini through the Google AI API
  </Card>

  <Card title="Anthropic on Vertex AI" icon="cloud" href="/api/providers/anthropic-vertex">
    Use Claude through Vertex AI
  </Card>
</CardGroup>