Skip to content

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 diset PORT).

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:

Terminal window
curl https://balitechsolution.com/v3/health
# {"status":"ok","service":"ai-proxy-v3","version":"v3"}

2. Authentication setting

Gateway menerima salah satu:

Terminal window
Authorization: Bearer sk-xxx
# atau
x-api-key: sk-xxx

API 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 aktif
  • bt/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 kirimSlug canonical di DB
bt/claude-sonnet-4.5, bt/claude-sonnet-4-5, oa-claude-sonnet-4.5sonnet4.5
bt/claude-sonnet-4.6, bt/claude-sonnet-4-6sonnet4.6
bt/claude-sonnet-5, bt/anthropic-claude-sonnet-5sonnet5
bt/agnes-2-flash, bt/qwen3.8-flashsesuai 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:

Terminal window
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 tokens

4. Endpoint settings

EndpointPathCatatan
Chat CompletionsPOST /v3/chat/completionsOpenAI-compatible, streaming & non-streaming
Messages (Anthropic)POST /v3/messagessystem string/array, block tool_use/tool_result auto-convert
ResponsesPOST /v3/responsesinput/instructions/tools → convert ke chat
BatchPOST /v3/batchmaks 50 sub-request, requests[].body = chat payload
ModelsGET /v3/modelshanya model dengan provider aktif
BalanceGET /v3/balancecek kuota & wallet
AudioPOST /v1/audio/speech, POST /v1/audio/transcriptions, GET /v1/voicesElevenLabs + Deepgram

Semua path /v3/... juga tersedia sebagai /v1/....

4.1 Chat Completions settings

Terminal window
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

Terminal window
# Messages — Anthropic-native, tool calling
curl 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 CLI
curl 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

Terminal window
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

Terminal window
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 → SSE text/event-stream
  • stream_options.include_usage wajib untuk dapat usage di chunk terakhir — proxy auto-inject kalau kamu lupa, tapi set eksplisit lebih aman.
  • Event: data: {"choices":[{"delta":{"content":"..."}}]} … data: [DONE]
  • Untuk /v3/messages dan /v3/responses yang stream, proxy menerjemahkan SSE Anthropic → OpenAI chunk secara transparan.

6. Quota & balance settings

Terminal window
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 fortnight yang sama dengan validasi API.
  • Premium bulanan (lama): satu pool monthly_tokens per 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_subscriptions status active) — bukan cuma saldo. Grant tidak bisa dipakai untuk model selain deepseek-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

SettingNilai defaultKeterangan
Per-IP burst500 reqdi nginx ddos-zones
Concurrent per-IP100nginx limit_conn
Per-user RPMtanpa 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 body10 MB413 kalau melebihi
Body timeout20s (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 }
}
}
Terminal window
cd balitech-website
npx opencode models | grep balitech # cek discovery
npx opencode run -m balitech-v3/bt/qwen3.8-flash "Halo v3!"
  • baseURL tanpa trailing slash, apiKey dibuat di console.
  • discoverModels: true auto GET /v3/models.
  • Jangan set model ke router9-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 SDK
import 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:

  • baseURL tanpa trailing slash — SDK tambah /chat/completions otomatis.
  • Header yang dikirim Hermes Authorization: Bearer sk-xxx sudah diterima gateway (alternatif x-api-key: sk-xxx juga bisa).
  • Untuk streaming, Hermes cukup set stream: true — gateway auto-inject stream_options.include_usage kalau lupa, tapi set eksplisit lebih aman supaya usage muncul di chunk terakhir.
  • Kalau gateway balas 503 server_busy / 429, retry dengan backoff — model bt/ 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)

Terminal window
export ANTHROPIC_BASE_URL="https://balitechsolution.com/v3"
export ANTHROPIC_API_KEY="sk-db-..."
# atau: export ANTHROPIC_AUTH_TOKEN="sk-db-..." # alias, sama saja
claude --model bt/sonnet4.5

Opsi 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

Terminal window
# Test langsung tanpa Claude Code — pakai curl Anthropic-native
curl 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) dan Authorization: Bearer sk-xxx (OpenAI style) — Claude Code biasanya kirim x-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}] dan tool_result blocks di-convert ke OpenAI tool_calls/role: tool bila upstream provider-nya OpenAI, dan sebaliknya.
  • Lihat juga Arsitektur & Cara Kerja untuk diagram nginx → ai-proxy → provider pool.

9. Error settings (mapping)

HTTPtypeKapan munculSaran settings
401authentication_errorkey kosong / salah / expiredcek header Authorization / x-api-key
403forbidden / model_not_allowed / model_not_availableplan tidak mengizinkan model premium ituupgrade plan
404model_not_foundslug tidak ada di katalogcek GET /v3/models
429monthly_limit_exceededpool bulanan habistop-up / tunggu bulan depan
429daily_model_limit_exceededkuota per-model harian habispakai model lain atau tunggu besok
429batch_too_large>50 sub-requestpecah batch
503server_busysemaphore penuhretry dengan backoff
503upstream_error / no_providerssemua provider gagalfallback ke bt/sonnet4.5 atau retry dengan backoff

Lihat juga Errors dan Balance & Usage.

10. Checklist settings minimal

  1. Dapat sk-xxx dari console → set di Authorization: Bearer / x-api-key atau opencode.json / ANTHROPIC_API_KEY.
  2. Arahkan baseURL ke https://balitechsolution.com/v3 (atau alias /v1) di opencode.json / Hermes config / Claude Code ANTHROPIC_BASE_URL.
  3. Pakai model bt/ yang ada di GET /v3/models (jangan hardcode provider upstream).
  4. Untuk streaming, set stream:true + stream_options:{"include_usage":true}.
  5. Handle x-fallback-model kalau butuh tahu model yang sebenarnya melayani.
  6. Monitor quota via GET /v3/balance sebelum batch besar.
  7. Hermes → baseURL https://balitechsolution.com/v3 (OpenAI SDK); Claude Code → ANTHROPIC_BASE_URL https://balitechsolution.com/v3 (Messages API).

Lihat juga