صورتحساب و کیف پول API

کیف پول API#

• هر حساب یک کیف پول API جداگانه دارد که از کنسول با درگاه بانکی ایرانی (کارت‌های شتاب) شارژ می‌شود.
• این کیف پول با اعتبار اشتراک چت فرق دارد: پلن‌های ماهانهٔ پنل چت هیچ‌وقت شامل مصرف API نمی‌شوند و برعکس.
• همهٔ کلیدهای یک حساب از همین کیف پول مصرف می‌کنند؛ برای کنترل هر کلید از سقف هزینهٔ ماهانه استفاده کن.
• درخواست‌های ناموفق (خطای اعتبارسنجی، خطای پروایدر و…) هزینه‌ای ندارند.

نحوهٔ محاسبهٔ هزینه#

قیمت هر مدل در فهرست مدل‌ها و GET /v1/models (فیلد pricing) آمده است. بسته به واحد مدل:

«ورودی تازه» یعنی prompt_tokens − cached_tokens. توکن‌های تفکر (reasoning) جزو توکن خروجی‌اند و پیام سیستمی تزریق هویت (در صورت روشن بودن) جزو ورودی.

مثال محاسبه#

فرض کن مدلی با این قیمت‌ها داریم (اعداد فرضی و گرد شده‌اند؛ قیمت واقعی را از فهرست مدل‌ها بگیر):

درخواستی با prompt_tokens = 12,000 که 8,000 توکنش از کش آمده و completion_tokens = 900:

fresh input  = 12,000 − 8,000 = 4,000 tokens  →  4,000 × 300,000   / 1,000,000 =   1,200  IRT
cached input = 8,000 tokens                   →  8,000 × 30,000    / 1,000,000 =     240  IRT
output       = 900 tokens                     →    900 × 1,500,000 / 1,000,000 =   1,350  IRT
                                                                      total   =   2,790  تومان

همین عدد در پاسخ API یکپارچه به‌صورت "hooshi": { "cost": 2790, "currency": "IRT" } برمی‌گردد. یعنی با یک میلیون تومان شارژ، بیش از ۳۵۰ درخواست مشابه می‌توانی بفرستی.

موجودی: GET /v1/balance#

import httpx

r = httpx.get("https://api.hooshi.ai/v1/balance", headers={"Authorization": "Bearer hk-..."})
b = r.json()
if b["balance"] < 50_000:
    print("⚠ موجودی کم است:", b["balance"], "تومان")

{ "object": "balance", "currency": "IRT", "balance": 482350.5, "min_required": 1000 }

گزارش مصرف: GET /v1/usage#

مصرف API کل حساب (همهٔ کلیدها، هم API یکپارچه و هم بومی) را به تفکیک روز و مدل برمی‌گرداند.

curl "https://api.hooshi.ai/v1/usage?days=7" -H "Authorization: Bearer $HOOSHI_API_KEY"

{
  "object": "list",
  "currency": "IRT",
  "data": [
    { "date": "2026-10-08", "model": "anthropic/claude-sonnet-5-5", "requests": 214, "input_tokens": 1830044, "output_tokens": 402113, "cost": 1192509.4 },
    { "date": "2026-10-08", "model": "openai/text-embedding-3-small", "requests": 37, "input_tokens": 920331, "output_tokens": 0, "cost": 2857.6 },
    { "date": "2026-10-09", "model": "openai/gpt-5.5", "requests": 88, "input_tokens": 512200, "output_tokens": 133080, "cost": 1017415.3 }
  ]
}

برای نمودار، مصرف هر کلید و جزئیات درخواست‌ها به داشبورد مصرف کنسول سر بزن.

حداقل موجودی#

اگر موجودی کیف پول API کمتر از min_required (در حال حاضر ۱٬۰۰۰ تومان) باشد، درخواست‌ها قبل از رسیدن به پروایدر با کد 402 رد می‌شوند. چون هزینهٔ دقیق بعد از پایان پاسخ مشخص می‌شود، یک درخواست بزرگ ممکن است موجودی را کمی منفی کند؛ این مبلغ از شارژ بعدی کم می‌شود.

{
  "error": {
    "message": "موجودی کیف پول API کافی نیست؛ از پنل توسعه‌دهندگان شارژ کنید. Insufficient API wallet balance — top up at ...",
    "type": "insufficient_quota",
    "code": "insufficient_quota",
    "param": null
  }
}

سقف هزینهٔ ماهانهٔ هر کلید#

برای هر کلید می‌توانی در کنسول یک سقف ماهانه به تومان تعیین کنی. مجموع هزینهٔ آن کلید از ابتدای ماه میلادی جاری محاسبه می‌شود و وقتی به سقف برسد، درخواست‌های بعدی تا ماه بعد رد می‌شوند:

{
  "error": {
    "message": "Monthly spend limit for this API key has been reached.",
    "type": "spend_limit_reached",
    "code": "spend_limit_reached",
    "param": null
  }
}