Google Vertex AI
Connect Gemini models hosted in your own Google Cloud project using a service account key
Overview
Google Vertex AI serves Gemini models from inside your own Google Cloud project, in a region you choose. Pick Google Vertex AI on the provider picker when you add an LLM configuration. It sits in the Cloud & self-hosted group alongside Amazon Bedrock and Self Hosted.
Vertex AI is the right choice when you want Gemini but your organization needs the traffic and the billing to sit inside a Google Cloud project you control. If you only want a quick Gemini key, use the direct Gemini provider instead. See Cloud providers.
Scope: Gemini on Vertex only. Vertex AI's Model Garden also hosts Claude, Llama and Mistral, but each of those uses a different wire format on Vertex infrastructure. Claude on Vertex, for example, uses Anthropic's Messages shape through a separate endpoint. Unlike Bedrock, Vertex has no single shape that covers every family, so MagOneAI currently supports Gemini models on Vertex only.
To use Claude, connect Anthropic directly or use Amazon Bedrock.
How Vertex AI differs from the direct Gemini provider
The request and response shape is identical. Vertex AI's :generateContent endpoint uses the same JSON as Google's direct Generative Language API, so MagOneAI reuses the same conversion code for both. Only the URL and the authentication header differ.
| Gemini (direct) | Google Vertex AI | |
|---|---|---|
| Credential | Google AI Studio API key | GCP service account JSON key |
| Auth header | API key | OAuth2 bearer token, minted by MagOneAI |
| Scoping | Your AI Studio account | Your GCP project and region |
| Required fields | Endpoint, API key | Service Account JSON, GCP Project ID, GCP Region |
| Billing | Google AI Studio | Your Google Cloud bill |
Setup steps
Enable the Vertex AI API
In the Google Cloud console, select the project you want to use and enable the Vertex AI API.
Note the project ID, not the project name or project number. MagOneAI needs the ID, which is lowercase letters, digits and hyphens, 6 to 30 characters long.
Create a service account
Create a service account in the same project and grant it the Vertex AI User role (roles/aiplatform.user).
This is the narrowest predefined role that can call :generateContent. Avoid granting project-wide editor or owner roles.
Download a JSON key
Create a key for that service account and download it in JSON format. The file looks like this:
{
"type": "service_account",
"project_id": "my-gcp-project",
"private_key_id": "...",
"private_key": "-----BEGIN PRIVATE KEY-----\n...",
"client_email": "magoneai@my-gcp-project.iam.gserviceaccount.com",
"token_uri": "https://oauth2.googleapis.com/token"
}MagOneAI requires type to be exactly service_account, and it requires client_email, private_key and token_uri to be present. A key missing any of those is refused at save time with a message naming the missing fields.
Add the configuration in MagOneAI
Open LLM configurations for the organization and add a new configuration. Select Google Vertex AI as the provider, then fill in three fields:
- Service Account JSON: paste the whole JSON file contents
- GCP Project ID: for example
my-gcp-project - GCP Region: for example
us-central1oreurope-west4
The generic Endpoint field is ignored for Vertex configurations. MagOneAI builds the URL from the project and region.
Pick a model
Choose a Gemini model available in the region you selected, for example gemini-2.5-pro or gemini-2.0-flash.
Model availability differs by region. A model that exists in us-central1 may not exist in your chosen region yet.
Declare capabilities and save
Gemini models are natively multimodal, so tick Supports Vision and, where the model handles it, Supports Audio. Fill in Advanced → Cost (USD per 1K tokens).
Click Save. MagOneAI mints a token and runs one test call before storing the configuration, so a bad key, a wrong project ID or an unavailable model surfaces straight away.
Editing an existing Vertex configuration leaves the service account key in place if you leave the field empty. The field shows dots in edit mode. Paste a new key only when you want to rotate it.
Project and region format rules
MagOneAI validates both fields against Google's real formats, at the API boundary and again immediately before it builds the request URL.
| Field | Rule | Valid | Invalid |
|---|---|---|---|
| GCP Project ID | Starts with a lowercase letter, then lowercase letters, digits and hyphens, 6 to 30 characters, does not end with a hyphen | my-gcp-project | My_Project, x |
| GCP Region | A GCP regional location: words separated by hyphens, ending in a digit | us-central1, europe-west4, northamerica-northeast1 | us-central, global |
Both values are interpolated into the request URL:
https://{region}-aiplatform.googleapis.com/v1/projects/{project}/...The service account bearer token is sent to whatever host that URL names. A region value such as evil.com/x# would move the host and leak the token, which is why the format rules are enforced twice and why only true GCP regional locations are accepted.
Token handling
MagOneAI mints an OAuth2 bearer token from your service account key, scoped to https://www.googleapis.com/auth/cloud-platform.
Google tokens last about one hour. MagOneAI caches the minted token and reuses it until five minutes before it expires, so a busy configuration mints roughly one token per hour rather than one per LLM call.
The cache key includes a hash of the private key, not just the service account email. A rotated key therefore never reuses the previous key's token.
There is no Application Default Credentials fallback. Every provider in MagOneAI is strictly bring-your-own-key and scoped to one organization. Falling back to the deployment's own ADC would let every organization on the platform share its GCP project and permissions.
A configuration with no service account key fails with GCP service-account JSON required for Vertex AI rather than silently using the server's identity.
Credential storage
The service account JSON is a structured secret. MagOneAI stores it in HashiCorp Vault and keeps only a Vault reference on the configuration row. This is the same convention used for the Bedrock credential set.
The project ID and region are not secret, so they are stored in plain text on the configuration. See Secrets management.
Cost tracking
Vertex AI bills through Google Cloud, and the rate differs per model and region. MagOneAI does not read Google Cloud pricing, so fill in Advanced → Cost (USD per 1K tokens) on each Vertex configuration yourself, for both Input and Output.
With those values set, Vertex usage appears beside every other provider in the usage dashboards. See Usage and quotas.
Troubleshooting
Cause: The configuration has no service account key stored.
Fix: Paste the key JSON and save. MagOneAI has no ADC fallback, so an empty credential is always an error.
Cause: What was pasted is not valid JSON. A common cause is pasting only part of the file, or pasting it from an editor that reflowed the private_key line.
Fix: Copy the whole file contents, unchanged, and paste again.
Cause: You pasted an OAuth client secret file or a user credential file instead of a service account key.
Fix: Create a key on a service account, not an OAuth client, and download it as JSON.
Cause: The key is missing client_email, private_key or token_uri. The error names the missing fields.
Fix: Download a fresh key from the Google Cloud console rather than reconstructing one by hand.
Cause: The private_key value is malformed, most often because literal \n escape sequences were converted to real newlines or stripped when the file passed through another tool.
Fix: Paste the original downloaded file contents without editing them.
Cause: The value does not match Google's format rules. Using the project number instead of the project ID is the most common mistake.
Fix: Use the project ID from the Google Cloud console, and a true regional location such as us-central1.
Causes to check, in order:
- The service account is missing Vertex AI User (
roles/aiplatform.user). - The Vertex AI API is not enabled on the project.
- The service account belongs to a different project than the project ID on the configuration.
Cause: The model is not served in the region you selected, or the model ID is wrong.
Fix: Check Google's model availability table for your region, then correct the region or the model ID.