# Dilysu

Mae angen allwedd API ar bob galwad sy'n rhedeg model neu'n darllen eich ceisiadau. Mae'r catalog (`GET /models`, `GET /categories`), `POST /quote` a dogfen OpenAPI yn gyhoeddus.

## Allweddi API

Crëwch a dirymwch allweddi yn [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Mae allwedd yn edrych fel `doitong_` wedi'i ddilyn gan 64 nod hecsadegol ac fe'i dangosir unwaith yn unig, pan fyddwch yn ei chreu. Anfonwch hi ym mhennyn `Authorization`:

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

Mae `X-API-Key: <key>` yn gweithio hefyd.

> [!WARNING]
> Cadwch allweddi ar eich gweinydd: gall unrhyw un sydd ag allwedd wario'r credydau API y caniateir iddi eu gwario. Os bydd allwedd yn gollwng, dirymwch hi a chrëwch un newydd.

Mae cais heb allwedd yn cael `401` gyda'r cod `missing_api_key`; mae allwedd anhysbys, ddirymedig neu sydd wedi dod i ben yn cael `401` hefyd.

## Cwmpasau

Mae pob allwedd yn cynnwys cwmpasau. Mae'r API model yn gwirio'r rhain:

| Gweithred | Cwmpas angenrheidiol |
|---|---|
| Rhedeg model, canslo cais, dileu ffeiliau cais, newid y gosodiad storio | `models:run` (mae allweddi gyda'r `images:create` neu `videos:create` hŷn hefyd yn gweithio) |
| Creu URL uwchlwytho | `models:run` neu `media:upload` |
| Darllen ceisiadau, cyfrif | `models:read` (mae allwedd sy'n gallu rhedeg modelau yn gallu darllen hefyd) |

Mae allweddi newydd yn cael `models:read` a `models:run` yn rhagosodedig. Mae galwad heb y cwmpas cywir yn cael `403` gyda'r cod `insufficient_scope`.

## Cyllidebau credydau

Gall allwedd gynnwys ei chyllideb ei hun mewn credydau API (1,000 o gredydau API = $1), wedi'i gosod gan berchennog y cyfrif: cyfanswm cyllideb, cyllideb ddyddiol (y 24 awr ddiwethaf), neu'r ddwy. Cyn codi tâl am rediad, caiff y gost ei gwirio yn erbyn yr hyn y mae'r allwedd eisoes wedi'i wario drwy'r API hwn (ar ôl ad-daliadau). Gwrthodir rhediad a fyddai'n mynd dros y terfyn gyda `402 budget_exceeded` ac ni chodir tâl.

> [!IMPORTANT]
> Mae gwrthodiad cyllideb yn derfynol: ni fydd ailgais yn helpu nes bod y perchennog yn cynyddu'r gyllideb.

 Gall allwedd heb gyllideb wario hyd at falans yr API. Ar wahân, mae rhediad na all balans yr API ei dalu yn cael `402 insufficient_credits` gyda `top_up_url`.

Mae `GET https://api.doitong.com/v1/account` yn dangos balans yr API a chyllideb weddill yr allwedd (y ddau mewn credydau API):

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

Mae `budget_remaining` yn `null` pan nad oes gan yr allwedd gyllideb ei hun.

## Terfynau cyfradd

Gall pob allwedd wneud 3600 o geisiadau yr awr oni bai bod ei therfyn wedi'i osod yn wahanol. Mae pob ymateb dilysedig yn cynnwys y cyflwr cyfredol:

| Pennyn | Ystyr |
|---|---|
| `X-RateLimit-Limit` | Ceisiadau a ganiateir yn y ffenestr gyfredol |
| `X-RateLimit-Remaining` | Ceisiadau sy'n weddill yn y ffenestr gyfredol |
| `X-RateLimit-Reset` | Amser Unix pan fydd y ffenestr yn ailosod |

Dros y terfyn, cewch `429` gyda phennyn `Retry-After` (eiliadau). Mae pleidleisio hir gyda `?wait=` yn cyfrif fel un cais fesul galwad, felly mae aros yn rhatach na phleidleisio'n gyflym.

Mae terfyn o 10 cais ar waith (`queued` neu `running`) fesul cyfrif hefyd. Mae dechrau un arall yn dychwelyd `429 too_many_inflight`; dechreuwch ef eto ar ôl i un orffen.