مصرف و صورت‌حساب
صورت‌حساب خود را بفهمید: مصرف در هر پاسخ، نقطهٔ پایانی موجودی برای هر کلید، نرخ‌های مؤثر، سقف‌های نرخ 429 و اثر خالی بودن موجودی روی درخواست‌ها.
مصرف هر درخواست در هر پاسخ می‌آید — با اطمینان بر اساس آن صورت‌حساب صادر کنید. تصویر لحظه‌ای موجودی با GET /v1/dashboard/balance در دسترس است.
همهٔ مدل‌ها، قابلیت‌ها و قیمت‌ها فهرست مستندات برای عامل‌های هوش مصنوعی:https://oneprovider.dev/docs/llms.txt مصرف هر درخواست
هر پاسخ /v1/messages یک شیء usage با تعداد توکن‌ها دارد:
{
"usage": {
"input_tokens": 48,
"output_tokens": 92,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
}برای chat-completions همین اعداد با نام‌های prompt_tokens، completion_tokens و total_tokens می‌آیند.
موجودی کلید: GET /v1/dashboard/balance
موجودی فعلی کلید را برمی‌گرداند. فوری پاسخ می‌دهد و همان کلید API را می‌گیرد.
فقط Authorization: Bearer این endpoint کلید شما را فقط از طریق هدرAuthorization: Bearer sk-... می‌پذیرد (برخلاف /v1/messages که x-api-key را هم می‌پذیرد). bash curl -H "Authorization: Bearer sk-YOUR_KEY_HERE" \
https://api.oneprovider.dev/v1/dashboard/balanceپاسخ 200 OK:
{
"object": "balance",
"balance_usd": 54.77,
"expires_at": "2026-07-29T19:00:00Z",
"is_active": true,
"last_synced_at": "2026-06-29T19:52:00Z"
}balance_usd: موجودی در دسترس کلید به USD.expires_at: انقضای کلید (ISO 8601 به UTC؛ اگر انقضا نداردnull).is_active: اگر کلید متوقف یا غیرفعال باشدfalse.last_synced_at: آخرین زمان به‌روزرسانی موجودی.
endpointهای موجودی سازگار با OpenAI
اپ‌هایی مانند NextChat و LobeChat موجودی را از مسیرهای سبک OpenAI می‌خوانند. این‌ها با همان کلید در Authorization: Bearer کار می‌کنند:
| Endpoint | چه برمی‌گرداند |
|---|---|
GET /v1/dashboard/billing/subscription | hard_limit_usd: موجودی باقی‌مانده |
GET /v1/dashboard/billing/usage | total_usage: همیشه 0 (این فیلد به سنت است) |
GET /v1/dashboard/billing/credit_grants | total_available: موجودی باقی‌مانده |
خطاها: 401 برای نبودن یا نامعتبر بودن هدر Authorization: Bearer؛ 429 وقتی از محدودیت نرخ فراتر بروید (endpointهای موجودی به‌ازای هر IP محدود شده‌اند). موجودی و هزینهٔ هر درخواست در حساب کاربری هم هست (صفحهٔ «مصرف» در ربات @oneprovider_robot و در app.oneprovider.dev ).
نرخ‌های مؤثر
ما بر اساس قیمت ثابت برای هر 1M توکن و با نرخ منتشرشده در /pricing محاسبه می‌کنیم. ضریب، حداقل یا گردکردنی در کار نیست. محاسبه این است:
textcost = (input_tokens / 1_000_000) * rate_in
+ (output_tokens / 1_000_000) * rate_out
+ (cache_read_input_tokens / 1_000_000) * (rate_in * 0.10)
+ (cache_creation_input_tokens / 1_000_000) * (rate_in * 1.25)- خواندن از کش برای بیشتر مدل‌ها با 10% نرخ ورودی محاسبه می‌شود.
- ساخت کش (اولین باری که یک نقطهٔ کش نوشته می‌شود) برای بیشتر مدل‌ها با 125% نرخ ورودی محاسبه می‌شود.
- ضرایب 0.10 و 1.25 در فرمول مقادیر معمول‌اند: نرخ دقیق خواندن و نوشتن کش برای هر مدل در جدول مدل‌ها است.
وقتی موجودی تمام می‌شود
وقتی موجودی کلید به صفر برسد، درخواست‌هایی که با آن زده می‌شوند 429 با error.type برابر insufficient_balance، error.code برابر insufficient_quota و هدر x-should-retry: false برمی‌گردانند:
HTTP/1.1 429 Too Many Requests
x-should-retry: false
Content-Type: application/json
{
"type": "error",
"error": {
"type": "insufficient_balance",
"code": "insufficient_quota",
"message": "Insufficient balance on this API key. Top up: dashboard.oneprovider.dev"
}
}دوباره تلاش نکنید: موجودی حساب کاربری و سقف کلید (صفحهٔ «کلیدها») را بررسی کنید، در صورت لزوم حساب کاربری را شارژ کنید و درخواست را دوباره بفرستید (چگونه ). سایر کدها در کدهای خطا آمده است.
مدت کلید را شما تعیین می‌کنید؛ موجودی منقضی نمی‌شود مدت هر کلید را در حساب کاربری تعیین می‌کنید (تا 90 روز، قابل تمدید). موجودی با تایمر کسر نمی‌شود: بازنشانی ماهانه، تعهد حداقل مصرف یا اشتراک وجود ندارد؛ وجه تا زمانی که مصرف نشود در دسترس می‌ماند.Rate-limit (429)
درخواست‌های زیاد در زمان کوتاه 429 rate_limit_error برمی‌گردانند. پاسخ ممکن است هدر Retry-After را به ثانیه داشته باشد:
HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json
{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "Rate limit exceeded; retry later"
}
}اگر Retry-After هست، دست‌کم به همان اندازه صبر کنید؛ وگرنه با وقفهٔ فزاینده دوباره تلاش کنید. اگر 429 ادامه داشت، همزمانی سمت کلاینت را کم کنید. درخواست‌هایی که با محدودیت نرخ رد می‌شوند از موجودی کم نمی‌کنند.
دقت مصرف هر درخواست
مجموع اشیای usage درخواست‌ها دقیقاً برابر هزینهٔ واقعی هر کلید است. در تاریخ 2026-05-08 روی نمونهٔ 24 ساعتهٔ 25 845 درخواست بررسی شد: بیشترین اختلاف کمتر از $0.001 بود (گرد کردن در رقم ششم اعشار). با اطمینان بر اساس usage هر درخواست صورت‌حساب صادر کنید.