---
title: Google Vertex AI
description: Route Google Vertex AI requests through AI Gateway for observability and control.
image: https://developers.cloudflare.com/dev-products-preview.png
---

> Documentation Index  
> Fetch the complete documentation index at: https://developers.cloudflare.com/ai-gateway/llms.txt  
> Use this file to discover all available pages before exploring further.

[Skip to content](#%5Ftop) 

# Google Vertex AI

[Google Vertex AI ↗](https://cloud.google.com/vertex-ai) enables developers to easily build and deploy enterprise ready generative AI experiences.

Below is a quick guide on how to set your Google Cloud Account:

1. Google Cloud Platform (GCP) Account  
   * Sign up for a [GCP account ↗](https://cloud.google.com/vertex-ai). New users may be eligible for credits (valid for 90 days).
2. Enable the Vertex AI API  
   * Go to [Enable Vertex AI API ↗](https://console.cloud.google.com/marketplace/product/google/aiplatform.googleapis.com) and activate the API for your project.
3. Apply for access to desired models.

## Endpoint

```

https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai


```

## Prerequisites

When making requests to Google Vertex AI, you will need:

* AI Gateway account tag
* AI Gateway gateway name
* Google Vertex AI credentials (service account JSON or access token)
* Google Vertex AI Project Name
* Google Vertex AI Region (for example, `us-central1`)
* Google Vertex AI model

## URL structure

Your new base URL will use the data above in this structure: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}`.

Then you can append the endpoint you want to hit, for example: `/publishers/google/models/{model}:{generative_ai_rest_resource}`

So your final URL will come together as: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}/publishers/google/models/gemini-2.5-flash:generateContent`

Use a specific region

Use a specific regional endpoint like `us-central1` or `us-east4` rather than `global`. The `global` endpoint has limited model support and may not work with all Vertex AI operations.

## Authenticating with Vertex AI

Authenticating with Vertex AI normally requires generating short-term credentials using the [Google Cloud SDKs ↗](https://cloud.google.com/vertex-ai/docs/authentication) with a complicated setup, but AI Gateway simplifies this for you with multiple options.

### Authentication methods comparison

| Method                             | cf-aig-authorization header | Authorization header                | Region handling              |
| ---------------------------------- | --------------------------- | ----------------------------------- | ---------------------------- |
| **BYOK (Recommended)**             | Bearer {CF\_AIG\_TOKEN}     | Not needed                          | Select in dashboard dropdown |
| **Service account JSON in header** | Bearer {CF\_AIG\_TOKEN}     | Base64-encoded JSON with region key | Include region key in JSON   |
| **Direct access token**            | Bearer {CF\_AIG\_TOKEN}     | Bearer {gcloud\_access\_token}      | Included in URL path         |

Do not confuse the headers

`cf-aig-authorization` authenticates your request to AI Gateway. `Authorization` passes credentials to the upstream provider (Google). When using BYOK, you only need `cf-aig-authorization` because AI Gateway injects the stored Google credentials for you.

### Option 1: BYOK (Recommended)

The recommended approach is to store your Google service account credentials using AI Gateway's [Bring Your Own Keys (BYOK)](https://developers.cloudflare.com/ai-gateway/configuration/bring-your-own-keys/) feature. This keeps your credentials secure and out of your application code.

1. [Create a service account key ↗](https://cloud.google.com/iam/docs/keys-create-delete) in the Google Cloud Console. Ensure that the service account has the required permissions for the Vertex AI endpoints and models you plan to use.
2. In the Cloudflare dashboard, go to **AI** \> **AI Gateway** \> your gateway > **Provider Keys**.
3. Select **Add API Key** and choose **Google Vertex AI** as the provider.
4. Paste your service account JSON and select your region from the dropdown. AI Gateway automatically applies this selected region to your stored credentials, so you do not need to manually add a `region` field to the JSON.
5. Select **Save**.

With BYOK configured, you only need to include the `cf-aig-authorization` header in your requests. AI Gateway handles the Vertex AI authentication automatically.

Terminal window

```

curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}/publishers/google/models/gemini-2.5-flash:generateContent" \

    -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \

    -H 'Content-Type: application/json' \

    -d '{

        "contents": [

          {

            "role": "user",

            "parts": [

              {

                "text": "Tell me more about Cloudflare"

              }

            ]

          }

        ]

      }'


```

### Option 2: Service Account JSON in Header

You can pass a Google service account JSON directly in the `Authorization` header on each request with a base64-encoded version of the JSON. This option is useful for testing or when you cannot use BYOK.

[Create a service account key ↗](https://cloud.google.com/iam/docs/keys-create-delete) in the Google Cloud Console. Ensure that the service account has the required permissions for the Vertex AI endpoints and models you plan to use.

AI Gateway uses your service account JSON to generate short-term access tokens which are cached and used for consecutive requests, and are automatically refreshed when they expire.

Note

When passing the service account JSON directly in the header (not using BYOK), you must include an additional key called `region` in the JSON with the GCP region code (for example, `us-central1`) you intend to use for your [Vertex AI endpoint ↗](https://cloud.google.com/vertex-ai/docs/reference/rest#service-endpoint).

#### Example service account JSON structure

```

{

  "type": "service_account",

  "project_id": "your-project-id",

  "private_key_id": "your-private-key-id",

  "private_key": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n",

  "client_email": "your-service-account@your-project.iam.gserviceaccount.com",

  "client_id": "your-client-id",

  "auth_uri": "https://accounts.google.com/o/oauth2/auth",

  "token_uri": "https://oauth2.googleapis.com/token",

  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",

  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/your-service-account%40your-project.iam.gserviceaccount.com",

  "region": "us-central1"

}


```

### Option 3: Direct Access Token

If you are already using the Google Cloud SDKs and generating a short-term access token (for example, with `gcloud auth print-access-token`), you can directly pass this as a Bearer token in the `Authorization` header of the request.

Note

This option is only supported for the provider-specific endpoint, not for the unified chat completions endpoint.

Terminal window

```

curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}/publishers/google/models/gemini-2.5-flash:generateContent" \

    -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \

    -H "Authorization: Bearer ya29.c.b0Aaekm1K..." \

    -H 'Content-Type: application/json' \

    -d '{

        "contents": [

          {

            "role": "user",

            "parts": [

              {

                "text": "Tell me more about Cloudflare"

              }

            ]

          }

        ]

      }'


```

## Using Unified Chat Completions API

AI Gateway provides a [Unified API](https://developers.cloudflare.com/ai-gateway/usage/chat-completion/) that works across providers. For Google Vertex AI, you can use the standard chat completions format. Note that the model field includes the provider prefix, so your model string will look like `google-vertex-ai/google/gemini-2.5-pro`.

### Endpoint

```

https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions


```

### Example with BYOK

With BYOK configured, you only need to include the `cf-aig-authorization` header:

Terminal window

```

curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions" \

    -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \

    -H 'Content-Type: application/json' \

    -d '{

        "model": "google-vertex-ai/google/gemini-2.5-pro",

        "messages": [

          {

            "role": "user",

            "content": "What is Cloudflare?"

          }

        ]

      }'


```

### Example with OpenAI SDK

If not using BYOK, pass the base64-encoded service account JSON (with `region` key included) as the API key:

JavaScript

```

import OpenAI from "openai";


// Service account JSON must include "region" key when not using BYOK

const serviceAccountJson = JSON.stringify({

  type: "service_account",

  project_id: "your-project-id",

  // ... other fields from your downloaded JSON

  region: "us-central1", // Required: add this to your service account JSON

});


const client = new OpenAI({

  apiKey: Buffer.from(serviceAccountJson).toString("base64"),

  baseURL:

    "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat",

  defaultHeaders: {

    "cf-aig-authorization": `Bearer {cf_aig_token}`,

  },

});


const response = await client.chat.completions.create({

  model: "google-vertex-ai/google/gemini-2.5-pro",

  messages: [

    {

      role: "user",

      content: "What is Cloudflare?",

    },

  ],

});


console.log(response.choices[0].message.content);


```

### Example with cURL

Terminal window

```

# First, base64-encode your service account JSON (must include "region" key)

SERVICE_ACCOUNT_BASE64=$(base64 < service-account.json | tr -d '\n')


curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions" \

    -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \

    -H "Authorization: Bearer $SERVICE_ACCOUNT_BASE64" \

    -H 'Content-Type: application/json' \

    -d '{

        "model": "google-vertex-ai/google/gemini-2.5-pro",

        "messages": [

          {

            "role": "user",

            "content": "What is Cloudflare?"

          }

        ]

      }'


```

Note

When not using BYOK, the service account JSON must include the `region` key and be base64-encoded. Refer to [Option 2: Service Account JSON in Header](#option-2-service-account-json-in-header) for the required JSON structure.

## Using Provider-Specific Endpoint

You can also use the provider-specific endpoint to access the full Vertex AI API.

### cURL with BYOK

With BYOK configured, you only need the `cf-aig-authorization` header:

Terminal window

```

curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}/publishers/google/models/gemini-2.5-flash:generateContent" \

    -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \

    -H 'Content-Type: application/json' \

    -d '{

        "contents": [

          {

            "role": "user",

            "parts": [

              {

                "text": "Tell me more about Cloudflare"

              }

            ]

          }

        ]

      }'


```

### cURL with Service Account JSON

If not using BYOK, pass the base64-encoded service account JSON (with `region` key included) in the Authorization header:

Terminal window

```

# First, base64-encode your service account JSON (must include "region" key) as a single line

SERVICE_ACCOUNT_BASE64=$(base64 < service-account.json | tr -d '\n')


curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}/publishers/google/models/gemini-2.5-flash:generateContent" \

    -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \

    -H "Authorization: Bearer $SERVICE_ACCOUNT_BASE64" \

    -H 'Content-Type: application/json' \

    -d '{

        "contents": [

          {

            "role": "user",

            "parts": [

              {

                "text": "Tell me more about Cloudflare"

              }

            ]

          }

        ]

      }'


```

## Troubleshooting

For general AI Gateway troubleshooting, refer to [Troubleshooting](https://developers.cloudflare.com/ai-gateway/reference/troubleshooting/).

### 401 Unauthenticated errors

If you receive a `CREDENTIALS_MISSING` or `UNAUTHENTICATED` error from Google, check the following Vertex AI-specific issues:

1. **Check your region**: Use a specific regional endpoint (like `us-central1`) in your URL, not `global`. The `global` endpoint has limited model support.
2. **Verify BYOK configuration**: If using BYOK, confirm in the dashboard that:  
   * Your service account JSON was saved correctly  
   * A region was selected from the dropdown
3. **Check service account permissions**: Ensure your service account has the `Vertex AI User` role or equivalent permissions in Google Cloud.
4. **Verify the region key** (non-BYOK only): If passing service account JSON directly in the `Authorization` header, make sure the JSON includes the `region` key.

```json
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/ai-gateway/","name":"AI Gateway"}},{"@type":"ListItem","position":3,"item":{"@id":"/ai-gateway/usage/","name":"Using AI Gateway"}},{"@type":"ListItem","position":4,"item":{"@id":"/ai-gateway/usage/providers/","name":"Provider Native"}},{"@type":"ListItem","position":5,"item":{"@id":"/ai-gateway/usage/providers/vertex/","name":"Google Vertex AI"}}]}
```