Αιτήματα

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

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

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

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

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

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

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).
• Το ?storage=permanent ή ?storage=temporary επιλέγει για πόσο διατηρούνται τα αρχεία εξόδου· χωρίς αυτό εφαρμόζεται η ρύθμιση του λογαριασμού (δείτε το Πού βρίσκονται τα αρχεία).

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

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

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

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

{
  "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 (δείτε το Χρέωση βάσει χρήσης).
• Όταν ένα αίτημα αποτυγχάνει, το error είναι { "type": …, "code": …, "message": … }.

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

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.

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

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> για την επόμενη σελίδα.

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

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).

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

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 βρίσκονται στους δικούς μας κεντρικούς υπολογιστές και μπορείτε να συνδέεστε απευθείας σε αυτές. Εσείς επιλέγετε για πόσο παραμένουν:

• Η ρύθμιση του λογαριασμού αποφασίζει για τα νέα αιτήματα: ο διακόπτης "Διατήρηση αρχείων για πάντα" στον πίνακα ελέγχου ή το 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.
• Όταν το υπόλοιπο API δεν μπορεί να πληρώσει την αποθήκευση, δεν χρεώνεστε και λαμβάνετε email: φορτίστε το υπόλοιπο εντός 30 ημερών ή τα διατηρούμενα αρχεία θα γίνουν προσωρινά και θα διαγραφούν 7 ημέρες αργότερα.

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