# Pengesahan

Setiap panggilan yang menjalankan model atau membaca permintaan anda memerlukan kunci API. Katalog (`GET /models`, `GET /categories`), `POST /quote` dan dokumen OpenAPI adalah awam.

## Kunci API

Cipta dan batalkan kunci di [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Kunci kelihatan seperti `doitong_` diikuti 64 aksara heksadesimal dan hanya dipaparkan sekali, ketika anda menciptanya. Hantar kunci itu dalam pengepala `Authorization`:

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

`X-API-Key: <key>` juga berfungsi.

> [!WARNING]
> Simpan kunci pada pelayan anda: sesiapa yang mempunyai kunci boleh membelanjakan kredit API yang dibenarkan untuknya. Jika kunci terdedah, batalkannya dan cipta yang baharu.

Permintaan tanpa kunci menerima `401` dengan kod `missing_api_key`; kunci yang tidak dikenali, telah dibatalkan atau telah tamat tempoh juga menerima `401`.

## Skop

Setiap kunci mempunyai skop. API model menyemak perkara berikut:

| Tindakan | Skop diperlukan |
|---|---|
| Jalankan model, batalkan permintaan, padam fail permintaan, ubah tetapan storan | `models:run` (kunci dengan `images:create` atau `videos:create` yang lebih lama juga berfungsi) |
| Cipta URL muat naik | `models:run` atau `media:upload` |
| Baca permintaan, akaun | `models:read` (kunci yang boleh menjalankan model juga boleh membaca) |

Kunci baharu mendapat `models:read` dan `models:run` secara lalai. Panggilan tanpa skop yang betul menerima `403` dengan kod `insufficient_scope`.

## Belanjawan kredit

Kunci boleh mempunyai belanjawannya sendiri dalam kredit API (1,000 kredit API = $1), yang ditetapkan oleh pemilik akaun: jumlah belanjawan, belanjawan harian (24 jam terakhir), atau kedua-duanya. Sebelum penjanaan dicaj, kos disemak berbanding jumlah yang telah dibelanjakan oleh kunci melalui API ini (selepas bayaran balik). Penjanaan yang akan melebihinya ditolak dengan `402 budget_exceeded` dan tiada caj dikenakan.

> [!IMPORTANT]
> Penolakan belanjawan adalah muktamad: percubaan semula tidak akan membantu sehingga pemilik menaikkan belanjawan.

Kunci tanpa belanjawan boleh membelanjakan sehingga baki API. Secara berasingan, penjanaan yang tidak dapat ditampung oleh baki API menerima `402 insufficient_credits` dengan `top_up_url`.

`GET https://api.doitong.com/v1/account` memaparkan baki API dan baki belanjawan kunci (kedua-duanya dalam kredit API):

```json 200 OK · akaun
{
  "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` ialah `null` apabila kunci tidak mempunyai belanjawan sendiri.

## Had kadar

Setiap kunci boleh membuat 3600 permintaan sejam melainkan hadnya ditetapkan secara berbeza. Setiap respons yang disahkan membawa keadaan semasa:

| Pengepala | Maksud |
|---|---|
| `X-RateLimit-Limit` | Permintaan yang dibenarkan dalam tetingkap semasa |
| `X-RateLimit-Remaining` | Permintaan yang masih ada dalam tetingkap semasa |
| `X-RateLimit-Reset` | Masa Unix apabila tetingkap ditetapkan semula |

Jika melebihi had, anda menerima `429` dengan pengepala `Retry-After` (saat). Tinjauan berkala yang lama dengan `?wait=` dikira sebagai satu permintaan bagi setiap panggilan, jadi menunggu lebih menjimatkan daripada meninjau dengan cepat.

Terdapat juga had 10 permintaan yang sedang berjalan (`queued` atau `running`) bagi setiap akaun. Memulakan satu lagi akan mengembalikan `429 too_many_inflight`; mulakannya semula selepas satu selesai.