How to Use Vertex AI API: A Developer's Guide

Google's Vertex AI API gives you programmatic access to Google's machine learning models — including Gemini, PaLM, and custom-trained models — through a unified REST and gRPC interface. Using it means enabling the API on a Google Cloud project, setting up authentication with a service account, and then sending HTTP requests to the correct regional endpoint with your project ID and model name.

This guide walks through the full setup so you can go from a blank Google Cloud project to a working API call, plus what to watch out for around authentication, quotas, and pricing.

Step 1: Set Up a Google Cloud Project

Vertex AI is not a standalone product — it lives inside Google Cloud Platform (GCP), so you need a GCP project first.

1. Go to the Google Cloud Console and create a new project, or select an existing one.
2. Enable billing for the project. Vertex AI is a paid service; there's no way around linking a billing account, even for small test calls.
3. In the search bar, look for "Vertex AI API" and click Enable.

Enabling the API can take a minute to propagate. If your first request fails with a "API not enabled" error, wait and retry.

Step 2: Authenticate with a Service Account

Vertex AI uses Google Cloud's IAM system rather than a simple API key. The standard approach is a service account with the right role attached.

gcloud iam service-accounts create vertex-caller \
  --display-name="Vertex AI Caller"

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:vertex-caller@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

gcloud iam service-accounts keys create key.json \
  --iam-account=vertex-caller@YOUR_PROJECT_ID.iam.gserviceaccount.com

This downloads a key.json credentials file. For local testing, point the Google Cloud SDK at it:

export GOOGLE_APPLICATION_CREDENTIALS="./key.json"
gcloud auth application-default login

In production, avoid shipping this JSON file with your app. Use workload identity federation on GCP compute, or a secrets manager if you're deploying elsewhere.

Step 3: Get an Access Token

Unlike simple API-key auth, Vertex AI requests need a short-lived OAuth2 bearer token generated from your service account credentials.

ACCESS_TOKEN=$(gcloud auth application-default print-access-token)

This token expires (usually within an hour), so any long-running service needs to refresh it periodically — either by shelling out to gcloud or using one of Google's client libraries, which handle refresh automatically.

Step 4: Call the API

Vertex AI endpoints are regional. You'll need your project ID, a region (like us-central1), and the model you want to call. Here's a basic call to a Gemini model:

curl -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://us-central1-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/publishers/google/models/gemini-1.5-flash:generateContent" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{ "text": "Summarize the plot of Frankenstein in two sentences." }]
    }]
  }'

The response comes back as JSON with the generated content nested under candidates. For streaming responses, swap generateContent for streamGenerateContent and read the response as newline-delimited JSON chunks.

Using a Client Library Instead of Raw REST

Google publishes official SDKs for Python, Node.js, Java, and Go that wrap authentication and request formatting:

const { VertexAI } = require('@google-cloud/vertexai');

const vertexAI = new VertexAI({ project: 'YOUR_PROJECT_ID', location: 'us-central1' });
const model = vertexAI.getGenerativeModel({ model: 'gemini-1.5-flash' });

const result = await model.generateContent('Explain quicksort in one paragraph.');
console.log(result.response.candidates[0].content.parts[0].text);

The SDK handles token refresh and request retries, which saves you from reimplementing that logic yourself.

Common Issues When Using Vertex AI API

• 403 Permission Denied: usually means the service account is missing the roles/aiplatform.user role, or billing isn't enabled.
• 404 Model Not Found: the model name or region doesn't match — not every model is available in every region.
• Quota exceeded: Vertex AI enforces per-project rate limits by default; request a quota increase in the console if you're scaling up.
• Token expiry mid-session: if you're building a long-running server, don't cache the bearer token indefinitely — refresh it before it expires.

When You Just Need a Simple API, Not GCP Plumbing

If your actual goal is "call a capable AI model over HTTP with an API key," the GCP setup above — project creation, IAM roles, OAuth token refresh, regional endpoints — is a lot of infrastructure to maintain just to send a chat completion.

If you already have Claude access through a subscription and want the same simplicity — a single API key, streaming responses, and usage metadata, without any of the IAM overhead — SubToAPI turns that access into a standard HTTPS API. You get an sub_live_... key and call it like any other REST API:

curl https://api.subtoapi.app/v1/messages \
  -H "Authorization: Bearer $SUBTOAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "Explain quicksort in one paragraph." }]
  }'

No service accounts, no OAuth token refresh, no regional endpoint juggling. Check the quickstart guide or the messages docs to see the full request format, and streaming docs if you need token-by-token output. Plans start at €9/month with a free trial — see pricing for details.

Questions

Do I need a Google Cloud billing account to use Vertex AI? Yes. Vertex AI requires an active billing account linked to your project, even if you're only running a handful of test requests during development.

Can I use a simple API key instead of OAuth tokens with Vertex AI? No, Vertex AI requires OAuth2 bearer tokens generated from service account credentials or workload identity — there's no static API key option like some other AI providers offer.

Why does my Vertex AI request return a 404 for a model that exists? Models are only available in specific regions. Double-check that the model name in your request URL matches one that's actually deployed in the region you specified.