# Аутентификация

Модельді іске қосатын немесе сұрауларыңызды оқитын әр қоңырауға 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 кредиттерін жұмсай алады. Кілт сыртқа шығып кетсе, оны кері қайтарып, жаңасын жасаңыз.

Кілтсіз сұрау `missing_api_key` коды бар `401` жауабын алады; белгісіз, кері қайтарылған немесе мерзімі өткен кілт те `401` алады.

## Ауқымдар

Әр кілттің ауқымдары болады. Модель API-і мыналарды тексереді:

| Әрекет | Қажетті ауқым |
|---|---|
| Модельді іске қосу, сұрауды тоқтату, сұрау файлдарын жою, сақтау орны параметрін өзгерту | `models:run` (ескі `images:create` немесе `videos:create` мәндері бар кілттер де жұмыс істейді) |
| Жүктеп салу URL-ын жасау | `models:run` немесе `media:upload` |
| Сұрауларды, есептік жазбаны оқу | `models:read` (модельдерді іске қоса алатын кілттер де оқи алады) |

Жаңа кілттерге әдепкі бойынша `models:read` және `models:run` беріледі. Дұрыс ауқымы жоқ қоңырау `insufficient_scope` коды бар `403` жауабын алады.

## Кредит бюджеттері

Кілттің есептік жазба иесі белгілеген API кредиттеріндегі (1 000 API кредиті = 1 $) жеке бюджеті болуы мүмкін: жалпы бюджет, тәуліктік бюджет (соңғы 24 сағат) немесе екеуі де. Орындалу үшін ақы алынбас бұрын, құн кілттің осы API арқылы жұмсаған сомасымен (қайтарымдарды шегергенде) салыстырылады. Бюджеттен асып кететін орындаудан `402 budget_exceeded` қатесімен бас тартылады және ақы алынбайды.

> [!IMPORTANT]
> Бюджеттен бас тарту — түпкілікті шешім: иесі бюджетті арттырмайынша, қайта жіберу көмектеспейді.

Бюджеті жоқ кілт API теңгеріміне дейін жұмсай алады. Бұған қоса, API теңгерімі жаба алмайтын орындау `top_up_url` мәні бар `402 insufficient_credits` жауабын қайтарады.

`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 уақыты |

Шектен ассаңыз, `Retry-After` тақырыбы (секунд) бар `429` жауабын аласыз. `?wait=` арқылы ұзақ сауалнама әр қоңырауға бір сұрау ретінде есептеледі, сондықтан күту жиі сауалнама жіберуден арзанырақ.

Бұған қоса, әр есептік жазбада орындалып жатқан (`queued` немесе `running`) сұраулар саны 10-мен шектеледі. Тағы біреуін бастау `429 too_many_inflight` жауабын қайтарады; біреуі аяқталғаннан кейін қайта бастаңыз.