Vertex AI enterprise (Gemini)
Vertex AI is Google’s enterprise endpoint for Gemini models — same model IDs as the Gemini Developer API but with GCP-native authentication (IAM), regional/private endpoints, audit logging, data-residency controls, and the Model Garden (Claude, Llama, Mistral, and 200+ open models hosted on Vertex infrastructure alongside Gemini). The two surfaces overlap heavily — the google-genai SDK switches modes with a single constructor flag — so most code is portable. The choice between them is fundamentally about controls, not features: pick Vertex when you need IAM-based access, private VPC routing, audit logs, regional residency, or you want Claude / Llama / Mistral on a single GCP bill. As of 2026, Vertex AI is transitioning to the Gemini Enterprise Agent Platform — the old cloud.google.com/vertex-ai/generative-ai/docs URL redirects, and new feature work is at cloud.google.com/agent-platform/docs.
See also
- gemini-api-and-sdks — the shared SDK surface
- gemini-models-and-capabilities — model IDs (drop
models/prefix on Vertex) - embeddings-and-vertex-search-gemini — Vertex AI Search (managed RAG)
- context-caching-gemini — works the same on Vertex with regional scope
- claude-models-and-capabilities — Claude on Vertex section
- auth-authz — IAM concepts
1. Developer API vs Vertex AI
| Property | Gemini Developer API | Vertex AI |
|---|---|---|
| Host | generativelanguage.googleapis.com | aiplatform.googleapis.com (regional) |
| Auth | API key (x-goog-api-key) | GCP IAM (service account, ADC, user creds) |
| Console | aistudio.google.com | console.cloud.google.com/vertex-ai |
| Best for | Indie devs, prototyping, low-volume production | Enterprise production, compliance, GCP-resident workloads |
| Endpoints | Single global endpoint | Regional (us-central1, europe-west4, …) + global where supported |
| Private networking | No | Yes (VPC Service Controls, Private Service Connect) |
| IAM | No | Yes (granular roles, conditional access) |
| Audit logs | No | Yes (Cloud Audit Logs) |
| Data residency | US-only | Per-region |
| Free tier | Yes | Limited ($300 GCP credit for new accounts) |
| Express mode | n/a | API-key on-ramp, subset of full Vertex |
| Model Garden | No | Yes — Claude, Llama, Mistral, etc. |
| SLA | Best-effort | Per-tier SLA |
| Customer-Managed Encryption Keys (CMEK) | No | Yes |
2. Authentication
Application Default Credentials (ADC) — recommended
# Local dev
gcloud auth application-default login
# Server / GKE
# (service account attached to the runtime — no JSON key needed)from google import genai
client = genai.Client(
vertexai=True,
project="my-gcp-project",
location="us-central1",
)
# ADC picked up automaticallyService account key (legacy)
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/sa-key.json"client = genai.Client(vertexai=True, project="...", location="us-central1")Service account JSON keys are discouraged — prefer Workload Identity Federation, attached service accounts, or short-lived tokens.
Vertex AI Express Mode
client = genai.Client(vertexai=True, api_key="VERTEX_EXPRESS_KEY")API-key access to a subset of Vertex features (text generation, embeddings, basic tools). No IAM, no private VPC. Use when you want Vertex pricing/regional features without setting up service accounts. The on-ramp tier.
3. Model ID conventions
Bare model IDs on Vertex (no models/ prefix):
# Developer API
client.models.generate_content(model="models/gemini-3.5-flash", ...)
# Vertex AI
client.models.generate_content(model="gemini-3.5-flash", ...)For Vertex-only models (Model Garden):
# Claude on Vertex
client.models.generate_content(model="claude-opus-4-7", ...)
# Note: requires separate enablement in the GCP console for each Anthropic model
# Llama on Vertex
client.models.generate_content(model="llama-3.1-405b-instruct", ...)
# Mistral on Vertex
client.models.generate_content(model="mistral-large-2", ...)Model availability varies by region. The us-central1 region typically has the broadest catalog.
4. Regional endpoints
Per cloud.google.com/vertex-ai/docs/locations:
| Region | Use when |
|---|---|
us-central1 (Iowa) | Default / broadest model availability |
us-east4 (Virginia) | East-coast US workloads |
europe-west4 (Netherlands) | EU data residency |
europe-west1 (Belgium) | EU alternative |
asia-northeast1 (Tokyo) | APAC |
asia-southeast1 (Singapore) | SE Asia |
global | Multi-region routing (where supported) |
client = genai.Client(vertexai=True, project="...", location="europe-west4")Regional scope of resources:
- Caches are regional — a cache in
us-central1is invisible fromeurope-west4 - Files are regional
- Batch jobs are regional
- Tuned models are regional
Choose your region at the start of a project and stay there.
5. Model Garden
Per cloud.google.com/vertex-ai/generative-ai/docs/model-garden. Vertex hosts:
| Family | Notable models |
|---|---|
| Anthropic | Claude Opus 4.7, Sonnet 4.6, Haiku 4.5 (and legacy) |
| Meta | Llama 3.1 / 3.2 / 4 (when GA) |
| Mistral | Mistral Large 2, Codestral |
| AI21 | Jamba 1.5 Large / Mini |
| Cohere | Command R+, Command R |
| Google open | Gemma 2 / 3, PaLM 2 legacy |
| Open source | 200+ via HuggingFace integration |
Same SDK surface for first-party + partner models. Difference: partner models require explicit enablement per model in the GCP console (a one-time click acknowledging terms + activating billing) before they’re callable.
Pricing for Model Garden partner models is billed through Google at the partner’s published rates, often with a Google margin. Compare to direct partner API if cost-sensitive.
6. IAM and permissions
Key roles (cloud.google.com/iam/docs/understanding-roles):
| Role | What it grants |
|---|---|
roles/aiplatform.user | Most common — call models, run jobs |
roles/aiplatform.viewer | Read-only — see resources, no API calls |
roles/aiplatform.admin | Full control on Vertex resources |
roles/aiplatform.serviceAgent | For internal service-to-service |
roles/aiplatform.tuningServiceAccount | For supervised tuning |
Custom roles + IAM conditions allow per-resource, per-region, time-bound access.
Example: grant a service account permission to call only the europe-west4 endpoint:
bindings:
- members:
- serviceAccount:my-app@my-project.iam.gserviceaccount.com
role: roles/aiplatform.user
condition:
title: "EU region only"
expression: "resource.name.startsWith('projects/my-project/locations/europe-west4/')"7. Private VPC and VPC Service Controls
For workloads that must never traverse the public internet:
- Private Service Connect — Vertex endpoints resolve to private IPs inside your VPC
- VPC Service Controls — perimeter policy that prevents data exfiltration even if IAM is compromised
- Customer-Managed Encryption Keys (CMEK) — control your own encryption keys via Cloud KMS
Setup is non-trivial (typically days of platform engineering). Worth it for regulated workloads (financial services, healthcare, government).
8. Audit logging
Cloud Audit Logs captures every API call to Vertex automatically when enabled:
- Admin Activity — resource creation, IAM changes — always on
- Data Access — model invocations, including request/response metadata — opt-in (and incurs log storage cost)
- System Events — internal Google actions
- Policy Denied — calls blocked by VPC SC or IAM
For full request/response capture (for compliance review), enable Data Access logs at the project level. Costs scale with traffic.
9. Supervised fine-tuning
Vertex AI supports supervised tuning of Gemini models. Per cloud.google.com/vertex-ai/generative-ai/docs/models/tune-models:
from google.cloud import aiplatform
job = aiplatform.gemini_tuning.create(
base_model="gemini-2.5-flash",
training_dataset="gs://my-bucket/train.jsonl",
validation_dataset="gs://my-bucket/val.jsonl",
output_uri="gs://my-bucket/tuned-models/",
epochs=3,
learning_rate_multiplier=1.0,
adapter_size=4, # LoRA rank
)Training data format: JSONL with {"messages": [{"role": "user", "content": "..."}, {"role": "model", "content": "..."}]} per line.
Models that support tuning (as of 2026-05): gemini-2.5-flash, gemini-2.5-flash-lite, gemini-2.0-flash and some 1.5 line. Gemini 3.x tuning availability rolls out by model.
Tuned models are referenced by full resource name: projects/PROJECT/locations/LOCATION/tuningJobs/JOB_ID/tunedModel. Serve via the same generate_content call.
Preference / RLHF tuning
Available for select models via Vertex; less commonly used than supervised. Provides a way to tune on (prompt, chosen, rejected) triplets.
10. Batch jobs on Vertex
Same surface as the Developer API (see gemini-api-and-sdks), with regional resources:
batch = client.batches.create(
model="gemini-3.5-flash",
src="gs://my-bucket/batch-input.jsonl", # GCS input
config=types.CreateBatchJobConfig(
display_name="nightly-job",
dest="gs://my-bucket/batch-output/",
),
)GCS-based I/O is standard on Vertex. The Developer API uses the in-product Files API instead.
11. Pricing
Per cloud.google.com/vertex-ai/pricing/generative-ai:
- Per-token rates match Developer API for Gemini models (no Vertex surcharge on Gemini)
- Model Garden partner models — partner rates + small Google margin
- Tuning — per-token training cost + serving infrastructure cost
- Vertex AI Search — separate per-document + per-query pricing
- Storage (caches, files, batch I/O) — standard GCS pricing
- Audit log storage — standard Cloud Logging pricing
For most workloads, total cost is dominated by per-token model spend; everything else is small unless you’re indexing massive document corpora or storing huge audit volumes.
12. Gemini Enterprise Agent Platform (transition)
Per cloud.google.com/agent-platform/docs (2026):
- The Vertex AI Generative AI docs are being consolidated into the Gemini Enterprise Agent Platform docs site
- Old URLs (
cloud.google.com/vertex-ai/generative-ai/docs) redirect to the new location - New capabilities (Agent Builder, Live API, Computer Use endpoint) ship under the Agent Platform brand
- Existing Vertex resources, SDKs, and API endpoints continue to work — this is a docs / branding consolidation, not a deprecation
Practical: when looking up new features, check the Agent Platform docs first. For established capabilities, the Vertex docs are still authoritative.
13. Migrating from Developer API to Vertex
Step 1 — set up GCP project + permissions
gcloud projects create my-project
gcloud config set project my-project
gcloud services enable aiplatform.googleapis.com
gcloud auth application-default loginStep 2 — change client init
# Before
client = genai.Client(api_key="...")
# After
client = genai.Client(vertexai=True, project="my-project", location="us-central1")Step 3 — adjust model IDs
# Strip "models/" prefix
"models/gemini-3.5-flash" → "gemini-3.5-flash"Step 4 — re-create regional resources
- Caches: previous caches on Developer API don’t exist on Vertex; recreate in your chosen region
- Files: re-upload (Vertex uses GCS for long-lived files; Files API also works)
- Tuned models: tune again on Vertex (different infra)
Step 5 — set up audit logging if required
Enable Data Access logs in Cloud Audit Logs.
Step 6 — enable Model Garden partner models if needed
Console → Model Garden → click “Enable” on Claude / Llama / Mistral entries.
14. Common pitfalls
- Mixing Developer API and Vertex model IDs —
models/gemini-3.5-flashfails on Vertex; bare ID fails on Developer API. - Regional cache invisibility — a cache in
us-central1is invisible fromeurope-west4. Match regions. - Service account JSON keys leaking — use ADC / Workload Identity. Never check JSON keys into source.
- Forgetting to enable Model Garden partners — calls to Claude / Llama return
NOT_FOUNDuntil the model is enabled in the console. - VPC Service Controls blocking GCS access — when restricting Vertex to a VPC, also include
storage.googleapis.comin the perimeter, or batch jobs fail. - Audit log cost surprise — Data Access logging on high-volume Vertex projects can produce GB/day of logs. Sample or filter if cost-sensitive.
- Tuning a deprecated base model — tuning on a model that retires next quarter wastes effort. Check the deprecation page first.
- Cross-region traffic — calling
us-central1fromeurope-west4-resident services traverses Google’s backbone and adds latency. Pin services to the model’s region.
15. Comparison to other vendors’ enterprise paths
| Aspect | Vertex AI (Gemini + Model Garden) | Anthropic Claude Platform on AWS | Bedrock (multi-vendor) | Azure AI Foundry |
|---|---|---|---|---|
| Native auth | GCP IAM | AWS IAM | AWS IAM | Azure Entra ID |
| Private networking | VPC Service Controls + PSC | AWS PrivateLink | PrivateLink | Private endpoints |
| Multi-vendor models | Yes — Claude, Llama, Mistral, etc. | Anthropic-only | Yes — Anthropic, Meta, Mistral, etc. | Yes — Anthropic, Mistral, others |
| Audit logging | Cloud Audit Logs | AWS CloudTrail | AWS CloudTrail | Azure Monitor |
| Regional residency | Per-region | Per-region | Per-region | Per-region |
| Customer-managed keys | Cloud KMS / CMEK | KMS | KMS | Key Vault |
16. Further reading
- Vertex AI Generative AI — root docs (redirecting to Agent Platform)
- Gemini Enterprise Agent Platform — new home for Vertex GenAI
- Model Garden — Claude / Llama / Mistral / open catalog
- Locations — regional availability matrix
- Tuning — supervised + preference tuning
- VPC Service Controls for Vertex AI — perimeter setup
- Vertex AI pricing — per-model + per-feature