# احراز هویت

هر فراخوانی که مدلی را اجرا می‌کند یا درخواست‌های شما را می‌خواند، به کلید API نیاز دارد. کاتالوگ (`GET /models`، `GET /categories`)، `POST /quote` و سند OpenAPI عمومی هستند.

## کلیدهای API

در [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys) کلیدها را بسازید و لغو کنید. یک کلید مانند `doitong_` است که پس از آن ۶۴ نویسه هگزادسیمال می‌آید و هنگام ایجاد فقط یک‌بار نمایش داده می‌شود. آن را در هدر `Authorization` ارسال کنید:

```bash
curl https://api.doitong.ru/v1/account -H "Authorization: Bearer $DOITONG_API_KEY"
```

`X-API-Key: <key>` نیز کار می‌کند.

> [!WARNING]
> کلیدها را روی سرور خود نگه دارید: هرکس کلیدی داشته باشد می‌تواند اعتبار API مجاز برای آن را مصرف کند. اگر کلیدی افشا شد، آن را لغو کنید و کلید جدیدی بسازید.

درخواست بدون کلید، `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` رد می‌شود و چیزی کسر نمی‌شود.

> [!IMPORTANT]
> رد شدن به‌دلیل بودجه نهایی است: تلاش مجدد تا زمانی که مالک بودجه را افزایش دهد کمکی نمی‌کند.

کلیدی که بودجه ندارد می‌تواند تا سقف موجودی API هزینه کند. جدا از این، اگر موجودی API نتواند هزینه اجرا را پوشش دهد، `402 insufficient_credits` همراه با `top_up_url` دریافت می‌کنید.

`GET https://api.doitong.ru/v1/account` موجودی API و بودجه باقی‌مانده کلید را نشان می‌دهد (هر دو برحسب اعتبار API):

```json 200 OK · حساب
{
  "object": "account",
  "credits": 125000,
  "balance": { "credits": 125000, "usd": "125.00" },
  "top_up_url": "https://doitong.ru/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` برمی‌گرداند؛ پس از پایان یکی از درخواست‌ها دوباره آن را شروع کنید.