قیمت‌گذاری و محاسبهٔ تومان

هزینهٔ هر درخواست به تومان و از کیف پول تو پرداخت می‌شود. هیچ اشتراک ماهانه، حداقل مصرف یا هزینهٔ پنهانی وجود ندارد: شارژ می‌کنی، هر درخواست به اندازهٔ مصرف واقعی‌اش کم می‌کند. این صفحه توضیح می‌دهد قیمت‌ها کجا هستند، چطور اعمال می‌شوند و از کجا ببینی چقدر خرج کرده‌ای.

قیمت هر مدل

هر مدل قیمت جداگانه‌ای برای توکن ورودی و توکن خروجی دارد که در صفحهٔ مدل‌ها به تومان به‌ازای هر یک میلیون توکن نمایش داده می‌شود. بعضی مدل‌ها اجزای دیگری هم دارند: قیمت به‌ازای هر تصویر ورودی، قیمت تصویر تولیدشده، قیمت ثابت به‌ازای هر درخواست (مثلاً جستجوی وب)، و قیمت جداگانه برای توکن‌های استدلال. همهٔ این‌ها در همان صفحه فهرست شده‌اند.

قیمت‌ها به تومان ثابت نیستند و با تغییر شرایط بازار به‌روز می‌شوند. هر درخواست با قیمتی که در لحظهٔ ارسال آن معتبر بوده تسویه می‌شود؛ تغییر قیمت وسط یک درخواست روی آن اثر نمی‌گذارد. تاریخچهٔ تغییر قیمت هر مدل نگه داشته می‌شود تا صورتحساب قابل دفاع باشد.

همان اعداد در API هم هست، برای وقتی که می‌خواهی در کد خودت هزینه را تخمین بزنی یا مدل ارزان‌تر را خودکار انتخاب کنی:

curl https://api.uttapen.ir/v1/models/openai/gpt-5-mini

{
  "id": "openai/gpt-5-mini",
  "context_length": 400000,
  "pricing_currency": "IRT",
  "pricing": {"prompt": "…", "completion": "…"},
  "uttapen_pricing": {
    "prompt_toman_per_1m": "…",
    "completion_toman_per_1m": "…",
    "image_toman": "0",
    "image_output_toman": "0",
    "request_toman": "0",
    "cache_read_toman_per_1m": "…",
    "is_free": false,
    "updated_at": "2026-09-06T22:19:22Z"
  }
}

pricing قیمت به‌ازای یک توکن به تومان است (برای محاسبهٔ دقیق)، و uttapen_pricing همان را به‌ازای یک میلیون توکن، به شکلی که در صفحهٔ مدل می‌بینی. مقادیر رشته‌اند تا اعشار گم نشود. GET /v1/models بدون کلید هم کار می‌کند و ۵ دقیقه کش دارد.

مصرف واقعی، نه برآورد

مبلغ نهایی هر درخواست از روی مصرفی که خود مدل برای همان درخواست گزارش می‌دهد حساب می‌شود: توکن‌های ورودی و خروجی، توکن‌های استدلال، توکن‌های کش‌شده (که ارزان‌ترند)، تصویرها و هر جزء دیگر. ما توکن‌ها را خودمان نمی‌شماریم و بازمحاسبه نمی‌کنیم، چون شمارش هر provider با tokenizer خودش انجام می‌شود و قیمت‌گذاری پله‌ای یا کش هم دارد. عدد usage در پاسخ همان چیزی است که پولش را داده‌ای.

نتیجهٔ عملی: پیام فارسی با همان مدل نسبت به انگلیسی توکن بیشتری مصرف می‌کند (بسته به tokenizer، ۱٫۵ تا ۳ برابر). قبل از انتخاب مدل، یک نمونهٔ واقعی بفرست و usage.prompt_tokens را ببین.

رزرو، تسویه، آزادسازی

چرخهٔ عمر پول در یک درخواست:

1. رزرو (hold). قبل از این که درخواست به مدل برود، مبلغی به‌عنوان سقف احتمالی هزینه از موجودی قابل‌استفاده‌ات کنار گذاشته می‌شود. این مبلغ از طول prompt و بیشترین خروجی ممکن (max_tokens یا پیش‌فرض ۴۰۹۶ توکن) به‌علاوهٔ کمی احتیاط حساب می‌شود؛ برای درخواست‌های استدلالی خروجی سه برابر و برای درخواست‌های ریز حداقل ۱۰۰ تومان. اگر موجودی قابل‌استفاده از این مبلغ کمتر باشد، 402 insufficient_balance می‌گیری و درخواست اصلاً ارسال نمی‌شود.
2. پاسخ. تا پایان پاسخ، مبلغ رزرو در held_toman است و موجودی اصلی دست نخورده.
3. تسویه (settle). با رسیدن usage، مبلغ واقعی از موجودی کم و کل رزرو آزاد می‌شود. این در یک تراکنش اتمی انجام می‌شود.
4. خطا. اگر مدل خطا بدهد یا پاسخی نیاید، رزرو کامل آزاد می‌شود و هیچ چیز شارژ نمی‌شود.
5. قطع وسط پاسخ. فقط مصرف تا لحظهٔ قطع تسویه می‌شود؛ اگر گزارش مصرف فوراً نرسد، یک job پس‌زمینه آن را از provider می‌پرسد و ظرف چند دقیقه تسویه می‌کند. تا آن موقع رزرو در held_toman می‌ماند.

پس available_toman (که balance_toman منهای held_toman است) عددی است که برای درخواست بعدی ملاک است، نه balance_toman. اگر چند استریم هم‌زمان داری، رزروها جمع می‌شوند.

چرا مبلغ نهایی گاهی از رزرو بیشتر است

رزرو یک برآورد است. اگر مدل بیش از حد انتظار توکن تولید کند (مثلاً max_tokens نداده‌ای و مدل تا سقف خودش نوشته)، مبلغ واقعی می‌تواند از رزرو بیشتر شود. در این حالت باز هم مبلغ واقعی کامل کم می‌شود و موجودی می‌تواند موقتاً منفی شود. تا شارژ بعدی همهٔ درخواست‌ها، حتی مدل‌های رایگان، 402 می‌گیرند. راه پیشگیری ساده است: max_tokens واقعی بده.

دیدن هزینهٔ هر درخواست

غیراستریم — روی پاسخ:

X-Uttapen-Cost-Toman: 6.659688
X-Uttapen-Balance-Toman: 97564.413809
X-Uttapen-Request-Id: 01a078dd-853e-7480-aa83-262d3239e6a2

استریم — با هدر X-Uttapen-Include-Meta: 1 رویداد uttapen.meta قبل از [DONE] با cost_toman، balance_toman و hold_toman (استریم).

مبالغ با ۶ رقم اعشار ذخیره و گزارش می‌شوند؛ یک درخواست کوچک می‌تواند کمتر از یک تومان باشد. گرد کردن فقط در نمایش داشبورد است، نه در حساب.

گزارش مصرف با API

curl "https://api.uttapen.ir/v1/uttapen/usage?from=2026-09-01&to=2026-09-08&group_by=model" \
  -H "Authorization: Bearer $UTTAPEN_API_KEY"

{
  "from": "2026-09-01T00:00:00Z",
  "to": "2026-09-08T00:00:00Z",
  "group_by": "model",
  "data": [
    {"bucket": "openai/gpt-5-nano", "requests": 89, "prompt_tokens": 4719345, "completion_tokens": 1969, "charge_toman": "2231.443689"},
    {"bucket": "openai/gpt-5", "requests": 3, "prompt_tokens": 30, "completion_tokens": 72, "charge_toman": "99.895314"}
  ]
}

• group_by یکی از day، model، key. با day هر bucket یک تاریخ (میلادی، UTC) است؛ با key شناسهٔ کلید (همان UUID صفحهٔ کلیدها) و برای مصرف چت داشبورد مقدار chat.
• فقط درخواست‌های تسویه‌شده شمرده می‌شوند؛ رزروهای باز در held_toman هستند.
• from و to تاریخ یا زمان ISO؛ پیش‌فرض ۳۰ روز گذشته تا حالا.
• فقط درخواست‌های کاربر همان کلید را می‌بیند؛ همهٔ کلیدهایت را در بر می‌گیرد.
• همان داده در داشبورد ← مصرف با نمودار و تقویم جلالی هست، و ریز هر تراکنش (شارژ، هزینه، برگشت) در کیف پول.

شارژ و فاکتور

شارژ از طریق درگاه زیبال، حداقل ۵۰٬۰۰۰ و حداکثر ۵۰٬۰۰۰٬۰۰۰ تومان در هر تراکنش. بعد از پرداخت موفق، مبلغ همان لحظه به balance_toman اضافه می‌شود و فاکتور در داشبورد ← فاکتورها قابل چاپ است. اگر بعد از پرداخت به هر دلیل موجودی اضافه نشد، شناسهٔ پرداخت را از صفحهٔ کیف پول به پشتیبانی بده؛ پرداخت تأییدشدهٔ زیبال هرگز دو بار اعمال نمی‌شود و هرگز گم نمی‌شود.

خلاصه

• قیمت هر مدل به تومان به‌ازای ۱M توکن ورودی/خروجی در صفحهٔ مدل و در GET /v1/models.
• شارژ بر اساس مصرف واقعی گزارش‌شدهٔ همان درخواست.
• رزرو قبل، تسویه بعد، خطا رایگان.
• X-Uttapen-Cost-Toman یا uttapen.meta برای هر درخواست، GET /v1/uttapen/usage برای تجمیع.