# Uthibitishaji

Kila mwito unaoendesha modeli au kusoma maombi yako unahitaji ufunguo wa API. Katalogi (`GET /models`,
`GET /categories`), `POST /quote` na hati ya OpenAPI ni za umma.

## Funguo za API

Unda na ubatilishe funguo kwenye [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Ufunguo huonekana
kama `doitong_` ikifuatiwa na vibambo 64 vya heksadesimali na huonyeshwa mara moja tu unapouunda. Utume katika kichwa cha
`Authorization`:

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

`X-API-Key: <key>` pia hufanya kazi.

> [!WARNING]
> Hifadhi funguo kwenye seva yako: mtu yeyote aliye na ufunguo anaweza kutumia krediti za API ambazo unaruhusiwa kutumia. Ikiwa ufunguo
> umevuja, ubatilishe na uunde mpya.

Ombi lisilo na ufunguo hupata `401` yenye msimbo `missing_api_key`; ufunguo usiojulikana, uliobatilishwa au ulioisha muda hupata `401` pia.

## Wigo wa ruhusa

Kila ufunguo una wigo wa ruhusa. API ya modeli hukagua hizi:

| Kitendo | Wigo unaohitajika |
|---|---|
| Endesha modeli, ghairi ombi, futa faili za ombi, badilisha mipangilio ya hifadhi | `models:run` (funguo zenye `images:create` au `videos:create` ya zamani pia hufanya kazi) |
| Unda URL ya kupakia | `models:run` au `media:upload` |
| Soma maombi, akaunti | `models:read` (ufunguo unaoweza kuendesha modeli pia unaweza kusoma) |

Funguo mpya hupata `models:read` na `models:run` kwa chaguomsingi. Mwito usio na wigo sahihi hupata `403` yenye msimbo
`insufficient_scope`.

## Bajeti za krediti

Ufunguo unaweza kuwa na bajeti yake katika krediti za API (salio za API 1,000 = $ 1), iliyowekwa na mmiliki wa akaunti: bajeti ya jumla,
bajeti ya kila siku (saa 24 zilizopita), au zote mbili. Kabla ya uendeshaji kutozwa, gharama hukaguliwa dhidi ya kiasi ambacho
ufunguo umetumia tayari kupitia API hii (baada ya marejesho ya fedha). Uendeshaji ambao ungeizidi hukataliwa kwa `402 budget_exceeded`
na hakuna kinachotozwa.

> [!IMPORTANT]
> Kukataliwa kwa sababu ya bajeti ni kwa mwisho: kujaribu tena hakutasaidia hadi mmiliki aongeze bajeti.

 Ufunguo usio na bajeti unaweza kutumia hadi salio la API. Kando na hilo, uendeshaji ambao salio la API haliwezi kugharamia hupata
`402 insufficient_credits` yenye `top_up_url`.

`GET https://api.doitong.com/v1/account` huonyesha salio la API na bajeti iliyosalia ya ufunguo (zote kwa krediti za API):

```json 200 OK · account
{
  "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` ni `null` wakati ufunguo hauna bajeti yake.

## Vikomo vya kasi

Kila ufunguo unaweza kufanya maombi 3600 kwa saa isipokuwa kikomo chake kimewekwa tofauti. Kila jibu lililothibitishwa huwa na
hali ya sasa:

| Kichwa | Maana |
|---|---|
| `X-RateLimit-Limit` | Maombi yanayoruhusiwa katika dirisha la sasa |
| `X-RateLimit-Remaining` | Maombi yaliyosalia katika dirisha la sasa |
| `X-RateLimit-Reset` | Muda wa Unix dirisha linapowekwa upya |

Ukizidi kikomo utapata `429` yenye kichwa cha `Retry-After` (sekunde). Upigaji kura mrefu wenye `?wait=` huhesabiwa kama ombi moja
kwa kila mwito, kwa hivyo kusubiri ni nafuu kuliko kupiga kura haraka.

Pia kuna kikomo cha maombi 10 yanayoendelea (`queued` au `running`) kwa kila akaunti. Kuanzisha jingine hurudisha
`429 too_many_inflight`; lianzishe tena baada ya moja kukamilika.