# Fíordheimhniú

Teastaíonn eochair API ó gach glao a ritheann samhail nó a léann d’iarratais. Tá an chatalóg (`GET /models`,
`GET /categories`), `POST /quote` agus an doiciméad OpenAPI poiblí.

## Eochracha API

Cruthaigh agus cúlghair eochracha ag [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Breathnaíonn eochair
mar `doitong_` agus 64 carachtar heicsidheachúlach ina dhiaidh agus taispeántar í uair amháin בלבד, nuair a chruthaíonn tú í. Seol í sa
ceanntásc `Authorization`:

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

Oibríonn `X-API-Key: <key>` chomh maith.

> [!WARNING]
> Coinnigh eochracha ar do fhreastalaí: is féidir le duine ar bith a bhfuil eochair aige na creidmheasanna API a bhfuil cead aige a chaitheamh a chaitheamh. Má sceitheann eochair,
> cúlghair í agus cruthaigh ceann nua.

Faigheann iarratas gan eochair `401` le cód `missing_api_key`; faigheann eochair anaithnid, chúlghairthe nó éagtha `401` chomh maith.

## Raonta feidhme

Iompraíonn gach eochair raonta feidhme. Seiceálann API na samhla iad seo:

| Gníomh | Raon feidhme riachtanach |
|---|---|
| Rith samhla, iarratas a chur ar ceal, comhaid iarratais a scriosadh, socrú na stórála a athrú | `models:run` (oibríonn eochracha leis an seanréim `images:create` nó `videos:create` chomh maith) |
| URL uaslódála a chruthú | `models:run` nó `media:upload` |
| Iarratais, cuntas a léamh | `models:read` (léann eochair a fhéadfaidh samhlacha a rith iad freisin) |

Faigheann eochracha nua `models:read` agus `models:run` de réir réamhshocraithe. Faigheann glao gan an raon feidhme ceart `403` le cód
`insufficient_scope`.

## Buiséid chreidmheasanna

Féadfaidh a bhuiséad féin a bheith ag eochair i gcreidmheasanna API (1,000 gcreidmheas API = $1), socraithe ag úinéir an chuntais: buiséad iomlán, buiséad
laethúil (na 24 uair an chloig dheireanacha), nó an dá cheann. Sula ngearrtar táille ar rith, déantar an costas a sheiceáil i gcoinne an méid atá caite ag an eochair cheana
tríd an API seo (glan ó aisíocaíochtaí). Diúltaítear do rith a sháródh é le `402 budget_exceeded` agus ní ghearrtar aon táille.

> [!IMPORTANT]
> Tá diúltú buiséid críochnaitheach: ní chabhróidh atriail go dtí go n-ardóidh an t-úinéir an buiséad.

Is féidir le heochair gan bhuiséad suas le hiarmhéid an API a chaitheamh. Ar leithligh, faigheann rith nach féidir leis an iarmhéid API a chlúdach `402 insufficient_credits`
le `top_up_url`.

Taispeánann `GET https://api.doitong.com/v1/account` iarmhéid an API agus buiséad fágtha na heochrach (iad araon i gcreidmheasanna API):

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

Bíonn `budget_remaining` `null` nuair nach bhfuil buiséad dá chuid féin ag an eochair.

## Teorainneacha ráta

Féadfaidh gach eochair 3600 iarratas a dhéanamh in aghaidh na huaire mura socraíodh a teorainn ar bhealach eile. Iompraíonn gach freagra fíordheimhnithe
staid reatha:

| Ceanntásc | Brí |
|---|---|
| `X-RateLimit-Limit` | Iarratais cheadaithe san fhuinneog reatha |
| `X-RateLimit-Remaining` | Iarratais fágtha san fhuinneog reatha |
| `X-RateLimit-Reset` | Am Unix nuair a athshocraítear an fhuinneog |

Má sháraíonn tú an teorainn, gheobhaidh tú `429` le ceanntásc `Retry-After` (soicind). Áirítear vótaíocht fhada le `?wait=` mar iarratas amháin
in aghaidh an ghlao, mar sin tá fanacht níos saoire ná vótaíocht thapa.

Tá teorainn de 10 n-iarratas ar siúl (`queued` nó `running`) in aghaidh an chuntais freisin. Seolann tosú ceann eile `429 too_many_inflight`; cuir tús leis arís tar éis do cheann críochnú.