Settings API (v2 & v3)

Halaman ini merangkum semua settings yang perlu kamu atur untuk memakai Balitech AI Gateway di jalur v2 (Go) dan v3 (Rust). Keduanya 100% kompatibel OpenAI, bedanya hanya backend dan SLA failover.

Ringkas: v2 vs v3

Aspek	v2 (`/v2/`)	v3 (`/v3/`) + `/v1/`
Runtime	Go (`ai-proxy/`)	Rust (`ai-proxy-v3/`)
Route utama	`/v2/chat/completions`, `/v2/messages`, `/v2/responses`, `/v2/batch`, `/v2/models`, `/v2/balance`	`/v3/` dan `/v1/` (alias identik) — plus `/v1/audio/*`, `/v1/voices`, `/v1/bt/models`
Failover	race parallel antar provider + fallback `sonnet4.6 → sonnet4.5`	sama (Rust)
Kelebihan v3	throughput lebih tinggi, backpressure via semaphore, circuit breaker per provider, auto `stream_options.include_usage`	—
Rekomendasi	jalur cadangan / redundansi	jalur utama — pakai ini dulu

Semua contoh di bawah pakai https://balitechsolution.com. Untuk dev lokal: http://localhost:8080 (v2) atau port yang diset PORT.

1. Base URL & versi

https://balitechsolution.com/v2/   # Go proxy
https://balitechsolution.com/v3/   # Rust proxy (utama)
https://balitechsolution.com/v1/   # alias v3 — jangan hardcode v1 kalau mau eksplisit

Cek health tanpa auth:

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

2. Authentication setting

Kedua versi terima salah satu:

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

API key dibuat di console (/api-keys) — satu key bisa dipakai di v2 maupun v3. 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 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/v2/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 v2 & v3 (parity)

Endpoint	v2	v3	Catatan
Chat Completions	`POST /v2/chat/completions`	`POST /v3/chat/completions`	OpenAI-compatible, streaming & non-streaming
Messages (Anthropic)	`POST /v2/messages`	`POST /v3/messages`	`system` string/array, block `tool_use`/`tool_result` auto-convert
Responses	`POST /v2/responses`	`POST /v3/responses`	`input`/`instructions`/`tools` → convert ke chat
Batch	`POST /v2/batch`	`POST /v3/batch`	maks 50 sub-request, `requests[].body` = chat payload
Models	`GET /v2/models`	`GET /v3/models`	hanya model dengan provider aktif
Balance	`GET /v2/balance`	`GET /v3/balance`	cek kuota & wallet
Audio	—	`POST /v1/audio/speech`, `POST /v1/audio/transcriptions`, `GET /v1/voices`	hanya v1/v3 (ElevenLabs + Deepgram)

4.1 Chat Completions settings

# v3
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}'

# v2 — sama, ganti path
curl https://balitechsolution.com/v2/chat/completions \
  -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \
  -d '{"model":"bt/sonnet4.5","messages":[{"role":"user","content":"Halo!"}]}'

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 — v3 (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

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"}]}}]}'
# v2: ganti /v3/batch → /v2/batch

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 → 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

curl https://balitechsolution.com/v3/balance -H "Authorization: Bearer sk-xxx"
curl https://balitechsolution.com/v2/balance -H "Authorization: Bearer sk-xxx"
# {"wallet_balance":50000,"monthly_token_limit":1000000,"monthly_tokens_used":128000,"monthly_tokens_remaining":872000,"unlimited":false}

Skema quota (sama di v2 & v3, storage quotas Asia/Jakarta):

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

Setting	Nilai default	Keterangan
Per-IP burst	500 req	di nginx `ddos-zones`
Concurrent per-IP	100	nginx limit_conn
Per-user RPM	dari `config.RateLimitRPM` (Go) / tanpa limit global di Rust v3 (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` (v2 & v3)

File balitech-website/opencode.json yang di-commit — isi hanya 2 provider ini. 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 },
    "balitech-v2": { "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "https://balitechsolution.com/v2", "apiKey": "sk-db-..." }, "discoverModels": true }
  }
}

cd balitech-website
npx opencode models | grep balitech   # cek discovery
npx opencode run -m balitech-v3/bt/qwen3.8-flash "Halo v3!"
npx opencode run -m balitech-v2/bt/qwen3.8-flash "Halo v2!"

baseURL tanpa trailing slash, apiKey sama untuk v2 & v3.
discoverModels: true auto GET /v3/models & GET /v2/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 — v3 utama
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 }
});

// v2 cadangan — ganti baseURL saja, key & model sama
const v2 = new OpenAI({ baseURL: "https://balitechsolution.com/v2", apiKey: "sk-db-..." });
await v2.chat.completions.create({ model: "bt/sonnet4.5", messages: [{ role: "user", content: "Halo v2!" }] });

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"]
    },
    "balitech-v2": {
      "baseURL": "https://balitechsolution.com/v2",
      "apiKey": "sk-db-...",
      "models": ["bt/qwen3.8-flash", "bt/sonnet4.5"]
    }
  }
}

Catatan Hermes:

baseURL tanpa trailing slash — SDK tambah /chat/completions otomatis.
Header yang dikirim Hermes Authorization: Bearer sk-xxx sudah diterima gateway v2 & v3 (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.
Failover v3→v2 di Hermes: kalau v3 balas 503 server_busy / 429, retry ke balitech-v2 dengan body yang sama — 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 v3 dan v2 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 saja
claude --model bt/sonnet4.5
# v2 cadangan
export ANTHROPIC_BASE_URL="https://balitechsolution.com/v2"
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

# 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!"}]}'

# Sama lewat v2
curl https://balitechsolution.com/v2/messages \
  -H "Authorization: Bearer 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 v2!"}]}'

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.
Untuk fallback, set ANTHROPIC_BASE_URL ke /v3 utama dan siapkan retry ke /v2 kalau butuh — key sama.
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 ganti v2↔v3

Lihat juga Errors dan Balance & Usage.

10. Checklist settings minimal

Dapat sk-xxx dari console → set di Authorization: Bearer / x-api-key atau opencode.json / ANTHROPIC_API_KEY.
Pilih jalur: v3 utama, v2 cadangan — bisa set dua-duanya di opencode.json / Hermes config / Claude Code ANTHROPIC_BASE_URL.
Pakai model bt/ yang ada di GET /v3/models (jangan hardcode provider upstream).
Untuk streaming, set stream:true + stream_options:{"include_usage":true}.
Handle x-fallback-model kalau butuh tahu model yang sebenarnya melayani.
Monitor quota via GET /v3/balance sebelum 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 v2/v3)
Authentication — header & rate limit
Chat Completions · Messages · Responses · Batch · Audio · Models · Streaming
Arsitektur & Cara Kerja — diagram nginx → ai-proxy-v3 / ai-proxy → pool provider (incl. 9Router) + integrasi OpenCode/Hermes/Claude Code