اعتبار، مصرف و پرداخت
همان کیف پول ساروی؛ با تفکیک رزرو موقت، تسویه و سقف مصرف.
موجودی مشترک
GET /v1/balance موجودی قابل استفادهٔ حساب را با واحد sarovi_credits برمی‌گرداند. این موجودی با Chat، Studio و Work در برنامهٔ ساروی مشترک است. ساخت پروژه یا کلید، اعتبار تازه ایجاد نمی‌کند. خرید و مشاهدهٔ پرداخت‌ها از صفحهٔ «اعتبار و پرداخت» انجام می‌شود.
چرخهٔ یک درخواست پولی
۱. ورودی و مجوز بررسی می‌شود. ۲. سقف پروژه و کلید بررسی و اعتبار موقت رزرو می‌شود. ۳. مدل یا worker اجرا می‌شود. ۴. مصرف واقعی تسویه و اختلاف رزرو اصلاح می‌شود.
کم شدن موجودی در زمان اجرا همیشه هزینهٔ نهایی نیست. گزارش pending یعنی یک رزرو هنوز بسته نشده است. اگر قبل از مصرف خطا رخ دهد، مسیر مربوط رزرو را آزاد می‌کند. در گفتگو، مصرف واقعی پیش از قطع یا خطا ممکن است قابل محاسبه باشد.
محاسبهٔ مصرف
گفتگو از همان سیاست مصرف ساروی استفاده می‌کند: هزینهٔ ارائه‌دهنده به اعتبار تبدیل می‌شود، حداقل توکنی و هزینهٔ پایهٔ حالت هم اعمال می‌شود. Studio و ویدیو از سیاست همان بخش استفاده می‌کنند. اعداد قیمت ارائه‌دهنده در صفحهٔ مدل، قیمت نهایی خرید اعتبار به تومان نیستند.
سقف پروژه و کلید
سقف ماهانه با ماه تقویمی UTC محاسبه می‌شود. برای پذیرش کار تازه، مجموع هزینهٔ تسویه‌شده و رزروهای باز به‌علاوهٔ رزرو جدید باید در سقف جا شود. تسویهٔ کار پذیرفته‌شده می‌تواند بیشتر از برآورد اولیه باشد؛ سقف پذیرش تضمین قطع اجرای جاری در یک رقم دقیق نیست.
پرداخت
قیمت بسته و نتیجهٔ پرداخت از مسیر فعلی حساب می‌آید. API تولید نمی‌تواند به‌صورت خودکار از کارت شما شارژ بخرد. موجودی فقط بعد از تأیید واقعی پرداخت اضافه می‌شود؛ برگشتن از درگاه یا وجود پارامتر موفقیت در URL کافی نیست.
خطاهای مالی
INSUFFICIENT_CREDITS: موجودی کافی برای رزرو نیست. PROJECT_BUDGET_EXCEEDED: سقف پروژه اجازهٔ شروع نمی‌دهد. KEY_BUDGET_EXCEEDED: سقف کلید تکمیل شده است. افزایش موجودی و افزایش سقف دو کار مستقل‌اند.
import json, os, urllib.request, urllib.error
request = urllib.request.Request(
"https://api.sarovi.ir/v1/balance",
headers={
"Authorization": "Bearer " + os.environ["SAROVI_API_KEY"],
"Content-Type": "application/json"
},
method="GET"
)
try:
with urllib.request.urlopen(request, timeout=300) as response:
result = json.load(response)
print(result)
except urllib.error.HTTPError as error:
detail = json.load(error)
raise RuntimeError(f"{error.code}: {detail['error'].get('code', detail['error'].get('type', 'HTTP_ERROR'))}") from errorکلید را در متغیر محیطی SAROVI_API_KEY قرار بده. بدون نصب کتابخانه؛ با Python استاندارد.
قرارداد API 1.6.0 · تاریخچهٔ تغییرات