# Dearbhadh

Feumaidh gach gairm a ruitheas modail no a leughas na h-iarrtasan agad iuchair API. Tha an catalog (`GET /models`,
`GET /categories`), `POST /quote` agus an sgrìobhainn OpenAPI poblach.

## Iuchraichean API

Cruthaich agus cùl-ghairm iuchraichean aig [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Tha iuchair coltach ri
`doitong_` air a leantainn le 64 caractar hexadecimal agus cha nochd i ach aon turas, nuair a chruthaicheas tu i. Cuir i sa
bhann-cinn `Authorization`:

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

Obraichidh `X-API-Key: <key>` cuideachd.

> [!WARNING]
> Cùm iuchraichean air an fhrithealaiche agad: faodaidh duine sam bith aig a bheil iuchair na creideasan API a tha ceadaichte dhi a chosg. Ma aoidicheas iuchair,
> cùl-ghairm i agus cruthaich tè ùr.

Gheibh iarrtas gun iuchair `401` leis a’ chòd `missing_api_key`; gheibh iuchair neo-aithnichte, cùl-ghairmte no a dh’fhalbh an ùine `401` cuideachd.

## Raointean

Bidh raointean aig gach iuchair. Nì an API modail sgrùdadh orra seo:

| Gnìomh | Raon a dhìth |
|---|---|
| Ruith modail, cuir dheth iarrtas, sguab às faidhlichean iarrtais, atharraich suidheachadh an stòraidh | `models:run` (obraichidh iuchraichean leis an fheadhainn as sine `images:create` no `videos:create` cuideachd) |
| Cruthaich URL luchdaidh suas | `models:run` no `media:upload` |
| Leugh iarrtasan, cunntas | `models:read` (bidh iuchair a dh’fhaodas modalan a ruith comasach air an leughadh cuideachd) |

Gheibh iuchraichean ùra `models:read` agus `models:run` mar bhun-roghainn. Gheibh gairm gun an raon cheart `403` leis a’ chòd
`insufficient_scope`.

## Buidseatan creideasan

Faodaidh a bhuidseat fhèin a bhith aig iuchair ann an creideasan API (1,000 creideasan API = $1), air a shuidheachadh le sealbhadair a’ chunntais: buidseat iomlan, buidseat
làitheil (na 24 uairean mu dheireadh), no an dà chuid. Mus tèid cosgais a chur air ruith, thèid a’ chosgais a choimeas ris na tha an iuchair air a chosg mar-thà
tron API seo (às dèidh ais-phàighidhean). Thèid ruith a bhiodh nas motha na sin a dhiùltadh le `402 budget_exceeded` agus cha tèid cosgais sam bith a chur air.

> [!IMPORTANT]
> Tha diùltadh buidseit deireannach: cha chuidich ath-iarrtas gus an tog an sealbhadair am buidseat.

 Faodaidh iuchair gun bhuidseat suas ri iarmad an API a chosg. Air leth, gheibh ruith nach urrainn don iarmad API a chòmhdach
`402 insufficient_credits` le `top_up_url`.

Tha `GET https://api.doitong.com/v1/account` a’ sealltainn iarmad an API agus buidseat air fhàgail na h-iuchrach (an dà chuid ann an creideasan API):

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

Tha `budget_remaining` aig `null` nuair nach eil buidseat fhèin aig an iuchair.

## Crìochan reata

Faodaidh gach iuchair 3600 iarrtas a dhèanamh gach uair mura deach a crìoch a shuidheachadh ann an dòigh eile. Bidh staid làithreach aig gach freagairt dhearbhaichte:

| Bann-cinn | Ciall |
|---|---|
| `X-RateLimit-Limit` | Iarrtasan ceadaichte san uinneag làithreach |
| `X-RateLimit-Remaining` | Iarrtasan air fhàgail san uinneag làithreach |
| `X-RateLimit-Reset` | Àm Unix nuair a nì an uinneag ath-shuidheachadh |

Ma thèid thu thairis air a’ chrìoch gheibh thu `429` le bann-cinn `Retry-After` (diogan). Tha bhòtadh fada le `?wait=` a’ cunntadh mar aon iarrtas
gach gairm, mar sin tha feitheamh nas saoire na bhòtadh gu luath.

Tha crìoch eile de 10 iarrtasan a’ dol air adhart (`queued` no `running`) gach cunntas. Tillidh tòiseachadh air aon eile `429 too_many_inflight`; tòisich a-rithist e
às dèidh do aon chrìochnachadh.