API Reference

Authentication

One header. Get sk_… from admin: Dashboard → Projects → Generate.

X-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

401 = missing, 403 = invalid. Keys are project-scoped.

Lightweight vault. Validates sk_…, mints 55m-cached ya29 from the stored SA, logs model, and returns the token JSON. No AI call.

curl -X POST http://YOUR_SERVER:8001/v1/json \
  -H "X-API-Key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-1.5-flash"}'
# also: POST /v1/json/gemini-1.5-flash  — same

{
  "json_type": "token",
  "model": "gemini-1.5-flash",
  "project": "acme",
  "access_token": "ya29....",
  "expires_in": 3600
}

Full proxy. Broker does the Vertex call for you and returns the AI response. Same X-API-Key + model allowlist, but broker handles auth + proxy.

curl -X POST http://YOUR_SERVER:8001/v1/gemini/gemini-1.5-flash:generateContent \
  -H "X-API-Key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Hello"}]}]}'

{"candidates":[{"content":{"parts":[{"text":"Hello!"}]}}]}

Same as JSON server, kept for backwards compat. Use /v1/json for new code.

curl -X POST http://YOUR_SERVER:8001/v1/token \
  -H "X-API-Key: sk_..." \
  -d '{"model":"gemini-1.5-flash"}'

Example — add to your code

Get token, then call Vertex directly. No proxy needed.

import requests, os

BROKER = os.getenv("BROKER_URL")  # http://YOUR_SERVER:8001
KEY = os.getenv("BROKER_API_KEY") # sk_...

# 1) Get token JSON
tok = requests.post(f"{BROKER}/v1/token",
  headers={"X-API-Key": KEY},
  json={"model":"gemini-1.5-flash"}).json()
access = tok["access_token"]

# 2) Call Gemini directly
r = requests.post(
  f"https://us-central1-aiplatform.googleapis.com/v1/projects/{tok['project_id']}/locations/us-central1/publishers/google/models/gemini-1.5-flash:generateContent",
  headers={"Authorization": f"Bearer {access}"},
  json={"contents":[{"role":"user","parts":[{"text":"Hello"}]}]})
print(r.json()["candidates"][0]["content"]["parts"][0]["text"])

const tok = await fetch(`${process.env.BROKER_URL}/v1/token`, {
  method:"POST",
  headers:{"X-API-Key": process.env.BROKER_API_KEY, "Content-Type":"application/json"},
  body: JSON.stringify({model:"gemini-1.5-flash"})
}).then(r=>r.json());

const res = await fetch(
  `https://us-central1-aiplatform.googleapis.com/v1/projects/${tok.project_id}/locations/us-central1/publishers/google/models/gemini-1.5-flash:generateContent`,
  {method:"POST", headers:{Authorization:`Bearer ${tok.access_token}`},
   body: JSON.stringify({contents:[{role:"user", parts:[{text:"Hello"}]}]})}
);
console.log((await res.json()).candidates[0].content.parts[0].text);

BROKER_URL=http://YOUR_SERVER:8001
BROKER_API_KEY=sk_xxxxxxxxxxxxxxxx
# that's it — no SA JSON in your repo

Errors