# אָטענטיפֿיקאַציע

יעדער רוף וואָס לויפֿט אַ מאָדעל אָדער לייענט אײַערע בקשות דאַרף אַן 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`; אָנהייבט עס ווידער נאָך דעם ווי איינע ענדיקט זיך.