# Έλεγχος ταυτότητας

Κάθε κλήση που εκτελεί ένα μοντέλο ή διαβάζει τα αιτήματά σας χρειάζεται ένα κλειδί API. Ο κατάλογος (`GET /models`,
`GET /categories`), το `POST /quote` και το έγγραφο OpenAPI είναι δημόσια.

## Κλειδιά API

Δημιουργήστε και ανακαλέστε κλειδιά στη διεύθυνση [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Ένα κλειδί έχει τη μορφή `doitong_` ακολουθούμενο από 64 δεκαεξαδικούς χαρακτήρες και εμφανίζεται μόνο μία φορά, όταν το δημιουργείτε. Στείλτε το στην κεφαλίδα
`Authorization`:

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

Το `X-API-Key: <key>` λειτουργεί επίσης.

> [!WARNING]
> Διατηρείτε τα κλειδιά στον διακομιστή σας: οποιοσδήποτε διαθέτει ένα κλειδί μπορεί να δαπανήσει τις πιστώσεις API που επιτρέπεται να δαπανήσει. Αν διαρρεύσει ένα κλειδί,
> ανακαλέστε το και δημιουργήστε ένα νέο.

Ένα αίτημα χωρίς κλειδί λαμβάνει `401` με τον κωδικό `missing_api_key`. Ένα άγνωστο, ανακληθέν ή ληγμένο κλειδί λαμβάνει επίσης `401`.

## Εμβέλειες

Κάθε κλειδί διαθέτει εμβέλειες. Το API μοντέλων ελέγχει τις εξής:

| Ενέργεια | Απαιτούμενη εμβέλεια |
|---|---|
| Εκτέλεση μοντέλου, ακύρωση αιτήματος, διαγραφή των αρχείων ενός αιτήματος, αλλαγή της ρύθμισης αποθήκευσης | `models:run` (λειτουργούν επίσης κλειδιά με τα παλαιότερα `images:create` ή `videos:create`) |
| Δημιουργία URL μεταφόρτωσης | `models:run` ή `media:upload` |
| Ανάγνωση αιτημάτων, λογαριασμού | `models:read` (ένα κλειδί που μπορεί να εκτελεί μοντέλα μπορεί επίσης να τα διαβάζει) |

Τα νέα κλειδιά λαμβάνουν `models:read` και `models:run` από προεπιλογή. Μια κλήση χωρίς τη σωστή εμβέλεια λαμβάνει `403` με τον κωδικό
`insufficient_scope`.

## Προϋπολογισμοί πιστώσεων

Ένα κλειδί μπορεί να έχει τον δικό του προϋπολογισμό σε πιστώσεις API (1.000 πιστώσεις API = 1 $), που ορίζεται από τον κάτοχο του λογαριασμού: συνολικό προϋπολογισμό, ημερήσιο προϋπολογισμό (τελευταίες 24 ώρες) ή και τα δύο. Πριν χρεωθεί μια εκτέλεση, το κόστος ελέγχεται σε σχέση με όσα έχει ήδη δαπανήσει το κλειδί μέσω αυτού του API (μετά τις επιστροφές χρημάτων). Μια εκτέλεση που θα τον υπερέβαινε απορρίπτεται με `402 budget_exceeded` και δεν χρεώνεται τίποτα.

> [!IMPORTANT]
> Η απόρριψη λόγω προϋπολογισμού είναι οριστική: η επανάληψη δεν θα βοηθήσει μέχρι ο κάτοχος να αυξήσει τον προϋπολογισμό.

 Ένα κλειδί χωρίς προϋπολογισμό μπορεί να δαπανήσει έως το υπόλοιπο API. Ξεχωριστά, μια εκτέλεση που δεν μπορεί να καλυφθεί από το υπόλοιπο API λαμβάνει `402 insufficient_credits`
με ένα `top_up_url`.

Το `GET https://api.doitong.com/v1/account` εμφανίζει το υπόλοιπο API και τον εναπομείναντα προϋπολογισμό του κλειδιού (και τα δύο σε πιστώσεις API):

```json 200 OK · λογαριασμός
{
  "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` είναι `null` όταν το κλειδί δεν έχει δικό του προϋπολογισμό.

## Όρια ρυθμού

Κάθε κλειδί μπορεί να εκτελεί 3600 αιτήματα ανά ώρα, εκτός αν το όριό του έχει οριστεί διαφορετικά. Κάθε ελεγμένη ταυτότητα απόκριση περιέχει την τρέχουσα κατάσταση:

| Κεφαλίδα | Σημασία |
|---|---|
| `X-RateLimit-Limit` | Αιτήματα που επιτρέπονται στο τρέχον παράθυρο |
| `X-RateLimit-Remaining` | Αιτήματα που απομένουν στο τρέχον παράθυρο |
| `X-RateLimit-Reset` | Ώρα Unix κατά την οποία επαναφέρεται το παράθυρο |

Όταν υπερβείτε το όριο, λαμβάνετε `429` με μια κεφαλίδα `Retry-After` (δευτερόλεπτα). Η μακρά περιοδική αναζήτηση με `?wait=` μετρά ως ένα αίτημα ανά κλήση, επομένως η αναμονή είναι οικονομικότερη από τη γρήγορη περιοδική αναζήτηση.

Υπάρχει επίσης όριο 10 αιτημάτων σε εξέλιξη (`queued` ή `running`) ανά λογαριασμό. Η έναρξη ενός ακόμη επιστρέφει
`429 too_many_inflight`. Ξεκινήστε το ξανά αφού ολοκληρωθεί ένα.