Quick Start: Google Gemini
Run these examples on a server or your local development machine. Keep service and provider keys out of public browser bundles.
1. Choose your region and create a key
Choose EU or US in the docs region selector. Accounts and keys are separate in each region. Sign up at Register in your chosen region and confirm the verification email; until then key creation and proxy requests return 403 Email Verification Required. Create an active Makas key in API Keys. The full mks_ token is shown once; a preview is only an identifier. If you no longer have the full key, create a replacement and revoke the old key when appropriate.
Your Makas key identifies the regional account; your provider key authenticates and pays the upstream provider. Stored provider keys are disabled for the first launch. The region selector changes displayed and copied URLs together.
2. Prepare your language and send a request
Choose a language below. Replace the clearly labelled shell placeholders with your own keys on your local machine. These complete examples each make one bounded request; model access depends on your provider account.
- Python
- TypeScript
- cURL
Python
Use Python 3.13. Prepare the runtime (the example uses only the standard library):
python --version
Set credentials in the same POSIX shell, replacing both placeholders:
export MAKAS_API_KEY='replace-with-your-full-makas-key'
export GOOGLE_API_KEY='replace-with-your-provider-key'
Save this complete example as example.py:
import json
import os
import urllib.request
request = urllib.request.Request(
"https://eu.makas.ai/proxy/google/v1beta/models/gemini-3.8-flash:generateContent",
data=json.dumps({"contents": [{"parts": [{"text": "Say hello"}]}],
"generationConfig": {"maxOutputTokens": 64}}).encode(),
headers={"Content-Type": "application/json", "Makas-Api-Key": os.environ["MAKAS_API_KEY"],
"X-Goog-Api-Key": os.environ["GOOGLE_API_KEY"]})
with urllib.request.urlopen(request, timeout=30) as response:
data = json.load(response)
print("".join(part.get("text", "") for part in data["candidates"][0]["content"]["parts"]))
print("Routed:", response.headers.get("Makas-Was-Routed"))
Run it in the same shell:
python example.py
TypeScript
Use Node 22+. In a working directory, install the pinned runtime and dependencies:
node --version
npm init -y
npm pkg set type=module
npm install tsx@4.23.15 typescript@7.0.2
Set credentials in the same POSIX shell, replacing both placeholders:
export MAKAS_API_KEY='replace-with-your-full-makas-key'
export GOOGLE_API_KEY='replace-with-your-provider-key'
Save this complete example as example.ts:
const response = await fetch(
"https://eu.makas.ai/proxy/google/v1beta/models/gemini-3.8-flash:generateContent", {
method: "POST", signal: AbortSignal.timeout(30000),
headers: {"Content-Type": "application/json", "Makas-Api-Key": process.env.MAKAS_API_KEY!,
"X-Goog-Api-Key": process.env.GOOGLE_API_KEY!},
body: JSON.stringify({contents: [{parts: [{text: "Say hello"}]}],
generationConfig: {maxOutputTokens: 64}}),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
console.log(data.candidates[0].content.parts.map((part: {text?: string}) => part.text ?? "").join(""));
console.log("Routed:", response.headers.get("Makas-Was-Routed"));
export {};
Run it in the same shell:
npx tsx example.ts
cURL
Use a POSIX shell and cURL 7.76+ (for --fail-with-body). Check your installed version:
curl --version
Set credentials in the same shell, replacing both placeholders:
export MAKAS_API_KEY='replace-with-your-full-makas-key'
export GOOGLE_API_KEY='replace-with-your-provider-key'
Copy and run this complete request in that shell:
curl --fail-with-body --silent --show-error --max-time 30 -i "https://eu.makas.ai/proxy/google/v1beta/models/gemini-3.8-flash:generateContent" \
-H "Content-Type: application/json" \
-H "Makas-Api-Key: $MAKAS_API_KEY" \
-H "X-Goog-Api-Key: $GOOGLE_API_KEY" \
--data '{"contents":[{"parts":[{"text":"Say hello"}]}],"generationConfig":{"maxOutputTokens":64}}'
Representative response
This is an illustrative response shape, not an exact generated answer or guaranteed token count. The examples above extract the text from the provider-native structure.
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"text": "Hello!"
}
]
}
}
],
"usageMetadata": {
"promptTokenCount": 12,
"candidatesTokenCount": 4,
"totalTokenCount": 16
}
}
3. Verify the result in Request Logs
For buffered inference, inspect the HTTP status and conditional Makas-Was-Routed, Makas-Model-Requested, Makas-Model-Used and Makas-Provider-Used headers. Cost and savings require usage and known pricing; rule and timing fields depend on the path. Missing values are allowed. A successful request may stay on the requested model and save nothing.
Open Request Logs in the same region. The examples print a bounded response and representative metadata; generated text and savings vary. For streams, initial HTTP 200 is not terminal success: wait for completion and check final usage, cost and incomplete outcomes in Request Logs. See response headers.
Troubleshooting
- 401: check the full
MAKAS_API_KEY, its expiry/revocation, the selected region and exactly oneMakas-Api-Keyheader. A masked preview cannot authenticate. - 403
Email Verification Required: confirm the verification email for this regional account, then retry. - 400
PROXY_API_KEY_ERROR: supply the matching provider credential in its native header. - Provider auth/model error: confirm provider account access, billing and model availability. Local contract tests do not establish live vendor access.
- 429: branch on the problem
errorCodewhen present, otherwise ontype. Burst limits can includeRetry-After; exhausted monthly quotas (TOKEN_QUOTA_EXCEEDED,REQUEST_QUOTA_EXCEEDED) and spending caps (type: urn:makas:error:cost-cap-exceeded, noerrorCode) need a reset or limit change, not a retry loop. - 5xx: inspect status, correlation ID and Request Logs; use bounded retries appropriate to the operation.
- Success without routing: check enabled groups, tier, confidence, capabilities and conversation continuity. Same-provider routing does not guarantee a model change.