# Αιτήματα

Ένα αίτημα είναι μία κλήση ενός μοντέλου. Έχει ένα id (`req_…`), μια κατάσταση, το κόστος του σε πιστώσεις API (1000 = 1 USD) και, όταν ολοκληρωθεί με επιτυχία, τα αρχεία που δημιουργήθηκαν. Το ίδιο αντικείμενο επιστρέφεται από κάθε παρακάτω τελικό σημείο, για κάθε μοντέλο.

## Εύρεση μοντέλου

Ο κατάλογος και των 1.496 μοντέλων είναι δημόσιο JSON (δεν απαιτείται κλειδί):

```bash
curl "https://api.doitong.com/v1/models?category=text-to-video&lab=Google&limit=20"
```

| Παράμετρος ερωτήματος | Σημασία |
|---|---|
| `q` | Λέξεις που πρέπει να εμφανίζονται όλες στο όνομα, το id, τον κατασκευαστή ή τις ετικέτες, για παράδειγμα `kling 3`. |
| `category` | Ένα id κατηγορίας, για παράδειγμα `text-to-video` ή `upscale`. Το `GET https://api.doitong.com/v1/categories` παραθέτει και τις 21 με τις μετρήσεις τους. |
| `lab` | Ο κατασκευαστής του μοντέλου, με όνομα ή id, για παράδειγμα `Google` ή `black-forest-labs`. |
| `family` | Ένα id `family` από προηγούμενη γραμμή: κάθε παραλλαγή ενός μοντέλου (pro, fast, image-to-video, …). |
| `mode` | `exact` (η τιμή υπολογίζεται από την είσοδο), `measured` (από τη διάρκεια ή το μέγεθος των αρχείων εισόδου), `estimate` (εκτιμώμενη τιμή ανά εκτέλεση) ή `metered` (χρέωση βάσει της πραγματικής χρήσης, έως ένα μέγιστο ανά εκτέλεση). |
| `limit`, `cursor` | Μέγεθος σελίδας (1 έως 100, προεπιλογή 50) και το `next_cursor` της προηγούμενης σελίδας. |

Κάθε γραμμή έχει `id`, `name`, `lab`, `category`, `family`, `summary`, `tags`, `output_kind`, `docs_url` και ένα αντικείμενο `price` (δείτε το [Pricing](https://doitong.com/developers/docs/pricing#price-objects)). Το `GET https://api.doitong.com/v1/models/{model_id}` προσθέτει το πλήρες JSON Schema εισόδου και εξόδου, τα κανονικά ονόματα παραμέτρων, τους κανόνες τιμολόγησης και ένα δείγμα εισόδου. Άγνωστο `category` ή `mode` επιστρέφει `400 invalid_parameter`.

## Εκτέλεση μοντέλου

```bash
curl -X POST "https://api.doitong.com/v1/run/{model_id}?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1842-cover" \
  -d '{"prompt": "..."}'
```

- Το σώμα είναι η είσοδος του μοντέλου, ένα αντικείμενο JSON. Κάθε σελίδα μοντέλου παραθέτει τις παραμέτρους του.
- Η είσοδος ελέγχεται πριν από οποιαδήποτε χρέωση. Μη έγκυρη είσοδος επιστρέφει `422 invalid_input` με την προβληματική `param` και δεν κοστίζει τίποτα.
- Το `?wait=N` (έως 20 δευτερόλεπτα) διατηρεί την κλήση ενεργή μέχρι να ολοκληρωθεί το αίτημα ή να λήξει ο χρόνος.
- Το `?webhook_url=https://…` στέλνει υπογεγραμμένο `POST` σε αυτή τη διεύθυνση όταν ολοκληρωθεί το αίτημα (δείτε το [Webhooks](https://doitong.com/developers/docs/webhooks)).
- Το `?storage=permanent` ή `?storage=temporary` επιλέγει για πόσο διατηρούνται τα αρχεία εξόδου· χωρίς αυτό εφαρμόζεται η ρύθμιση του λογαριασμού (δείτε το [Πού βρίσκονται τα αρχεία](#storage)).

Η απόκριση είναι `202 Accepted` όσο το αίτημα βρίσκεται ακόμη σε εξέλιξη και `200 OK` όταν ολοκληρώθηκε εντός της αναμονής (ή όταν είναι επανάληψη, δείτε παρακάτω). Οι κεφαλίδες `Location` και `Doitong-Request-Id` περιέχουν τη διεύθυνση URL και το id του αιτήματος.

## Καταστάσεις

Κύκλος ζωής αιτήματος: `queued` → `running` → `succeeded` | `failed` | `canceled` (ολοκληρωμένο· οι αποτυχημένες και ακυρωμένες χρεώσεις επιστρέφονται).

| Κατάσταση | Σημασία | Τελική |
|---|---|---|
| `queued` | Έγινε αποδεκτό και χρεώθηκε, σε αναμονή εργαζομένου. Το `queue_position` μπορεί να εμφανίζει τη θέση στην ουρά. | όχι |
| `running` | Το μοντέλο δημιουργεί την έξοδο. | όχι |
| `succeeded` | Ολοκληρώθηκε. Το `outputs` παραθέτει τα αρχεία. | ναι |
| `failed` | Το μοντέλο ή ένα όριο το σταμάτησε. Το `error` εξηγεί γιατί. Οι πιστώσεις API επιστρέφονται. | ναι |
| `canceled` | Ακυρώθηκε πριν παραγάγει αποτέλεσμα. Οι πιστώσεις API επιστρέφονται. | ναι |

Ένα αίτημα που διαρκεί περισσότερο από το χρονικό του όριο αποτυγχάνει με τον κωδικό `timeout` και επιστρέφεται: 15 λεπτά για εικόνες, 60 λεπτά για βίντεο, 30 λεπτά για ήχο και οτιδήποτε άλλο.

## Το αντικείμενο αιτήματος

```json
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "flux/schnell",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:01Z",
  "completed_at": "2026-10-20T12:00:02Z",
  "queue_position": null,
  "cost": { "credits": 3, "usd": "0.003", "charged": 3, "refunded": 0 },
  "input": { "prompt": "..." },
  "output": { "images": [ { "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "width": 1024, "height": 768 } ] },
  "outputs": [
    { "type": "image", "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "content_type": "image/jpeg",
      "width": 1024, "height": 768, "file_size": 183920, "stored": true }
  ],
  "error": null,
  "metrics": { "inference_seconds": 1.2 },
  "storage": { "mode": "permanent", "bytes": 183920, "expires_at": null, "expired": false },
  "urls": {
    "self": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

- Το `outputs` είναι ίδιο για κάθε μοντέλο: μία καταχώριση ανά αρχείο που δημιουργήθηκε, με `type` (`image`, `video`, `audio`, `file` ή `3d`), ένα `url` στην αποθήκευσή μας, `content_type` και, όταν είναι γνωστά, `file_size`, `width`, `height`, `duration`.
- Το `output` είναι το αντικείμενο αποτελέσματος του ίδιου του μοντέλου (τα πεδία του παρατίθενται σε κάθε σελίδα μοντέλου), με τις ίδιες διευθύνσεις URL.
- Το `storage` δηλώνει πώς διατηρούνται τα αρχεία: `mode` (`permanent` ή `temporary`), αποθηκευμένα `bytes`, `expires_at` (πότε διαγράφεται ένα προσωρινό αρχείο, `null` για τα μόνιμα) και `expired` (`true` μόλις διαγραφούν τα αρχεία).
- Το `cost.credits` είναι η τιμή της κλήσης σε πιστώσεις API (`cost.usd` σε USD), το `cost.charged` ό,τι χρεώθηκε από το υπόλοιπο API και το `cost.refunded` ό,τι επιστράφηκε. Για μοντέλο `metered`, το `cost.credits` είναι το μέγιστο ποσό που δεσμεύτηκε στην αρχή (`cost.held`)· όταν η εκτέλεση ολοκληρωθεί με επιτυχία, το `cost.settled` δηλώνει το ποσό της χρήσης και το υπόλοιπο του μέγιστου βρίσκεται στο `cost.refunded` (δείτε το [Χρέωση βάσει χρήσης](https://doitong.com/developers/docs/pricing#metered)).
- Όταν ένα αίτημα αποτυγχάνει, το `error` είναι `{ "type": …, "code": …, "message": … }`.

## Ανάγνωση αιτήματος

```bash
curl "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

- Το `?wait=N` (έως 20 δευτερόλεπτα) κάνει αναμονή μεγάλης διάρκειας: η κλήση επιστρέφει μόλις το αίτημα γίνει τελικό ή μετά από N δευτερόλεπτα με την τρέχουσα κατάσταση. Η επανάληψη αυτής της διαδικασίας είναι ο απλούστερος τρόπος αναμονής αποτελέσματος.
- Το `?logs=1` προσθέτει τις γραμμές του αρχείου καταγραφής προόδου του μοντέλου (τις τελευταίες 50) ως `logs`.

Μπορείτε να διαβάσετε μόνο αιτήματα του δικού σας λογαριασμού· οποιοδήποτε άλλο id είναι `404 request_not_found`.

## Λίστα αιτημάτων

```bash
curl "https://api.doitong.com/v1/requests?limit=20&status=succeeded&model=flux/schnell" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

Πρώτα εμφανίζονται τα νεότερα. Το `limit` είναι από 1 έως 100 (προεπιλογή 20), ενώ τα `status` και `model` λειτουργούν ως φίλτρα. Η απόκριση είναι `{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }`· περάστε `cursor=<next_cursor>` για την επόμενη σελίδα.

## Ακύρωση αιτήματος

```bash
curl -X POST "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

- Ακυρώθηκε πριν ξεκινήσει το μοντέλο: η κατάσταση γίνεται `canceled`, οι πιστώσεις API επιστρέφονται και λαμβάνετε `200`.
- Η δημιουργία έχει ήδη ξεκινήσει: η ακύρωση προωθείται και λαμβάνετε `202` με `"cancel_requested": true`. Αν το μοντέλο ολοκληρωθεί ούτως ή άλλως, το αίτημα ολοκληρώνεται κανονικά και χρεώνεται.
- Είναι ήδη τελικό: `409 not_cancelable` (ένα αίτημα που είναι ήδη `canceled` απλώς επιστρέφει `200`).

## Διαγραφή των αρχείων αιτήματος

```bash
curl -X DELETE "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/files" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

Διαγράφει τώρα τα αντίγραφα των αρχείων εξόδου του αιτήματος και σταματά τη χρέωση αποθήκευσής τους. Η απόκριση είναι το αντικείμενο αιτήματος με `storage.expired: true`· οι διευθύνσεις URL παραμένουν στην εγγραφή αλλά δεν λειτουργούν πλέον. Η επανάληψη της κλήσης δεν αλλάζει τίποτα (`200`). Ένα αίτημα που είναι ακόμη `queued` ή `running` δεν έχει αρχεία: `409 request_active`. Απαιτεί `models:run`.

## Idempotency: επανάληψη χωρίς διπλή χρέωση

Τα δίκτυα αποτυγχάνουν. Για ασφαλή επανάληψη μιας εκτέλεσης, στείλτε μια κεφαλίδα `Idempotency-Key` (οποιαδήποτε συμβολοσειρά έως 255 χαρακτήρες, μοναδική ανά λειτουργία, για παράδειγμα το δικό σας id παραγγελίας):

- Ίδιο κλειδί και ίδιο σώμα όπως πριν: λαμβάνετε το αρχικό αίτημα (`200`, κεφαλίδα `Idempotent-Replayed: true`) και δεν γίνεται νέα χρέωση.
- Ίδιο κλειδί και σώμα μετά από εκτέλεση που απέτυχε πριν φτάσει στο μοντέλο (`upstream_error` ή `internal_error` κατά την υποβολή, `insufficient_credits`, `budget_exceeded`, `too_many_inflight`): δεν δημιουργήθηκε τίποτα και δεν έγινε χρέωση, επομένως η επανάληψη εκτελεί ξανά το μοντέλο αντί να επιστρέψει την αποτυχία.
- Ίδιο κλειδί με διαφορετικό σώμα: `409 idempotency_mismatch`.
- Τα κλειδιά περιορίζονται στο κλειδί API που τα έστειλε.

## Πού βρίσκονται τα αρχεία

Κάθε αρχείο εξόδου αντιγράφεται στην αποθήκευσή μας πριν το αίτημα χαρακτηριστεί `succeeded`, επομένως οι διευθύνσεις URL στο `outputs` βρίσκονται στους δικούς μας κεντρικούς υπολογιστές και μπορείτε να συνδέεστε απευθείας σε αυτές. Εσείς επιλέγετε για πόσο παραμένουν:

| Λειτουργία | Διάρκεια | Τιμή |
|---|---|---|
| `permanent` (προεπιλογή) | Μέχρι να τα διαγράψετε | 100 πιστώσεις API (0,10 $) ανά GB τον μήνα, με ημερήσια χρέωση από το υπόλοιπο API |
| `temporary` | 7 ημέρες και μετά διαγράφονται | Δωρεάν |

- Η ρύθμιση του λογαριασμού αποφασίζει για τα νέα αιτήματα: ο διακόπτης "Διατήρηση αρχείων για πάντα" στον [πίνακα ελέγχου](https://doitong.com/developers/dashboard#balance) ή το `PATCH https://api.doitong.com/v1/account/storage` με `{"mode": "temporary"}`. Το `GET https://api.doitong.com/v1/account` την εμφανίζει στην ενότητα `storage`, μαζί με τα byte που διατηρείτε και τη μηνιαία εκτίμηση.
- Το `?storage=permanent|temporary` σε μια εκτέλεση (το όρισμα `storage` του εργαλείου MCP `run`) την παρακάμπτει για τη συγκεκριμένη εκτέλεση.
- Η αλλαγή της ρύθμισης δεν επηρεάζει ποτέ αρχεία που έχετε ήδη· διαγράψτε τα με [`DELETE /requests/{id}/files`](#delete-files).
- Όταν το υπόλοιπο API δεν μπορεί να πληρώσει την αποθήκευση, δεν χρεώνεστε και λαμβάνετε email: φορτίστε το υπόλοιπο εντός 30 ημερών ή τα διατηρούμενα αρχεία θα γίνουν προσωρινά και θα διαγραφούν 7 ημέρες αργότερα.

Στη σπάνια περίπτωση που αποτύχει η αντιγραφή μας, η καταχώριση έχει `"stored": false` και η διεύθυνση URL είναι η αρχική, βραχύβια διεύθυνση: κατεβάστε το αρχείο σύντομα.