Google Vertex AI

Google 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 ↗. New users may be eligible for credits (valid for 90 days).

2. Enable the Vertex AI API

   • Go to Enable Vertex AI API ↗ 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 ↗ 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) feature. This keeps your credentials secure and out of your application code.

1. Create a service account key ↗ 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.

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 ↗ 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 ↗.

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.

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 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:

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

# 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 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:

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:

# 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.

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.