Developer Reference
Two separate ways to use the broker. Pick one — don’t mix.
All endpoints are relative to your broker host.
http://YOUR_SERVER:8001
In your app .env: BROKER_URL=http://YOUR_SERVER:8001 + BROKER_API_KEY=sk_…
One header for both A and B. No OAuth in your code.
X-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
401 = missing, 403 = invalid. Keys are project-scoped, rate-limited.
Get a token JSON only. You call Vertex yourself. Logged as /v1/json with model.
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
import requests, os
BROKER=os.getenv("BROKER_URL")
KEY=os.getenv("BROKER_API_KEY")
tok=requests.post(f"{BROKER}/v1/json", headers={"X-API-Key":KEY}, json={"model":"gemini-1.5-flash"}).json()
# tok = {"access_token":"ya29…","model":"gemini-1.5-flash","project":"acme",...}
import requests as req
req.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 {tok['access_token']}"},
json={"contents":[{"role":"user","parts":[{"text":"Hello"}]}]})
{"json_type":"token","model":"gemini-1.5-flash","access_token":"ya29...","expires_in":3600}
Broker does the Vertex call and returns the AI response. One call from your code.
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"}]}]}'
import requests, os
r=requests.post(f"{os.getenv('BROKER_URL')}/v1/gemini/gemini-1.5-flash:generateContent",
headers={"X-API-Key": os.getenv("BROKER_API_KEY")},
json={"contents":[{"role":"user","parts":[{"text":"Hello"}]}]})
print(r.json()["candidates"][0]["content"]["parts"][0]["text"])
{"candidates":[{"content":{"parts":[{"text":"Hello!"}]}}]}
curl http://YOUR_SERVER:8001/v1/models -H "X-API-Key: sk_..."