Dokumentasi API
API kompatibel OpenAI untuk model chat open-weight, ditagih per token dalam rupiah dari saldo prabayar.
Mulai cepat
SDK atau HTTP client OpenAI apa pun bisa dipakai. Arahkan ke base URL di bawah, buat API key di halaman API key, lalu kirim request.
Base URL
https://ai.lokalbdg.com/v1curl https://ai.lokalbdg.com/v1/chat/completions \
-H "Authorization: Bearer $LOKALBDG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4.1-flash",
"messages": [{"role": "user", "content": "Halo! Apa kabar?"}]
}'Agent dan harness
Konfigurasi siap tempel untuk agent populer. Semua memakai API Chat Completions; jangan pilih mode Responses atau Anthropic Messages.
Langkah 1: export LOKALBDG_API_KEY="sk-..."
{
models: {
mode: "merge",
providers: {
lokalbdg: {
baseUrl: "https://ai.lokalbdg.com/v1",
apiKey: "${LOKALBDG_API_KEY}",
api: "openai-completions",
models: [{ id: "deepseek-v4.1-flash", name: "DeepSeek V4.1 Flash" }],
},
},
},
}Pilih model: openclaw models set lokalbdg/deepseek-v4.1-flash
Autentikasi
Kirim key sebagai Authorization: Bearer sk-.... Key hanya ditampilkan sekali saat dibuat; kami hanya menyimpan hash-nya. Key bisa diberi batas belanja harian dan bulanan serta daftar model yang diizinkan, dan bisa dirotasi atau dicabut kapan saja (key yang dicabut berhenti bekerja dalam beberapa detik).
Chat completions
POST https://ai.lokalbdg.com/v1/chat/completions mengikuti format request dan respons OpenAI Chat Completions. model dan messages wajib diisi. Parameter standar seperti temperature, top_p, max_tokens / max_completion_tokens, stop, seed, response_format, tools, dan tool_choice diteruskan ke provider model. Parameter mana yang dipatuhi tergantung modelnya.
model pada respons adalah ID model gateway yang kamu minta. usage memuat prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details.cached_tokens dan, untuk model reasoning, completion_tokens_details.reasoning_tokens. Model reasoning juga bisa mengembalikan reasoning_content di samping content. Setiap respons membawa header x-request-id; sertakan saat menghubungi dukungan.
Isi max_tokens sesuai kebutuhanmu: gateway menahan biaya output maksimum di awal (lihat Cara kerja tagihan).
Streaming
Setel stream: true untuk menerima server-sent events. Tambahkan stream_options: { "include_usage": true } agar ada chunk terakhir berisi penggunaan token sebelum [DONE]; tanpa itu, chunk usage tidak dikirim. Jika koneksi diputus, request berhenti dan kamu ditagih untuk token yang sudah dihasilkan.
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"gpt-oss-120b","choices":[{"index":0,"delta":{"content":"Halo"}}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"gpt-oss-120b","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"gpt-oss-120b","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":9,"total_tokens":23,"prompt_tokens_details":{"cached_tokens":0},"completion_tokens_details":{"reasoning_tokens":0}}}
data: [DONE]Tools dan output JSON
Function calling memakai format tools OpenAI; tool call dikembalikan di choices[].message.tool_calls (atau di-stream lewat delta.tool_calls). Untuk output JSON gunakan response_format: { "type": "json_object" }. Dukungannya berbeda tiap model, jadi uji dulu model yang akan kamu pakai.
Model dan harga
GET https://ai.lokalbdg.com/v1/models menampilkan model yang boleh dipakai key-mu. Harga dalam rupiah per 1.000.000 token.
Memuat harga…
Error
Error memakai format OpenAI, dengan code yang bisa dibaca mesin:
{
"error": {
"message": "Insufficient balance. Top up at https://ai.lokalbdg.com/ — Saldo tidak mencukupi. Isi saldo di https://ai.lokalbdg.com/",
"type": "insufficient_quota",
"param": null,
"code": "insufficient_balance"
}
}| HTTP | code | Arti |
|---|---|---|
| 400 | invalid_json · missing_model · invalid_request | Body bukan JSON valid, tidak punya model bertipe string, atau tidak bisa dibaca. |
| 401 | invalid_api_key | Key tidak dikenal atau sudah dicabut. |
| 402 | insufficient_balance | Saldo tersedia lebih kecil dari biaya yang ditahan untuk request ini. Isi saldo di dashboard. |
| 402 | key_daily_cap_exceeded · key_monthly_cap_exceeded | Batas belanja key (hari atau bulan menurut Asia/Jakarta) akan terlampaui. |
| 403 | key_frozen | Key dibekukan setelah lonjakan belanja yang tidak biasa. Aktifkan lagi di dashboard. |
| 403 | model_not_allowed | Key punya daftar model yang diizinkan, dan model ini tidak termasuk. |
| 403 | tenant_suspended · tenant_closed | Akun tidak bisa memakai API. |
| 404 | model_not_found | ID model tidak dikenal atau dinonaktifkan. Lihat GET /v1/models. |
| 413 | request_too_large | Body lebih besar dari 8 MiB. |
| 429 | rpm_limit · tpm_limit · concurrency_limit | Batas laju. Tunggu sejumlah detik sesuai header Retry-After. |
| 503 | all_upstreams_failed · bad_upstream_response · service_unavailable | Semua provider model gagal atau gateway sedang tidak tersedia. Kamu tidak ditagih. Coba lagi dengan backoff. |
| 504 | upstream_timeout | Provider tidak menjawab tepat waktu. Kamu tidak ditagih. |
Ulangi 429, 503, dan 504 dengan exponential backoff. Jangan ulangi 400, 401, 402, atau 403 sebelum mengubah sesuatu.
Batas dan batas belanja
Batas bawaan per akun adalah 600 request per menit, 1.000.000 token per menit, dan 50 request bersamaan. Respons 429 menyertakan header Retry-After (detik). Hubungi kami jika butuh batas lebih tinggi. Body request dibatasi 8 MiB. Batas belanja harian dan bulanan per key diatur di dashboard dan direset tengah malam waktu Asia/Jakarta.
Cara kerja tagihan
Saldomu adalah rupiah prabayar. Biaya per request = (token input + token output × bobot output) × harga ÷ 1.000.000. Token input yang kena cache maupun tidak berharga sama; bobot output tercantum di bagian Model dan harga. Sebelum request dimulai, gateway menahan biaya maksimum yang mungkin (perkiraan input ditambah max_tokens); setelah selesai, tahanan diganti dengan biaya sebenarnya. Jika saldo tersedia tidak cukup untuk tahanan itu, kamu mendapat 402 insufficient_balance, jadi max_tokens kecil memungkinkan kamu jalan dengan saldo kecil. Request yang gagal di semua provider tidak ditagih. Halaman Pemakaian dan ekspor CSV-nya menunjukkan persis apa yang ditagih.
Kompatibilitas
- Didukung:
POST /v1/chat/completions(streaming, tools, mode JSON) danGET /v1/models. - Tidak didukung: endpoint embeddings, gambar, audio, dan file, API Assistants dan Responses, serta API Anthropic Messages (
/v1/messages). Pakai client kompatibel OpenAI, atau adapter Anthropic-ke-OpenAI. - Field request
storedanmetadataditerima dan diabaikan (tidak pernah diteruskan ke provider). - Prompt dan completion tidak disimpan oleh gateway; hanya metadata pemakaian (token, biaya, model, waktu) yang dicatat.