# Kimlik doğrulama

Bir modeli çalıştıran veya isteklerinizi okuyan her çağrı için API anahtarı gerekir. Katalog (`GET /models`, `GET /categories`), `POST /quote` ve OpenAPI belgesi herkese açıktır.

## API anahtarları

[https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys) adresinden anahtar oluşturun ve iptal edin. Bir anahtar, `doitong_` ile başlayan 64 onaltılık karakterden oluşur ve oluşturduğunuz anda yalnızca bir kez gösterilir. Anahtarı `Authorization` başlığında gönderin:

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

`X-API-Key: <key>` de çalışır.

> [!WARNING]
> Anahtarları sunucunuzda tutun: anahtara sahip olan herkes, harcamasına izin verilen API kredisini harcayabilir. Bir anahtar sızarsa onu iptal edin ve yenisini oluşturun.

Anahtarsız bir istek, `missing_api_key` koduyla `401` alır; bilinmeyen, iptal edilmiş veya süresi dolmuş bir anahtar da `401` alır.

## Kapsamlar

Her anahtar kapsamlar taşır. Model API'si bunları denetler:

| Eylem | Gerekli kapsam |
|---|---|
| Bir modeli çalıştırma, bir isteği iptal etme, isteğin dosyalarını silme, depolama ayarını değiştirme | `models:run` (daha eski `images:create` veya `videos:create` kapsamlarına sahip anahtarlar da çalışır) |
| Yükleme URL'si oluşturma | `models:run` veya `media:upload` |
| İstekleri ve hesabı okuma | `models:read` (modelleri çalıştırabilen bir anahtar da okuyabilir) |

Yeni anahtarlara varsayılan olarak `models:read` ve `models:run` verilir. Doğru kapsam olmadan yapılan bir çağrı, `insufficient_scope` koduyla `403` alır.

## Kredi bütçeleri

Bir anahtar, hesap sahibi tarafından belirlenen API kredisi cinsinden kendi bütçesini taşıyabilir (1.000 API kredisi = $1): toplam bütçe, günlük bütçe (son 24 saat) veya her ikisi. Bir çalıştırma ücretlendirilmeden önce maliyet, anahtarın bu API üzerinden şimdiye kadar harcadığı tutarla (iadeler düşüldükten sonra) karşılaştırılır. Bütçeyi aşacak bir çalıştırma `402 budget_exceeded` ile reddedilir ve ücret alınmaz.

> [!IMPORTANT]
> Bütçe reddi kesindir: sahibi bütçeyi artırana kadar yeniden denemek işe yaramaz.

Bütçesi olmayan bir anahtar, API bakiyesine kadar harcama yapabilir. Ayrıca API bakiyesinin karşılayamadığı bir çalıştırma, `top_up_url` ile birlikte `402 insufficient_credits` alır.

`GET https://api.doitong.ru/v1/account`, API bakiyesini ve anahtarın kalan bütçesini (ikisi de API kredisi cinsinden) gösterir:

```json 200 OK · hesap
{
  "object": "account",
  "credits": 125000,
  "balance": { "credits": 125000, "usd": "125.00" },
  "top_up_url": "https://doitong.ru/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_..."
}
```

Anahtarın kendine ait bütçesi olmadığında `budget_remaining` değeri `null` olur.

## Hız sınırları

Her anahtar, sınırı farklı ayarlanmadıysa saatte 3600 istek yapabilir. Kimliği doğrulanmış her yanıt mevcut durumu içerir:

| Başlık | Anlamı |
|---|---|
| `X-RateLimit-Limit` | Mevcut pencerede izin verilen istek sayısı |
| `X-RateLimit-Remaining` | Mevcut pencerede kalan istek sayısı |
| `X-RateLimit-Reset` | Pencerenin sıfırlanacağı Unix zamanı |

Sınırı aşarsanız `Retry-After` başlığıyla birlikte `429` alırsınız (saniye). `?wait=` ile uzun yoklama, çağrı başına bir istek sayılır; bu nedenle beklemek, sık aralıklarla yoklama yapmaktan daha ekonomiktir.

Ayrıca hesap başına ilerleme durumunda (`queued` veya `running`) en fazla 10 istek olabilir. Bir istek daha başlatmak `429 too_many_inflight` döndürür; biri tamamlandıktan sonra yeniden başlatın.