# Motuhēhēnga

Me whai kī API ia karanga e whakahaere ana i tētahi tauira, e pānui ana rānei i ō tono. He tūmatanui te rārangi (`GET /models`,
`GET /categories`), `POST /quote` me te tuhinga OpenAPI.

## Ngā kī API

Waihangahia, whakakorehia hoki ngā kī ki [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). He rite te kī
ki `doitong_` whai muri ko ngā pūāhua hautekaumāono 64, ā, kotahi anake te wā ka whakaaturia, ina waihanga koe. Tukua ki te
pane `Authorization`:

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

Ka mahi hoki `X-API-Key: <key>`.

> [!WARNING]
> Puritia ngā kī ki tō tūmau: mā te tangata kei a ia he kī e whakapau ngā whiwhinga API e whakaaetia ana kia whakapaua. Mēnā ka turuturu
> tētahi kī, whakakorehia, ka waihanga i tētahi kī hou.

Ka whiwhi tētahi tono kāore he kī i `401` me te waehere `missing_api_key`; ka whiwhi hoki tētahi kī kāore e mōhiotia ana, kua whakakorea, kua pau rānei i `401`.

## Ngā whānuitanga

He whānuitanga tō ia kī. Ka tirohia ēnei e te API tauira:

| Mahi | Whānuitanga e hiahiatia ana |
|---|---|
| Whakahaere tauira, whakakore tono, muku i ngā kōnae o tētahi tono, huri i te tautuhinga rokiroki | `models:run` (ka mahi hoki ngā kī me `images:create`, `videos:create` tawhito) |
| Waihanga URL tukuake | `models:run` rānei `media:upload` |
| Pānui tono, pūkete | `models:read` (ka pānui hoki tētahi kī ka taea te whakahaere tauira) |

Ka whiwhi ngā kī hou i `models:read` me `models:run` mā te taunoa. Ka whiwhi te karanga kāore i te whānuitanga tika i `403` me te waehere `insufficient_scope`.

## Ngā pūtea whiwhinga

Ka taea e tētahi kī tōna ake pūtea i roto i ngā whiwhinga API (1,000 whiwhinga API = $ 1), nā te kaiwhiwhi pūkete i whakarite: pūtea tapeke, pūtea ia rā (ngā hāora 24 kua hipa), e rua rānei. I mua i te utu o tētahi whakahaere, ka whakatauritea te utu ki ngā mea kua whakapaua kētia e te kī mā tēnei API (i muri i ngā whakahokinga pūtea). Ka whakakorehia tētahi whakahaere ka hipa i taua pūtea me `402 budget_exceeded`, ā, kāore he utu.

> [!IMPORTANT]
> He whakatau whakamutunga te whakakore pūtea: kāore te ngana anō e whai hua kia whakanuia ra anō e te rangatira te pūtea.

Mā tētahi kī kāore he pūtea e whakapau kia eke ki te toenga API. Motuhake, ka whiwhi tētahi whakahaere kāore e taea e te toenga API te utu i `402 insufficient_credits` me tētahi `top_up_url`.

Ka whakaatu a `GET https://api.doitong.com/v1/account` i te toenga API me te pūtea e toe ana o te kī (kei roto e rua i ngā whiwhinga API):

```json 200 OK · pūkete
{
  "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_..."
}
```

Ko `budget_remaining` he `null` ina kāore he pūtea ake o te kī.

## Ngā here auau

Ka taea e ia kī te tuku 3600 tono ia hāora, engari mēnā kua rerekē te whakarite o tōna here. Kei ia whakautu kua motuhēhē te āhua o nāianei:

| Pane | Tikanga |
|---|---|
| `X-RateLimit-Limit` | Ngā tono e whakaaetia ana i te wāhanga o nāianei |
| `X-RateLimit-Remaining` | Ngā tono e toe ana i te wāhanga o nāianei |
| `X-RateLimit-Reset` | Te wā Unix e tautuhi anō ai te wāhanga |

Ki te hipa i te here, ka whiwhi koe i `429` me te pane `Retry-After` (hēkona). Ko te pōti roa me `?wait=` ka tatau hei tono kotahi mō ia karanga, nō reira he iti ake te utu o te tatari i te pōti tere.

He here anō mō ngā tono 10 e haere ana (`queued`, `running` rānei) mō ia pūkete. Ka whakahoki te tīmata i tētahi atu i `429 too_many_inflight`; tīmatahia anō ina mutu tētahi.