Settings API
Halaman ini merangkum semua settings yang perlu kamu atur untuk memakai Balitech AI Gateway (Rust). Kompatibel OpenAI, dengan failover antar provider, backpressure via semaphore, circuit breaker per provider, dan auto stream_options.include_usage.
Route utama: /v3/* dan /v1/* (alias identik) — plus /v1/audio/*, /v1/voices, /v1/bt/models.
Semua contoh di bawah pakai
https://balitechsolution.com. Untuk dev lokal:http://localhost:8080(atau port yang disetPORT).
1. Base URL & versi
https://balitechsolution.com/v3/ # Rust proxy (utama)https://balitechsolution.com/v1/ # alias v3 (juga tersedia di /api/v1/)Cek health tanpa auth:
curl https://balitechsolution.com/v3/health# {"status":"ok","service":"ai-proxy-v3","version":"v3"}2. Authentication setting
Gateway menerima salah satu:
Authorization: Bearer sk-xxx# ataux-api-key: sk-xxxAPI key dibuat di console (/api-keys) — satu key bisa dipakai di semua endpoint. Validasi mengecek status=active, expires_at, dan plan.
3. Model setting (bt/)
Semua model diakses dengan prefix bt/:
bt/deepseek-v4.1-flash— model termurah, tetap wajib plan aktifbt/sonnet4.5,bt/sonnet4.6,bt/sonnet5,bt/deepseek-v4-pro,bt/gemini-image, dll — premium (butuh plan aktif; tier free lama nonaktif)
Slug di URL/path tanpa prefix di DB — proxy otomatis normalisasi:
| Alias yang kamu kirim | Slug canonical di DB |
|---|---|
bt/claude-sonnet-4.5, bt/claude-sonnet-4-5, oa-claude-sonnet-4.5 | sonnet4.5 |
bt/claude-sonnet-4.6, bt/claude-sonnet-4-6 | sonnet4.6 |
bt/claude-sonnet-5, bt/anthropic-claude-sonnet-5 | sonnet5 |
bt/agnes-2-flash, bt/qwen3.8-flash | sesuai slug agnes-2-flash, qwen3.8-flash |
Fallback otomatis: kalau sonnet4.6 gagal di semua provider atau plan kamu tidak mengizinkan, proxy akan fallback ke sonnet4.5 (free) dan balas header x-fallback-model: bt/sonnet4.5. Usage/quota dicatat atas model fallback (billing jujur).
List model live:
curl https://balitechsolution.com/v3/models -H "Authorization: Bearer sk-xxx"curl https://balitechsolution.com/v1/bt/models -H "Authorization: Bearer sk-xxx" # + harga IDR/1M tokens4. Endpoint settings
| Endpoint | Path | Catatan |
|---|---|---|
| Chat Completions | POST /v3/chat/completions | OpenAI-compatible, streaming & non-streaming |
| Messages (Anthropic) | POST /v3/messages | system string/array, block tool_use/tool_result auto-convert |
| Responses | POST /v3/responses | input/instructions/tools → convert ke chat |
| Batch | POST /v3/batch | maks 50 sub-request, requests[].body = chat payload |
| Models | GET /v3/models | hanya model dengan provider aktif |
| Balance | GET /v3/balance | cek kuota & wallet |
| Audio | POST /v1/audio/speech, POST /v1/audio/transcriptions, GET /v1/voices | ElevenLabs + Deepgram |
Semua path /v3/... juga tersedia sebagai /v1/....
4.1 Chat Completions settings
curl https://balitechsolution.com/v3/chat/completions \ -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \ -d '{"model":"bt/qwen3.8-flash","messages":[{"role":"user","content":"Halo!"}],"temperature":0.7,"max_tokens":2048}'Param umum: model (required, prefix bt/), messages[], temperature, top_p, max_tokens (default 8192), stream (bool), tools/tool_choice, stream_options: {"include_usage": true} (auto-injeksi kalau stream:true).
4.2 Messages & Responses settings
# Messages — Anthropic-native, tool callingcurl https://balitechsolution.com/v3/messages \ -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \ -d '{"model":"bt/sonnet4.5","system":"Kamu asisten.","messages":[{"role":"user","content":"Halo!"}],"max_tokens":2048,"tools":[{"name":"get_weather","description":"...","input_schema":{"type":"object"}}]}'
# Responses — dipakai Codex/Codex CLIcurl https://balitechsolution.com/v3/responses \ -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \ -d '{"model":"bt/sonnet4.5","instructions":"Kamu asisten.","input":"Halo!","max_output_tokens":2048,"tools":[{"type":"function","name":"get_weather","description":"...","parameters":{"type":"object"}}]}'Kedua endpoint otomatis translate tool format (Anthropic input_schema ↔ OpenAI parameters) dan tool_result ↔ role: tool.
4.3 Batch settings
curl https://balitechsolution.com/v3/batch \ -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \ -d '{"requests":[{"custom_id":"req-1","body":{"model":"bt/qwen3.8-flash","messages":[{"role":"user","content":"Halo!"}]}},{"custom_id":"req-2","body":{"model":"bt/sonnet4.5","messages":[{"role":"user","content":"Ceritakan Bali"}]}}]}'Limit: 50 sub-request per batch, tiap sub-request failover independen.
5. Streaming settings
curl https://balitechsolution.com/v3/chat/completions \ -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \ -d '{"model":"bt/qwen3.8-flash","messages":[{"role":"user","content":"Cerita panjang"}],"stream":true,"stream_options":{"include_usage":true}}'stream: true→ SSEtext/event-streamstream_options.include_usagewajib untuk dapatusagedi chunk terakhir — proxy auto-inject kalau kamu lupa, tapi set eksplisit lebih aman.- Event:
data: {"choices":[{"delta":{"content":"..."}}]}…data: [DONE] - Untuk
/v3/messagesdan/v3/responsesyang stream, proxy menerjemahkan SSE Anthropic → OpenAI chunk secara transparan.
6. Quota & balance settings
curl https://balitechsolution.com/v3/balance -H "Authorization: Bearer sk-xxx"# {"wallet_balance":50000,"quota_period":"monthly","quota_limit":1000000,"quota_used":128000,"quota_remaining":872000,"unlimited":false}Field kuota utama adalah quota_period, quota_limit, quota_used, dan quota_remaining. Field lama monthly_* tetap dikirim untuk kompatibilitas dan mengikuti periode aktif yang sama.
Skema quota (storage quotas Asia/Jakarta):
- Beli Token Custom: grant aktif ditumpuk; pemakaian dan sisa mengikuti siklus
fortnightyang sama dengan validasi API. - Premium bulanan (lama): satu pool
monthly_tokensper user/bulan. - Premium per-model harian (baru, mis. Starter Monthly):
daily_model_tokens:{slug}— 50M/model/hari, tiap model bucket terpisah. - Premium butuh plan aktif (
api_subscriptionsstatus active) — bukan cuma saldo. Grant tidak bisa dipakai untuk model selaindeepseek-v4.1-flash.
Kalau quota habis, proxy balas 429 monthly_limit_exceeded / grant_limit_exceeded / daily_model_limit_exceeded atau fallback ke model sekeluarga kalau tersedia.
7. Rate limit & backpressure settings
| Setting | Nilai default | Keterangan |
|---|---|---|
| Per-IP burst | 500 req | di nginx ddos-zones |
| Concurrent per-IP | 100 | nginx limit_conn |
| Per-user RPM | tanpa limit global (per-model quota) | balas 429 rate_limit_exceeded |
| Max concurrent (proxy) | 200 (env MAX_CONCURRENT) | semaphore — kalau penuh balas 503 server_busy dalam ACQUIRE_TIMEOUT_MS (3000ms) |
| Max body | 10 MB | 413 kalau melebihi |
| Body timeout | 20s (HTTP_TIMEOUT) | skip provider lambat via CIRCUIT_SKIP 20s |
Header fallback: x-fallback-model: bt/sonnet4.5 menandakan model yang sebenarnya melayani bukan yang diminta.
8. opencode.json untuk project balitech-website
File balitech-website/opencode.json yang di-commit — isi hanya provider Balitech. router9-docker tidak dipakai di project.
Lihat panduan lengkap & copy-paste di Getting Started — sama persis, tidak perlu duplikat di sini.
Ringkas:
{ "$schema": "https://opencode.ai/config.json", "model": "balitech-v3/bt/sonnet4.5", "small_model": "balitech-v3/bt/qwen3.8-flash", "provider": { "balitech-v3": { "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "https://balitechsolution.com/v3", "apiKey": "sk-db-..." }, "discoverModels": true } }}cd balitech-websitenpx opencode models | grep balitech # cek discoverynpx opencode run -m balitech-v3/bt/qwen3.8-flash "Halo v3!"baseURLtanpa trailing slash,apiKeydibuat di console.discoverModels: trueautoGET /v3/models.- Jangan set
modelkerouter9-docker/*di repo public.
8.1 Hermes setting (OpenAI-compatible)
Hermes (dan tool OpenAI-compatible lain seperti Continue, Cline, Kilo Code) tinggal arahkan baseURL ke gateway Balitech — format request tetap OpenAI standar.
// Hermes / OpenAI SDKimport OpenAI from "openai";const v3 = new OpenAI({ baseURL: "https://balitechsolution.com/v3", apiKey: "sk-db-..." });await v3.chat.completions.create({ model: "bt/qwen3.8-flash", messages: [{ role: "user", content: "Halo Hermes!" }], stream: true, stream_options: { include_usage: true }});Config Hermes (hermes.json / .hermes/config.json — sesuaikan dengan versi Hermes kamu):
{ "providers": { "balitech-v3": { "baseURL": "https://balitechsolution.com/v3", "apiKey": "sk-db-...", "models": ["bt/qwen3.8-flash", "bt/sonnet4.5", "bt/sonnet5"] } }}Catatan Hermes:
baseURLtanpa trailing slash — SDK tambah/chat/completionsotomatis.- Header yang dikirim Hermes
Authorization: Bearer sk-xxxsudah diterima gateway (alternatifx-api-key: sk-xxxjuga bisa). - Untuk streaming, Hermes cukup set
stream: true— gateway auto-injectstream_options.include_usagekalau lupa, tapi set eksplisit lebih aman supayausagemuncul di chunk terakhir. - Kalau gateway balas
503 server_busy/429, retry dengan backoff — modelbt/tidak perlu diubah.
8.2 Claude Code setting (Anthropic Messages API)
Claude Code berbicara ke Anthropic Messages API (POST /messages), bukan OpenAI. Gateway sudah handle itu secara native — mereka menerjemahkan system (string/array), tool_use/tool_result blocks, dan input_schema ↔ parameters secara transparan. Jadi Claude Code bisa diarahkan langsung ke Balitech tanpa proxy tambahan.
Opsi A — environment variable (paling simpel)
export ANTHROPIC_BASE_URL="https://balitechsolution.com/v3"export ANTHROPIC_API_KEY="sk-db-..."# atau: export ANTHROPIC_AUTH_TOKEN="sk-db-..." # alias, sama sajaclaude --model bt/sonnet4.5Opsi B — settings.json Claude Code (~/.claude/settings.json)
{ "env": { "ANTHROPIC_BASE_URL": "https://balitechsolution.com/v3", "ANTHROPIC_API_KEY": "sk-db-..." }}Opsi C — project local (.claude/settings.local.json)
{ "env": { "ANTHROPIC_BASE_URL": "https://balitechsolution.com/v3", "ANTHROPIC_API_KEY": "sk-db-..." }, "model": "bt/sonnet4.5"}Verifikasi Claude Code
# Test langsung tanpa Claude Code — pakai curl Anthropic-nativecurl https://balitechsolution.com/v3/messages \ -H "x-api-key: sk-db-..." -H "Content-Type: application/json" \ -H "anthropic-version: 2023-06-01" \ -d '{"model":"bt/sonnet4.5","max_tokens":2048,"messages":[{"role":"user","content":"Halo Claude Code!"}]}'Catatan Claude Code:
- Gateway terima dua header auth:
x-api-key: sk-xxx(Anthropic native) danAuthorization: Bearer sk-xxx(OpenAI style) — Claude Code biasanya kirimx-api-key. - Model tetap prefix
bt/(bt/sonnet4.5,bt/sonnet5,bt/qwen3.8-flash) — jangan pakai slug Anthropic asli (claude-sonnet-4-5-20250929). Normalisasi di gateway yang urus (claude-sonnet-4.5→sonnet4.5). - Tool calling / MCP tetap jalan:
tools: [{name, description, input_schema}]dantool_resultblocks di-convert ke OpenAItool_calls/role: toolbila upstream provider-nya OpenAI, dan sebaliknya. - Lihat juga Arsitektur & Cara Kerja untuk diagram nginx → ai-proxy → provider pool.
9. Error settings (mapping)
| HTTP | type | Kapan muncul | Saran settings |
|---|---|---|---|
| 401 | authentication_error | key kosong / salah / expired | cek header Authorization / x-api-key |
| 403 | forbidden / model_not_allowed / model_not_available | plan tidak mengizinkan model premium itu | upgrade plan |
| 404 | model_not_found | slug tidak ada di katalog | cek GET /v3/models |
| 429 | monthly_limit_exceeded | pool bulanan habis | top-up / tunggu bulan depan |
| 429 | daily_model_limit_exceeded | kuota per-model harian habis | pakai model lain atau tunggu besok |
| 429 | batch_too_large | >50 sub-request | pecah batch |
| 503 | server_busy | semaphore penuh | retry dengan backoff |
| 503 | upstream_error / no_providers | semua provider gagal | fallback ke bt/sonnet4.5 atau retry dengan backoff |
Lihat juga Errors dan Balance & Usage.
10. Checklist settings minimal
- Dapat
sk-xxxdari console → set diAuthorization: Bearer/x-api-keyatauopencode.json/ANTHROPIC_API_KEY. - Arahkan
baseURLkehttps://balitechsolution.com/v3(atau alias/v1) diopencode.json/ Hermes config / Claude CodeANTHROPIC_BASE_URL. - Pakai model
bt/yang ada diGET /v3/models(jangan hardcode provider upstream). - Untuk streaming, set
stream:true+stream_options:{"include_usage":true}. - Handle
x-fallback-modelkalau butuh tahu model yang sebenarnya melayani. - Monitor quota via
GET /v3/balancesebelum batch besar. - Hermes →
baseURL https://balitechsolution.com/v3(OpenAI SDK); Claude Code →ANTHROPIC_BASE_URL https://balitechsolution.com/v3(Messages API).
Lihat juga
- Getting Started — request pertama (OpenCode)
- Authentication — header & rate limit
- Chat Completions · Messages · Responses · Batch · Audio · Models · Streaming
- Arsitektur & Cara Kerja — diagram nginx → ai-proxy-v3 → pool provider (incl. 9Router) + integrasi OpenCode/Hermes/Claude Code