API
API: συνδέστε τα προγράμματά σας με το AI-CLOUD
Αν έχετε ήδη εφαρμογή σε εμάς, από εδώ τη συνδέετε με τα υπόλοιπα προγράμματά σας, όπως της αποθήκης ή του λογιστηρίου, και με τον ιστότοπό σας. Από το ίδιο σημείο έχετε και πρόσβαση στα μοντέλα AI, που χρεώνονται στις πιστώσεις σας. Τη σελίδα μπορείτε να τη στείλετε απευθείας σε όποιον συντηρεί το άλλο πρόγραμμα.
Τελευταία αναθεώρηση: 2 Σεπτεμβρίου 2026
Τι μπορεί να κάνει
Υπάρχουν δύο είσοδοι και δουλεύουν με το ίδιο κλειδί. Όταν εκδίδετε το κλειδί, διαλέγετε αν θα ανοίγει τη μία από τις δύο ή και τις δύο.
- Μοντέλα AI. Το πρόγραμμά σας στέλνει ερώτηση και παίρνει απάντηση από γλωσσικό μοντέλο. Το κόστος αφαιρείται από τις πιστώσεις σας σε εμάς, οπότε δεν χρειάζεστε ούτε σύμβαση ούτε κλειδί από τον πάροχο του μοντέλου.
- Γέφυρα προς την εφαρμογή σας. Ένα άλλο σύστημα καλεί την εφαρμογή που φτιάξατε σε εμάς μέσα από δική μας διεύθυνση. Οι κλήσεις έχουν όριο και καταγράφονται, και η καθεμία φέρει υπογραφή, ώστε να ξέρετε ότι ήρθε πράγματι από εμάς.
Πρώτα βήματα
Θέλει δύο λεπτά. Κλειδί μπορεί να εκδώσει ο ιδιοκτήτης ή ο διαχειριστής του λογαριασμού. Το μέλος και ο παρατηρητής δεν έχουν αυτό το δικαίωμα, επειδή το κλειδί ξοδεύει τις πιστώσεις όλου του λογαριασμού και δουλεύει χωρίς σύνδεση.
- Συνδεθείτε στην πύλη και ανοίξτε το API από το μενού.
- Πατήστε «Έκδοση κλειδιού», δώστε του ένα όνομα και διαλέξτε το έργο και τη χρήση του.
- Το κλειδί εμφανίζεται μία φορά. Σημειώστε το αμέσως, γιατί εμείς δεν το κρατάμε και δεν μπορούμε να σας το ξαναδείξουμε. Αν το ξεχάσετε, το ανακαλείτε και εκδίδετε νέο.
- Δοκιμάστε το με την πρώτη εντολή παρακάτω.
Η διεύθυνση και το κλειδί
Όλα περνούν από μία διεύθυνση. Το κλειδί μπαίνει στην κεφαλίδα
Authorization, όπως και στα περισσότερα API που έχετε ήδη
δουλέψει.
curl https://ai-cloud.gr/api/v1/me \
-H "Authorization: Bearer ΤΟ_ΚΛΕΙΔΙ_ΣΑΣ"
{
"key": {
"name": "Το πρόγραμμα της αποθήκης",
"masked": "ak_live_…f3c9",
"scopes": ["ai"],
"project": "43baa9f08a20"
},
"balanceCredits": 4820,
"limits": { "perMinute": 60, "perDay": 5000 }
}
Ποια μοντέλα προσφέρονται
Το πρόγραμμα ζητά τη λίστα από εμάς κάθε φορά, ώστε να μη μένει μια παλιά λίστα γραμμένη στον κώδικά του. Οι τιμές στην απάντηση είναι οι δικές σας, δηλαδή αυτό που θα χρεωθείτε πραγματικά.
- Οι τιμές είναι σε μικροπιστώσεις ανά 1000 token. 1000 μικροπιστώσεις = 1 πίστωση.
- Ένα token αντιστοιχεί περίπου σε τρεις με τέσσερις ελληνικούς χαρακτήρες. Μια ερώτηση μεσαίου μήκους, μαζί με την απάντησή της, βγάζει μερικές εκατοντάδες token.
- Διαθέσιμα είναι τα μοντέλα της Anthropic, επειδή η είσοδος αυτή δέχεται τη δική τους μορφή αιτήματος. Αν χρειάζεστε άλλον πάροχο, γράψτε μας.
curl https://ai-cloud.gr/api/v1/models \
-H "Authorization: Bearer ΤΟ_ΚΛΕΙΔΙ_ΣΑΣ"
{
"models": [
{
"model": "claude-haiku-4-5",
"contextWindow": 200000,
"inputPricePer1kMicro": 180,
"outputPricePer1kMicro": 900
}
]
}
Μία κλήση προς το AI
Το σώμα του αιτήματος είναι ίδιο με αυτό που δέχεται η Anthropic. Αν το πρόγραμμά σας μιλά ήδη με το API τους, αλλάζετε μόνο τη διεύθυνση και το κλειδί. Η απάντηση σας επιστρέφεται ακριβώς όπως ήρθε, χωρίς περικοπές.
- Το
max_tokensορίζει πόσο μεγάλη μπορεί να είναι η απάντηση. Το ανώτατο που δεχόμαστε είναι 4096, ώστε να ξέρετε από πριν πόσο μπορεί να κοστίσει η ακριβότερη κλήση. - Η ροή (
"stream": true) δεν υποστηρίζεται. Ένα τέτοιο αίτημα απορρίπτεται με μήνυμα που εξηγεί τον λόγο, και δεν το αλλάζουμε στα κρυφά. - Κάθε κλήση έχει περιθώριο 25 δευτερολέπτων. Αν το μοντέλο δεν απαντήσει μέσα σε αυτά, επιστρέφεται σφάλμα, για να μην περιμένει το πρόγραμμά σας επ’ αόριστον.
curl https://ai-cloud.gr/api/v1/ai/messages \
-H "Authorization: Bearer ΤΟ_ΚΛΕΙΔΙ_ΣΑΣ" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-haiku-4-5",
"max_tokens": 300,
"messages": [
{ "role": "user", "content": "Σύνοψε αυτό το παράπονο σε μία πρόταση: ..." }
]
}'
X-AICLOUD-Cost-Micro: 9
X-AICLOUD-Charged: 1
Πόσο κοστίζει
Πληρώνετε το κόστος της κλήσης με προσαύξηση 20%. Η χρέωση υπολογίζεται αφού
έρθει η απάντηση, με τον πραγματικό αριθμό token, και τίποτα δεν δεσμεύεται από
πριν. Πριν στείλουμε το αίτημα, ωστόσο, ελέγχουμε αν το υπόλοιπό σας φτάνει για την
ακριβότερη δυνατή έκβαση (το κείμενό σας μαζί με όλα τα max_tokens).
Αν δεν φτάνει, το αίτημα απορρίπτεται αμέσως, ώστε να μη μείνετε με χρέος.
- Ό,τι χρεώθηκε φαίνεται αμέσως στις κεφαλίδες της απάντησης και στην οθόνη «API» στην πύλη. Στα ονόματα των κεφαλίδων δεν μετράει αν είναι πεζά ή κεφαλαία, και τα περισσότερα προγράμματα τα δίνουν με πεζά.
- Όταν οι πιστώσεις δεν φτάνουν για την ακριβότερη έκβαση του αιτήματος, αυτό απορρίπτεται πριν εκτελεστεί, οπότε δεν ξοδεύεται τίποτα και δεν δημιουργείται χρέος. Στην απάντηση γράφει πόσες πιστώσεις χρειάζονται και πόσες έχετε.
- Με την προσωρινή αποθήκευση της προτροπής, χρεώνονται κι εκείνα τα token. Η εγγραφή στη μνήμη κοστίζει 1,25 της τιμής εισόδου και η ανάγνωση από αυτήν 0,1. Γλιτώνετε πράγματι χρήματα, απλώς η χρέωση δεν μηδενίζεται.
- Κάθε κλειδί μπορεί να έχει μηνιαίο ανώτατο όριο σε πιστώσεις. Μόλις το φτάσει, σταματά μόνο εκείνο και τα υπόλοιπα κλειδιά συνεχίζουν κανονικά.
- Η γέφυρα προς την εφαρμογή σας δεν κοστίζει πιστώσεις. Γι’ αυτήν πληρώνετε ήδη τη φιλοξενία του έργου.
token εισόδου 16 × 150 μικροπιστώσεις / 1000 = 2,40
token εξόδου 6 × 750 μικροπιστώσεις / 1000 = 4,50
────
κόστος 6,90 → 7 μικροπιστώσεις
με προσαύξηση 20% 9 μικροπιστώσεις
(= 0,009 πιστώσεις)
Η γέφυρα προς την εφαρμογή σας
Ένα άλλο σύστημα καλεί την εφαρμογή σας μέσα από τη δική μας διεύθυνση. Επειδή ανάμεσα στα δύο βρισκόμαστε εμείς, έχετε κλειδί που ανακαλείται με ένα κουμπί, όριο στις κλήσεις και καταγραφή του ποιος κάλεσε και πότε.
- Η διεύθυνση δηλώνεται στην πύλη, στην οθόνη API, ξεχωριστά για κάθε έργο.
- Γίνεται δεκτή μόνο διεύθυνση με
https://και όνομα τομέα. Αριθμητική διεύθυνση IP δεν δηλώνεται. - Ό,τι γράφεται μετά τον αριθμό του έργου προστίθεται αυτούσιο στη διεύθυνσή σας, μαζί με τις παραμέτρους μετά το «?».
curl https://ai-cloud.gr/api/v1/p/43baa9f08a20/παραγγελίες \
-H "Authorization: Bearer ΚΛΕΙΔΙ_ΜΕ_ΕΜΒΕΛΕΙΑ_ΓΕΦΥΡΑΣ"
↓ φτάνει στη διεύθυνσή σας
https://η-εφαρμογή-σας.gr/παραγγελίες
Γιατί ζητάμε να αποδείξετε ότι η διεύθυνση είναι δική σας
Μια διεύθυνση που δηλώσατε δεν ενεργοποιείται αμέσως. Πρώτα αποδεικνύετε ότι ο τομέας σας ανήκει. Χωρίς αυτό, οποιοσδήποτε θα μπορούσε να δηλώσει τον ιστότοπο κάποιου άλλου και να τον γεμίζει αιτήματα στο όνομά μας και από τη διεύθυνσή μας. Η απόδειξη γίνεται μία φορά και θέλει περίπου ένα λεπτό.
- Στην πύλη βλέπετε μια συμβολοσειρά της μορφής
aicloud-verify-…. - Κάντε ώστε το
https://η-διεύθυνσή-σας/.well-known/aicloud-gateway.txtνα επιστρέφει αυτή τη συμβολοσειρά ως απλό κείμενο. - Πατήστε «Επιβεβαίωση ιδιοκτησίας» και τελειώσατε.
- Αν αλλάξετε τη διεύθυνση, η επιβεβαίωση ακυρώνεται και την κάνετε από την αρχή. Η απόδειξη για έναν τομέα δεν ισχύει για κανέναν άλλο.
Κάνε τη διεύθυνση /.well-known/aicloud-gateway.txt να επιστρέφει
αυτό το κείμενο ως plain text: aicloud-verify-xxxxxxxx
Πώς η εφαρμογή σας αναγνωρίζει ότι είμαστε εμείς
Κάθε κλήση που περνά από τη γέφυρα είναι υπογεγραμμένη. Η εφαρμογή σας βγάζει την ίδια υπογραφή με το κοινό μυστικό που βλέπετε στην πύλη και συγκρίνει τις δύο. Έτσι, ακόμη κι αν κάποιος μαντέψει τη διεύθυνσή σας, δεν μπορεί να παρουσιαστεί ως εμείς.
- Μαζί με το αποτύπωμα του σώματος υπογράφονται ο χρόνος, η μέθοδος και η διαδρομή. Γι’ αυτό μια υπογραφή δεν μπορεί να χρησιμοποιηθεί ξανά για άλλη διαδρομή.
- Η διαδρομή είναι ακριβώς αυτή που λαμβάνει ο διακομιστής σας, με τις παραμέτρους μετά το «?» και με την κωδικοποίηση που είχε όταν έφτασε. Στο Node αυτό είναι το
req.urlόπως είναι: μην το αποκωδικοποιήσετε και μην κόψετε τις παραμέτρους πριν υπολογίσετε την υπογραφή. - Αν η διεύθυνσή σας έχει πρόθεμα (
https://ο-ιστότοπός-σας.gr/api), το πρόθεμα ανήκει κι αυτό στην υπογεγραμμένη διαδρομή, όπως ακριβώς εμφανίζεται και στο αίτημα που σας φτάνει. - Το μυστικό το βλέπετε στην πύλη όποτε θέλετε και το αλλάζετε με ένα κουμπί, οπότε το παλιό παύει αμέσως να ισχύει.
X-AICLOUD-Signature: t=1788332240,v1=5c4afbda789bcceb…
X-AICLOUD-Timestamp: 1788332240
X-AICLOUD-Project: 43baa9f08a20
X-AICLOUD-Caller-Ip: 78.47.88.53
User-Agent: AICLOUD-Gateway/1
import { createHmac, createHash, timingSafeEqual } from 'node:crypto';
function verify(req, body, secret) {
const [t, v1] = req.headers['x-aicloud-signature']
.split(',').map(part => part.split('=')[1]);
// Παλιά υπογραφή δεν γίνεται δεκτή: γι' αυτό ακριβώς υπάρχει ο υπογεγραμμένος χρόνος.
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const hash = createHash('sha256').update(body).digest('hex');
const payload = `${t}.${req.method}\n${req.url}\n${hash}`;
const ours = createHmac('sha256', secret).update(payload).digest('hex');
return ours.length === v1.length
&& timingSafeEqual(Buffer.from(ours), Buffer.from(v1));
}
Τι ΔΕΝ φτάνει στην εφαρμογή σας
Πριν παραδώσουμε το αίτημα, αφαιρούμε ορισμένα στοιχεία, και το κάνουμε για τη δική σας προστασία. Μια εφαρμογή που δέχεται cookies και κλειδιά άλλων καταλήγει να τα γράφει στο δικό της ημερολόγιο.
- Το κλειδί. Η κεφαλίδα
Authorizationμένει σε εμάς. Η εφαρμογή σας δεν βλέπει ποτέ το κλειδί με το οποίο κλήθηκε. - Τα cookies. Δεν περνούν προς καμία κατεύθυνση, ούτε το
Set-Cookieπου στέλνει η εφαρμογή σας πίσω σε αυτόν που την καλεί. - Οι κεφαλίδες της δικής μας εισόδου (
Host,X-Forwarded-*). Αφορούν τη δική μας υποδομή και θα σας μπέρδευαν για την προέλευση της κλήσης. - Οι μόνες κεφαλίδες που προωθούνται είναι οι
Content-Type,Accept,Accept-Language,Idempotency-Key,X-Request-Id.
Όρια
Τα όρια ισχύουν για όλους, και για εμάς. Αν στην καθημερινή σας δουλειά δεν σας φτάνουν, γράψτε μας και θα τα αυξήσουμε, γιατί τρόπος να παρακαμφθούν δεν υπάρχει.
| Τι | Πόσο | Γιατί |
|---|---|---|
| Αιτήματα ανά κλειδί | 60 το λεπτό, 5000 το εικοσιτετράωρο | Αν διαρρεύσει ένα κλειδί, το όριο κρατά τη ζημιά μικρή. |
| Αιτήματα ανά λογαριασμό | 120 το λεπτό | Για να μην παρακάμπτεται το παραπάνω με δέκα κλειδιά. |
| Μέγεθος αιτήματος | 256 KB | Τα μεγάλα αρχεία δεν περνούν από εδώ, και σας το λέμε καθαρά με σφάλμα. |
| Μέγεθος απάντησης | 1 MB | Το ίδιο, προς την αντίθετη κατεύθυνση. |
| Χρόνος μίας κλήσης | 25 δευτ. για το AI, 20 δευτ. για τη γέφυρα | Μετά από αυτό το διάστημα επιστρέφεται σφάλμα. |
| Ενεργά κλειδιά ανά λογαριασμό | 20 | Με περισσότερα κλειδιά, ένας λογαριασμός χάνει τον έλεγχο για το ποιο χρησιμοποιείται πού. |
Όταν κάτι δεν δουλεύει
Κάθε σφάλμα έχει έναν σύντομο κωδικό για το πρόγραμμα και μια πρόταση για τον
άνθρωπο. Ο κωδικός βρίσκεται στο πεδίο code. Το πρόγραμμά σας ας
ελέγχει αυτόν, γιατί η διατύπωση του κειμένου μπορεί να αλλάξει.
- Από εμάς δεν θα πάρετε ποτέ 403 ή 404. Το δίκτυο μπροστά από τον ιστότοπο μετατρέπει αυτούς τους κωδικούς σε ιστοσελίδα, γι’ αυτό κάθε άρνηση επιστρέφεται ως 401 ή 400, με τον ακριβή λόγο στο
code.
| Κατάσταση | Κωδικός | Τι σημαίνει |
|---|---|---|
| 401 | bad_key |
Το κλειδί είναι λάθος, ανακλήθηκε, έληξε ή δεν έχει δικαίωμα γι’ αυτό. Εκδώστε νέο από την πύλη. |
| 401 | wrong_project |
Το κλειδί είναι άλλου έργου. Κάθε κλειδί ισχύει για ένα. |
| 401 | ip_not_allowed |
Το κλειδί είναι κλειδωμένο σε άλλες διευθύνσεις. Η λίστα αλλάζει στην πύλη. |
| 401 | account_blocked |
Η πρόσβαση στον λογαριασμό είναι σε αναστολή. Επικοινωνήστε μαζί μας. |
| 400 | bad_json |
Το σώμα δεν είναι έγκυρο JSON. |
| 400 | unknown_model |
Δεν υπάρχει τέτοιο μοντέλο. Τα ονόματα είναι στο /v1/models. |
| 400 | model_not_allowed |
Αυτό το μοντέλο δεν προσφέρεται. Η λίστα είναι στο /v1/models. |
| 400 | stream_unsupported |
Στείλατε "stream": true. Αφαιρέστε το, γιατί η ροή δεν υποστηρίζεται. |
| 400 | not_found |
Δεν υπάρχει τέτοια διεύθυνση. Ελέγξτε τη διαδρομή. |
| 400 | target_unverified |
Η διεύθυνση της εφαρμογής δεν έχει επιβεβαιωθεί ακόμη στην πύλη. |
| 402 | no_wallet |
Ο λογαριασμός δεν έχει πορτοφόλι με πιστώσεις. |
| 402 | insufficient_credits |
Οι πιστώσεις δεν φτάνουν γι’ αυτό το αίτημα. Φορτίστε από την πύλη. Δεν ξοδεύτηκε τίποτα. |
| 402 | unpaid_calls |
Υπάρχουν αχρέωτες πιστώσεις από προηγούμενες κλήσεις. Φορτίστε και τακτοποιούνται μόνες τους. |
| 402 | balance_unavailable |
Το υπόλοιπο δεν μπορεί να ελεγχθεί αυτή τη στιγμή. Δοκιμάστε ξανά σε λίγο. |
| 402 | key_limit_reached |
Συμπληρώθηκε το μηνιαίο ανώτατο όριο αυτού του κλειδιού. |
| 409 | — | Η εφαρμογή σας απάντησε 403 ή 404. Ο πραγματικός αριθμός είναι στο X-AICLOUD-Upstream-Status. |
| 413 | too_large |
Το αίτημα ξεπερνά τα 256 KB. |
| 429 | rate_limited |
Υπερβολικά πολλά αιτήματα. Περιμένετε τα δευτερόλεπτα από το Retry-After. |
| 502 | model_error |
Το μοντέλο αρνήθηκε το αίτημα. Ο δικός του λόγος είναι στο detail. Δεν χρεώνεται. |
| 502 | target_unreachable |
Η γέφυρα δεν έφτασε στην εφαρμογή σας. Συνήθως η διεύθυνση είναι λάθος ή δεν είναι προσβάσιμη. |
| 502 | response_too_large |
Η εφαρμογή σας επέστρεψε πάνω από 1 MB. |
| 503 | gateway_off |
Η είσοδος είναι προσωρινά κλειστή από εμάς. Δοκιμάστε ξανά σε λίγο. |
| 500 | internal |
Δικό μας σφάλμα. Αν επαναλαμβάνεται, πείτε μας. |
Ασφάλεια: τι κάνουμε εμείς και τι ζητάμε από εσάς
Το κλειδί είναι μια συμβολοσειρά γραμμένη μέσα σε ένα άλλο πρόγραμμα, συχνά για χρόνια. Γι' αυτό το προστατεύουμε με όσα μέτρα μπορούμε, και υπάρχουν δύο πράγματα που μένουν σε εσάς.
- Σε εμάς: το κλειδί φυλάσσεται μόνο ως μη αντιστρέψιμο αποτύπωμα. Ακόμη κι αν διαρρεύσει η βάση, κανείς δεν παίρνει από εκεί κλειδί που δουλεύει.
- Σε εμάς: το ημερολόγιο γράφει τι ζητήθηκε, πώς έληξε και πόσο κόστισε. Το περιεχόμενο του αιτήματός σας δεν το κρατά ποτέ, ούτε το κλειδί.
- Σε εμάς: ένα αίτημα από τη γέφυρα δεν κατευθύνεται ποτέ σε εσωτερικό δίκτυο, ακόμη κι αν ο τομέας στραφεί εκεί μετά την επιβεβαίωση. Ο έλεγχος γίνεται ξανά σε κάθε κλήση.
- Από εσάς: φυλάξτε το κλειδί όπως έναν κωδικό πρόσβασης, σε μεταβλητή περιβάλλοντος. Μην το γράφετε μέσα στον κώδικα και μην το ανεβάζετε στο αποθετήριο.
- Από εσάς: αν έχετε σταθερή διεύθυνση, γράψτε την στη λίστα με τις επιτρεπόμενες διευθύνσεις του κλειδιού. Τότε ένα κλεμμένο κλειδί δεν δουλεύει από αλλού.
- Περισσότερα για τα μέτρα: Ασφάλεια των δεδομένων.
Συχνές ερωτήσεις
Χρειαζόμαστε προγραμματιστή;
Για την είσοδο του AI όχι απαραίτητα. Όποιος συντηρεί το άλλο σας πρόγραμμα συνήθως μπορεί να το βάλει να στείλει ένα αίτημα. Για τη γέφυρα χρειάζεται κάποιος να ανεβάσει το αρχείο επιβεβαίωσης και να προσθέσει τον έλεγχο της υπογραφής. Αν η εφαρμογή σας είναι φτιαγμένη σε εμάς, αρκεί να το ζητήσετε από τον πράκτορα του στούντιο.
Μπορώ να δω ξανά το κλειδί μου;
Όχι, και το έχουμε κάνει έτσι επίτηδες. Κρατάμε μόνο το μη αντιστρέψιμο αποτύπωμά του, οπότε κανείς δεν μπορεί να το ανακτήσει, ούτε εμείς. Αν το ξεχάσετε, το ανακαλείτε με ένα κουμπί και εκδίδετε καινούργιο.
Τι γίνεται αν το κλειδί διαρρεύσει;
Το ανακαλείτε από την πύλη και δεν δουλεύει ήδη από την επόμενη κλήση. Καλό είναι κάθε πρόγραμμα να έχει το δικό του κλειδί, ώστε με την ανάκληση να σταματά μόνο αυτό και τα άλλα να συνεχίζουν.
Πληρώνω για τις αποτυχημένες κλήσεις;
Όχι. Χρεώνεται μόνο ό,τι επεξεργάστηκε πραγματικά το μοντέλο. Ένα αίτημα που απορρίφθηκε, επειδή π.χ. τελείωσαν οι πιστώσεις ή ξεπεράστηκε κάποιο όριο, δεν σας κοστίζει τίποτα.
Μπορεί το API να διαβάζει και να αλλάζει τα δεδομένα στο έργο μου;
Μόνο μέσα από τη δική σας εφαρμογή και μόνο όσα επιτρέπει εκείνη. Πρόσβαση απευθείας στη βάση σας δεν δίνουμε. Η γέφυρα παραδίδει το αίτημα στον κώδικά σας και αυτός αποφασίζει τι θα γίνει.
Εκδώστε το πρώτο σας κλειδί
Το κλειδί το εκδίδετε στην πύλη, από την οθόνη «API». Σας παίρνει δύο λεπτά, και ως την πρώτη κλήση δεν χρεώνεστε τίποτα.