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

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

قیمت هر مدل

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

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

همان اعداد در 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 بدون کلید هم کار می‌کند و ۵ دقیقه کش دارد.

مدل‌های با قیمت متغیر

چند مدل مسیریاب‌اند: هر درخواست را به مدلی می‌فرستند که برای آن مناسب‌تر تشخیص می‌دهند، پس قیمتشان از قبل معلوم نیست. در صفحهٔ مدل «قیمت متغیر» می‌بینی و در GET /v1/models مقدارهای pricing برابر "-1" است (همان قرارداد رایج برای «قیمت نامعلوم»). داخل uttapen_pricing این فیلدها هم می‌آید:

"uttapen_pricing": {
  "prompt_toman_per_1m": "-1",
  "completion_toman_per_1m": "-1",
  "variable": true,
  "observed_window_days": 7,
  "observed_avg_toman_per_1m": "48210.00",
  "observed_requests": 312,
  "observed_scope": "all"
}

observed_avg_toman_per_1m میانگین مبلغی است که مشتری‌ها در ۷ روز اخیر واقعاً برای هر یک میلیون توکن (ورودی و خروجی با هم) پرداخته‌اند و observed_requests تعداد درخواست‌هایی که میانگین بر پایهٔ آن‌هاست. تا وقتی درخواست کافی ثبت نشده، این دو فیلد نمی‌آیند. این عدد فقط برای برآورد است: هزینهٔ هر درخواست همان قیمت مدلِ پاسخ‌دهنده است، و مثل همهٔ مدل‌ها پیش از ارسال مبلغی رزرو و بعد فقط هزینهٔ واقعی کم می‌شود.

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

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

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

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

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

1. رزرو (hold). قبل از این که درخواست به مدل برود، مبلغی به‌عنوان سقف احتمالی هزینه از موجودی قابل‌استفاده‌ات کنار گذاشته می‌شود. این مبلغ از طول پرامپت و بیشترین خروجی ممکن (max_tokens تو، یا اگر ندادی سقف پیش‌فرض ۳۲٬۷۶۸ توکن — و اگر خود مدل سقف کمتری دارد، همان) به‌علاوهٔ کمی احتیاط حساب می‌شود؛ برای درخواست‌های استدلالی خروجی سه برابر و برای درخواست‌های ریز حداقل ۱۰۰ تومان.
2. اگر موجودی به سقف درخواستی نرسد، درخواست رد نمی‌شود. سقف خروجی تا جایی که موجودی می‌کشد پایین می‌آید (حداقل ۱٬۰۲۴ توکن) و عددش در هدر پاسخ X-Uttapen-Max-Tokens می‌آید؛ پاسخ ممکن است با finish_reason: "length" تمام شود. فقط اگر همان حداقل هم جا نشود 402 insufficient_balance می‌گیری — و آنجا required_toman می‌گوید چقدر شارژ لازم است. سقفی که برایش رزرو شده همان سقفی است که به مدل تحمیل می‌شود، پس مدل نمی‌تواند از رزرو جلو بزند.
3. پاسخ. تا پایان پاسخ، مبلغ رزرو در held_toman است و موجودی اصلی دست نخورده.
4. تسویه (settle). با رسیدن usage، مبلغ واقعی از موجودی کم و کل رزرو آزاد می‌شود. این در یک تراکنش اتمی انجام می‌شود.
5. خطا. اگر مدل خطا بدهد یا پاسخی نیاید، رزرو کامل آزاد می‌شود و هیچ چیز شارژ نمی‌شود.
6. قطع وسط پاسخ. فقط مصرف تا لحظهٔ قطع تسویه می‌شود؛ اگر گزارش مصرف فوراً نرسد، یک کار پس‌زمینه آن را از سازندهٔ مدل می‌پرسد و ظرف چند دقیقه تسویه می‌کند. تا آن موقع رزرو در held_toman می‌ماند.

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

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

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

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

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

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 برای تجمیع.