Skip to content

PAYG dari Saldo Wallet

PAYG membayar pemakaian model dari saldo wallet akun. Gunakan API key aktif yang sama pada endpoint /v1 atau /v3. Paket plan tidak wajib untuk request chat teks dan custom function/tool calls yang harga modelnya tersedia.

Urutan pembayaran

  1. Request chat ke model bansos yang aktif hari ini memakai pool bansos jika akun memenuhi syarat dan pool mampu mereservasi request tersebut.
  2. Pemakaian model reguler memakai kuota plan aktif yang tersedia dan mengizinkan model tersebut.
  3. Akun tanpa plan, plan kedaluwarsa, kuota yang sudah habis, atau model di luar cakupan plan dapat memakai PAYG dari saldo wallet.

Jika bansos habis atau model belum diaktifkan untuk pool hari ini, API key pribadi melanjutkan pemeriksaan plan/PAYG. API key khusus program lama yang berstatus paused tetap hanya dapat memakai bansos. Akses PAYG memerlukan saldo yang cukup untuk request, terpisah dari syarat top-up Rp3.500/24 jam atau Rp10.000/72 jam untuk bansos.

Reservasi dan biaya akhir

Sebelum menghubungi provider, sistem menahan saldo untuk batas biaya request. Perhitungan mempertimbangkan panjang input, batas output, harga model, dan kemungkinan fallback. Request paralel berbagi saldo tersedia yang sama; uang yang sedang ditahan tidak dapat dibelanjakan oleh request atau pembelian lain.

Setelah provider mengirim usage yang valid, biaya akhir memakai tarif retail model dan diskon cache yang berlaku. Selisih reservasi dikembalikan otomatis. Biaya PAYG dibulatkan ke atas ke Rupiah utuh, minimal Rp1 untuk request dengan pemakaian positif. Histori wallet menampilkan reservasi sebagai transaksi pending dan biaya akhir sebagai deduction paid.

Model tanpa harga, input gambar/audio/file, hosted tools berbayar, dan n selain 1 ditolak sebelum provider dipanggil. PAYG saat ini mencakup Chat Completions, Messages, Responses, streaming, dan setiap item batch untuk teks/custom function tools; endpoint audio memiliki aturan paket tersendiri.

Jika provider tidak mengirim usage yang dapat diverifikasi, koneksi terputus, atau hasil upstream belum diketahui, reservasi dapat tetap ditahan untuk rekonsiliasi. Dana tersebut bukan biaya akhir yang sudah dikonfirmasi. Tim admin dapat merekonsiliasi berdasarkan bukti pemakaian provider; sistem tidak mengembalikan reservasi yang sudah dikirim ke provider dengan asumsi pemakaiannya nol.

Menangani respons API

  • 402 insufficient_wallet_balance: saldo tersedia belum cukup untuk reservasi maksimum. Top-up wallet, kurangi konteks, atau kurangi max_tokens/max_output_tokens.
  • 400 payg_price_unavailable: harga model atau rute fallback belum dapat dihitung.
  • 400 payg_unsupported_request: format/cara pemakaian belum memiliki perhitungan reservasi PAYG.
  • 503 wallet_unavailable: database/reservasi belum dapat dikonfirmasi; jangan menganggap request sudah dijalankan.
  • X-Billing-Mode: payg: request menggunakan wallet.
  • X-Wallet-Reservation-Id: referensi reservasi untuk penelusuran admin.
  • X-Wallet-Reserved-Rp: jumlah maksimum yang ditahan, bukan biaya akhir.

GET /v3/balance (atau /v1/balance) menampilkan wallet_balance sebagai saldo tersedia, wallet_reserved_rp sebagai saldo yang masih ditahan, dan wallet_payg_available. Kuota token nol tidak berarti pemakaian gratis tanpa batas.

Retry yang tidak mendebit dua kali

Kirim header Idempotency-Key unik berisi maksimal 128 byte untuk satu request logis. Retry dengan key yang sama ditolak dengan 409 idempotency_already_processed; provider tidak dipanggil dan wallet tidak didebit lagi. Jika payload berbeda tetapi key sama, responsnya 409 idempotency_conflict. Respons hasil generasi tidak disimpan untuk replay. Gunakan key baru hanya saat benar-benar ingin menjalankan generasi baru. Tanpa header ini, request yang dikirim lagi dianggap sebagai generasi terpisah.

Batch menerapkan key tersebut per posisi item sehingga retry seluruh batch tidak menjalankan ulang item yang sudah direservasi.