Ngamia uses credits for model usage. Credits are pegged 1:1 to TZS by default, and the account balance is checked before a gateway request. Chat and embeddings settle from completed usage; voice stages reserve an estimated amount first and then settle or release that reservation as the stage completes or fails.
If the available balance cannot cover a request, the gateway rejects it with 402 insufficient_quota before calling the provider. Final cost depends on the selected model’s catalog pricing and the usage returned by the provider when available.
Read the current balance
/v1/billing/balanceAPI key or JWTcurl https://api.ngamia.cc/v1/billing/balance \\
-H "Authorization: Bearer $NGAMIA_API_KEY"The response includes the current balance and the configured low-balance threshold:
{
"balance": 1998.6285,
"low_balance_threshold": 1000,
"updated_at": "2026-07-14T13:00:00Z"
}Both a JWT and an API key can read the balance. Use the API key when a server integration needs to display its own available credits.
Understand usage debits
| Event | Balance effect |
|---|---|
| Chat or embedding request accepted | Balance is checked; the final usage debit is recorded after successful completion. |
| Voice stage accepted | An estimated credit amount is reserved before the transcription or speech operation. |
| Voice stage completes | The reservation is settled against reported or policy-based usage and the activity record is written. |
| Provider failure, cancellation, or rejected request | The reservation is released or the request fails without a completed usage debit; inspect the response and activity log. |
| Balance below threshold | Ngamia can send a low-balance alert; your UI should still surface the current balance. |
Use Activity & analytics when you need token counts, audio duration, input characters, latency, status, or a request-level usage record.
Read the transaction ledger
/v1/billing/transactionsJWTThe ledger is returned newest first. Use ?limit=50&offset=0 for pagination.
[
{
"id": "...",
"type": "usage",
"amount": -0.0247,
"balance_after": 1998.6285,
"reference_type": "usage_log",
"reference_id": "...",
"created_at": "2026-07-14T13:00:00Z"
}
]| Field | Meaning |
|---|---|
type | Usually topup, usage, or refund; handle unknown future values defensively. |
amount | Signed credit change: negative for usage and positive for top-ups or refunds. |
balance_after | Balance immediately after this ledger entry. |
reference_type | The subsystem that produced the entry, such as payment or usage_log. |
reference_id | The related payment or activity record when one exists. |
When credits are low
Start a top-up with Payments, wait for the payment to reach completed, then retry the original gateway request. Use Idempotency for top-ups and other requests where a dropped connection could cause a duplicate action.