احراز هویت
هر فراخوانی که مدلی را اجرا می‌کند یا درخواست‌های شما را می‌خواند، به کلید API نیاز دارد. کاتالوگ (GET /models، GET /categories)، POST /quote و سند OpenAPI عمومی هستند.
کلیدهای API
در https://doitong.com/developers/dashboard#keys کلیدها را بسازید و لغو کنید. یک کلید مانند doitong_ است که پس از آن ۶۴ نویسه هگزادسیمال می‌آید و هنگام ایجاد فقط یک‌بار نمایش داده می‌شود. آن را در هدر Authorization ارسال کنید:
curl https://api.doitong.com/v1/account -H "Authorization: Bearer $DOITONG_API_KEY"X-API-Key: <key> نیز کار می‌کند.
درخواست بدون کلید، 401 با کد missing_api_key دریافت می‌کند؛ کلید ناشناخته، لغوشده یا منقضی‌شده نیز 401 می‌گیرد.
محدوده‌ها
هر کلید دارای محدوده‌هایی است. API مدل این موارد را بررسی می‌کند:
| عملیات | محدوده موردنیاز |
|---|---|
| اجرای مدل، لغو درخواست، حذف فایل‌های یک درخواست، تغییر تنظیم فضای ذخیره‌سازی | models:run (کلیدهای دارای images:create یا videos:create قدیمی نیز کار می‌کنند) |
| ایجاد URL بارگذاری | models:run یا media:upload |
| خواندن درخواست‌ها و حساب | models:read (کلیدی که می‌تواند مدل‌ها را اجرا کند نیز می‌تواند آن‌ها را بخواند) |
کلیدهای جدید به‌طور پیش‌فرض models:read و models:run را دریافت می‌کنند. فراخوانی بدون محدوده مناسب، 403 با کد insufficient_scope دریافت می‌کند.
بودجه‌های اعتباری
یک کلید می‌تواند بودجه مخصوص خود را برحسب اعتبار API (۱٬۰۰۰ اعتبار API = $۱) داشته باشد که مالک حساب تعیین می‌کند: بودجه کلی، بودجه روزانه (۲۴ ساعت گذشته)، یا هر دو. پیش از کسر هزینه اجرا، هزینه با مقداری که کلید تاکنون از طریق این API خرج کرده است (پس از محاسبه بازپرداخت‌ها) مقایسه می‌شود. اگر اجرا از این مقدار بیشتر شود، با 402 budget_exceeded رد می‌شود و چیزی کسر نمی‌شود.
کلیدی که بودجه ندارد می‌تواند تا سقف موجودی API هزینه کند. جدا از این، اگر موجودی API نتواند هزینه اجرا را پوشش دهد، 402 insufficient_credits همراه با top_up_url دریافت می‌کنید.
GET https://api.doitong.com/v1/account موجودی API و بودجه باقی‌مانده کلید را نشان می‌دهد (هر دو برحسب اعتبار API):
{
"object": "account",
"credits": 125000,
"balance": { "credits": 125000, "usd": "125.00" },
"top_up_url": "https://doitong.com/developers/dashboard#balance",
"key": {
"name": "Production server",
"prefix": "doitong_3fa9c1e...",
"scopes": ["models:read", "models:run"],
"budget_remaining": 50000,
"rate_limit": 3600,
"rate_limit_remaining": 3571
},
"webhook_signing_secret": "whsec_..."
}وقتی کلید بودجه اختصاصی نداشته باشد، مقدار budget_remaining برابر null است.
محدودیت نرخ
هر کلید می‌تواند در هر ساعت ۳۶۰۰ درخواست ارسال کند، مگر اینکه محدودیت آن متفاوت تنظیم شده باشد. هر پاسخ احراز هویت‌شده وضعیت فعلی را دارد:
| هدر | معنا |
|---|---|
X-RateLimit-Limit |
تعداد درخواست‌های مجاز در بازه فعلی |
X-RateLimit-Remaining |
تعداد درخواست‌های باقی‌مانده در بازه فعلی |
X-RateLimit-Reset |
زمان یونیکس بازنشانی بازه |
با عبور از محدودیت، 429 همراه با هدر Retry-After (ثانیه) دریافت می‌کنید. نظرسنجی طولانی با ?wait= در هر فراخوانی یک درخواست محسوب می‌شود، بنابراین انتظار کشیدن از نظرسنجی سریع‌تر ارزان‌تر است.
همچنین برای هر حساب، حداکثر ۱۰ درخواست در حال پردازش (queued یا running) مجاز است. شروع درخواست دیگر، 429 too_many_inflight برمی‌گرداند؛ پس از پایان یکی از درخواست‌ها دوباره آن را شروع کنید.