کنترل مصرف و هزینه در مسیر API

اگه از بنفش تو یه اپ، اسکریپت، یا CLI agent استفاده می‌کنی و می‌خوای بدونی چی جلوی مصرف بی‌حساب رو می‌گیره — این مقاله برای توئه. تا آخرش دقیقاً می‌دونی چه کنترلی امروز واقعاً وجود داره، چه چیزی هنوز نداری، و اگه وسط کار پولت تموم بشه چی می‌بینی.

سه لایه کنترل: کیف پول، سقف هر کلید، سقف هر اجرا

بنفش برای هر کاربر یه کیف پول تومانی داره — همونی که با ۱۰۰٬۰۰۰ تومان شروع می‌شه و با شارژ اضافه می‌شه. مسیر API/CLI هم به همین کیف پول گیت شده: وقتی کلید می‌سازی، می‌تونی روش یه سقف هزینه (اختیاری، مخصوص همون کلید) و یه سقف هر اجرا (run cap، سقف هزینه‌ی یه نشست agent) هم بذاری — هر دو تا رو تو «اتصال به ابزارها» تنظیم می‌کنی.

این کنترل‌ها دقیقاً چطور کار می‌کنن

• چت تو مرورگر بنفش: قبل از هر پیام، هزینه‌ی تخمینی رو از قبل نگه می‌داره (hold) تا نشه بیشتر از موجودیت خرج کنی. اگه کیف پولت خالی باشه، پیام اصلاً ارسال نمی‌شه.
• مسیر API / CLI agent / SDK: اینجا چک لحظه‌ای و از‌قبل نیست — یه سقف روی خودِ gateway تنظیم می‌شه که با موجودی کیف پولت هماهنگه. وقتی موجودی ته بکشه، همون کلید هر درخواستی که بفرستی با HTTP 402 رد می‌شه، تا وقتی شارژ کنی — کلید عوض نمی‌شه، همین که شارژ کنی همون کلید بلافاصله دوباره کار می‌کنه. جزئیاتش تو «رفع اشکال اتصال» هست.
• سقف هر اجرا (run cap): جدا از کیف پول کلیه — یه سقف هزینه برای یه نشست agent که خودت موقع ساختن یا ویرایش کلید تعیین می‌کنی. رسیدن بهش، برخلاف کیف پول خالی، کلید رو به‌طور خودکار جایگزین می‌کنه — درخواست بعدی با کلید قدیمی HTTP 401 می‌گیره، نه 402 — ولی فقط همون کلید رو می‌بنده، نه کل حسابت رو.

۴۰۲ در برابر ۴۲۹: کدوم کجا پیش میاد

مسیر IDE/CLI/SDK (Cursor، Claude Code، هر ابزار سازگار با OpenAI) دو تا وضعیت خطای تضمین‌شده و مال خودِ بنفش داره:

• کیف پول خالی → HTTP 402. این خطا از خودِ gateway میاد، نه از یه فرمت اختصاصی بنفش — پس بدنه‌ی دقیقش رو gateway تعیین می‌کنه، نه این مقاله. رفتارش ثابته: همون کلید بلافاصله بعد از شارژ دوباره کار می‌کنه، بدون جایگزینی.
• سقف هر اجرا پر شد → HTTP 401 روی کلید قدیمی. کلید خودکار جایگزین می‌شه؛ درخواست بعدی با کلید جدید باید کار کنه.

سقفِ رولینگِ خودِ بنفش (۵ ساعته/هفتگی) هنوز کلید IDE رو با یه ۴۲۹ زنده رد نمی‌کنه. اون سقف امروز فقط چتِ داخل مرورگر رو مستقیماً با HTTP 429 گیت می‌کنه — همون‌جایی که تیک اجرای هر پیام از قبل چک می‌شه. برای یه کلید IDE، رسیدن به همون سقف رولینگ فقط یه فلگ داخلی (ideCapSuspendedAt) رو بین یکی دو تیک بعدیِ چرخه‌ی sync ثبت می‌کنه؛ رد کردن واقعیِ درخواست‌های gateway بر همین اساس یه قدم جدا و هنوز پیاده‌نشده‌ست.

⚠️ این تضمین نمی‌ده که هیچ‌وقت ۴۲۹ نمی‌گیری. خودِ gateway (که کلید IDE مستقیم بهش وصل می‌شه) سقف نرخ/همزمانی مخصوص به خودشم داره — کاملاً جدا از سقف رولینگ بنفش — و طبق قرارداد صدور کلید می‌تونه مستقل عمل کنه. این نوشته فقط داره می‌گه «سقف رولینگ خودِ بنفش امروز مسیر IDE رو گیت نمی‌کنه»، نه این‌که gateway هیچ‌وقت خودش HTTP 429 برنمی‌گردونه. کد و اسکریپتت رو طوری بنویس که یه ۴۲۹ غیرمنتظره رو retry/backoff کنه، نه این‌که فرض کنه اصلاً پیش نمیاد.

گرفتن کلید به کیف پول گره نخورده

ساختن کلید نیاز به موجودی کیف پول نداره — با کیف پول کاملاً خالی هم می‌تونی از «اتصال به ابزارها» یه کلید بسازی. کیف پول وقتی وارد بازی می‌شه که واقعاً یه درخواست بفرستی.

پس اگه می‌خوای هزینه‌ت رو خودت کنترل کنی

• سقف هزینه و سقف هر اجرا رو موقع ساختن کلید تنظیم کن — پیش‌فرض خاموشه، ولی رایگان و فوریه.
• قبل از این‌که یه agent رو ول کنی خودش کار کنه، با تخمین‌گر هزینه ببین هر نشست چقدر آب می‌خوره:

• مدل مصرفت رو با کارت جور کن — «کدوم مدل رو انتخاب کنم؟» همینو توضیح می‌ده.
• برای برنامه‌ای که مصرف کاربرهای دیگه رو هم مدیریت می‌کنی، «کنترل هزینه در برنامه‌ت» چند تا تکنیک عملی داره.

چی کار نمی‌کنه (هنوز)

• هشدار لحظه‌ای وقتی مصرف API از یه آستانه رد می‌شه، قبل از رسیدن به سقف — وجود نداره؛ فقط می‌تونی با تخمین‌گر بالا از قبل حساب کتاب کنی.
• سقف‌های زمانی (روزانه/هفتگی) — فعلاً فقط سقف کلی کلید و سقف هر اجرا هست، نه سقف دوره‌ای.

اگه هر کدوم از این‌ها برات حیاتیه، فعلاً باید خودت تو کد یا اسکریپتت پیاده‌ش کنی.