# אימות

כל קריאה שמריצה מודל או קוראת את הבקשות שלכם דורשת מפתח API. הקטלוג (`GET /models`,‏ `GET /categories`),‏ `POST /quote` ומסמך OpenAPI הם ציבוריים.

## מפתחות API

צרו ובטלו מפתחות בכתובת [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). מפתח נראה כמו `doitong_` ואחריו 64 תווים הקסדצימליים, והוא מוצג פעם אחת בלבד, בעת יצירתו. שלחו אותו בכותרת `Authorization`:

```bash
curl https://api.doitong.com/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 (1,000 קרדיטי API = ⁨‏1 ‏$⁩), שנקבע על ידי בעל החשבון: תקציב כולל, תקציב יומי (24 השעות האחרונות), או שניהם. לפני חיוב הרצה, העלות נבדקת מול הסכום שהמפתח כבר הוציא דרך API זה (בניכוי החזרים). הרצה שתחרוג ממנו נדחית עם `402 budget_exceeded` ולא מתבצע חיוב.

> [!IMPORTANT]
> דחיית תקציב היא סופית: ניסיון חוזר לא יעזור עד שהבעלים יגדיל את התקציב.

מפתח ללא תקציב יכול להוציא עד גובה יתרת ה-API. בנפרד, הרצה שיתרת ה-API אינה יכולה לכסות מקבלת `402 insufficient_credits` עם `top_up_url`.

`GET https://api.doitong.com/v1/account` מציג את יתרת ה-API ואת התקציב שנותר למפתח (שניהם בקרדיטי API):

```json 200 OK · חשבון
{
  "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` כאשר אין למפתח תקציב משלו.

## מגבלות קצב

כל מפתח יכול לבצע 3600 בקשות בשעה, אלא אם המגבלה שלו הוגדרה אחרת. כל תשובה מאומתת כוללת את המצב הנוכחי:

| כותרת | משמעות |
|---|---|
| `X-RateLimit-Limit` | מספר הבקשות המותר בחלון הנוכחי |
| `X-RateLimit-Remaining` | מספר הבקשות שנותר בחלון הנוכחי |
| `X-RateLimit-Reset` | זמן Unix שבו החלון מתאפס |

חריגה מהמגבלה מחזירה `429` עם כותרת `Retry-After` (בשניות). תשאול ארוך עם `?wait=` נספר כבקשה אחת בכל קריאה, ולכן המתנה זולה יותר מתשאול מהיר.

קיימת גם מגבלה של 10 בקשות בתהליך (`queued` או `running`) לכל חשבון. התחלה של בקשה נוספת מחזירה `429 too_many_inflight`; התחילו אותה שוב לאחר שאחת מהן תסתיים.