1. Panduan Memulai Cepat (Quickstart)
Cukup ganti baseURL dan masukkan API key Anda. Tidak ada SDK khusus yang wajib diinstall.
from openai import OpenAI
client = OpenAI(
base_url="",
api_key="vx-live-YOUR_API_KEY",
)
response = client.chat.completions.create(
model="deepseek-4.1",
messages=[
{"role": "system", "content": "You are a helpful engineering assistant."},
{"role": "user", "content": "Jelaskan cara kerja rate-limiting token bucket."},
],
temperature=0.7,
)
print(response.choices[0].message.content)2. Rute API yang Didukung (Endpoints)
/v1/chat/completionsOpenAI CompatibleChat completions standar industri. Mendukung multi-turn chat, system prompt, JSON mode, dan streaming SSE.
/v1/messagesAnthropic NativeProtokol Messages asli Anthropic. Digunakan otomatis oleh Claude Code CLI, Claude SDK, dan Cursor.
/v1/modelsREST JSON ListMengembalikan daftar model terkurasi yang diizinkan untuk API key pemanggil. Tidak pernah membocorkan model di luar whitelist.
/v1/models/{id}REST JSON DetailMengambil spesifikasi konteks dan metadata model spesifik. Mengembalikan 404 jika ID model tidak ada pada whitelist key.
3. Matriks Kode Respon & Penanganan Error
Semua kesalahan mengembalikan format JSON standar: {"error": {"message": "...", "code": "..."}}
| Status | Error Code | Penyebab | Solusi Klien |
|---|---|---|---|
| 200 OK | - | Permintaan berhasil diproses. | Baca data dari response JSON atau stream SSE. |
| 400 Bad Request | conflicting_credentials | Mengirim Authorization Bearer dan x-api-key yang berbeda sekaligus. | Pilih salah satu header autentikasi yang konsisten. |
| 401 Unauthorized | invalid_api_key | API key tidak ditemukan, dicabut, atau dinonaktifkan. | Periksa kembali nilai API key pada konsol Anda. |
| 402 Payment Required | insufficient_token_balance | Saldo token habis (0) dan tidak memiliki pass durasi aktif. | Top-up via TokoPay QRIS atau tunggu reset harian 00:01 WIB. |
| 402 Payment Required | model_requires_purchase | Model ditandai Saldo Berbayar (tidak gratis) dan saldo beli bernilai 0. | Top-up saldo reguler atau aktifkan paket durasi. |
| 403 Forbidden | model_not_allowed_for_bansos | API key Bansos memanggil model di luar whitelist yang diizinkan admin. | Pilih model yang tersedia di halaman /bansos atau buat key reguler. |
| 404 Not Found | model_not_found | Model ID tidak terdaftar atau disembunyikan oleh kebijakan admin. | Panggil GET /v1/models untuk melihat daftar model yang diizinkan. |
| 413 Payload Too Large | payload_too_large | Ukuran prompt melebihi 200.000 karakter atau > 100 pesan chat. | Kecilkan riwayat percakapan yang dikirimkan. |
| 429 Rate Limited | rate_limited / concurrent_limit | Permintaan melebihi batas RPM atau konkurensi paralel. | Terapkan exponential backoff sesuai header Retry-After. |
| 503 Service Unavailable | capacity_busy | Kapasitas upstream sedang padat sementara waktu. | Ulangi permintaan setelah jeda beberapa detik. |
4. Kebijakan Kuota & Zona Waktu (WIB)
Semua perhitungan kuota gratis harian mengacu pada zona waktu Asia/Jakarta (WIB, UTC+7). Kuota gratis di-reset otomatis setiap hari pada pukul 00:01 WIB.
Harga jual model pada katalog ditampilkan dalam satuan IDR per 1.000.000 token. Saldo token yang dibeli berlaku selamanya tanpa batas waktu kedaluwarsa.