Επισκόπηση

Endpoints

Κάθε endpoint βρίσκεται κάτω από ένα base URL και εξυπηρετείται μέσω HTTPS.

https://api.shannon-ai.com

Τα τρία endpoints που παράγουν κείμενο φτάνουν στα ίδια μοντέλα. Διαλέξτε αυτό του οποίου τη μορφή χρησιμοποιεί ήδη ο κώδικάς σας.

Βασικά του αιτήματος

• Το σώμα κάθε POST είναι ένα αντικείμενο JSON, έως 32 MiB.
• Ένα πεδίο που το API δεν γνωρίζει δεν προκαλεί σφάλμα και δεν έχει αποτέλεσμα. Ένα αίτημα γραμμένο για άλλον πάροχο δεν αποτυγχάνει εξαιτίας ενός επιπλέον πεδίου.
• Ένα γνωστό πεδίο με λάθος τύπο JSON, ή ένα υποχρεωτικό πεδίο που λείπει, απαντάται με 422. Ένα σώμα που δεν είναι έγκυρο JSON απαντάται με 400.
• Το model είναι ένα από τα ids στη σελίδα Μοντέλα & τιμές. Τα πεζά και τα κεφαλαία δεν παίζουν ρόλο.

Μια απάντηση είναι JSON, ή stream από server-sent events όταν το αίτημα ορίζει το stream σε true. Κάθε endpoint απαντά στη δική του μορφή. Κάθε απάντηση έχει την κεφαλίδα x-request-id.

Από τι περνά ένα αίτημα

Ένα αίτημα ελέγχεται με σταθερή σειρά πριν τρέξει μοντέλο. Απαντά ο πρώτος έλεγχος που αποτυγχάνει, οπότε ένα 401 δεν σας λέει ακόμη τίποτα για το σώμα.

Μορφή σφάλματος

Ένα σφάλμα είναι αντικείμενο JSON με ένα error που περιέχει type και message. Το /v1/messages το τυλίγει όπως το περιμένουν τα SDK της Anthropic· κάθε άλλη διαδρομή χρησιμοποιεί τη μορφή OpenAI.

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

• Διαβάστε το type και το message. Τα code και param υπάρχουν μόνο σε ορισμένα σφάλματα: αντιμετωπίστε τα ως προαιρετικά. Το param είναι πάντα null.
• Αφού ξεκινήσει ένα stream, η κατάσταση είναι ήδη 200. Μια αποτυχία φτάνει τότε ως frame σφάλματος μέσα στο stream.
• Κάθε απάντηση σφάλματος φέρει την κεφαλίδα x-request-id.

Χειρισμός σφαλμάτων

Χρέωση και υπόλοιπο

• Υπάρχει ένα υπόλοιπο ανά λογαριασμό, και το chat και το API το μοιράζονται: πρώτα το σημερινό ημερήσιο όριο του πλάνου, μετά το αγορασμένο credit. Το API δεν έχει δική του ποσόστωση.
• Ένα αίτημα δεσμεύει τον προϋπολογισμό εξόδου του (max_tokens, προεπιλογή 4,096) και στη συνέχεια χρεώνεται για τα tokens που χρησιμοποίησε πραγματικά, με την τιμή του μοντέλου.
• Κάθε απάντηση αναφέρει τους αριθμούς tokens στο usage. Η σελίδα Κλειδιά & χρήση δείχνει το υπόλοιπο και το κόστος κάθε αιτήματος.
• Κάθε αίτημα εξυπηρετείται ισότιμα. Το μόνο όριο στον ρυθμό αιτημάτων είναι η προστασία από υπερφόρτωση: 120 αιτήματα ανά λεπτό ανά λογαριασμό. Τα αιτήματα που στέλνονται παράλληλα περιμένουν σε ουρά.

Όρια και υπόλοιπο Μοντέλα & τιμές Κλειδιά & χρήση

Πεδία που εξαρτώνται από το μοντέλο

Κάθε μοντέλο δέχεται το ίδιο αίτημα. Μερικά πεδία ισχύουν μόνο σε ορισμένα μοντέλα· ο πίνακας ονομάζει πού. Οι σελίδες των endpoints απαριθμούν κάθε πεδίο.

Chat Completions

Αν έρχεστε από SDK της OpenAI

• Ορίστε το base URL σε https://api.shannon-ai.com/v1 και το κλειδί στο κλειδί Shannon σας. Οι κλήσεις Chat Completions και Responses δουλεύουν τότε με το SDK ως έχει.
• Το model πρέπει να είναι id Shannon. Ένα όνομα μοντέλου άλλου παρόχου, όπως το gpt-4o, απαντάται με 400 και unknown model.
• Ο συλλογισμός έρχεται σε δικό του πεδίο: reasoning_content δίπλα στο content, στο μήνυμα και στα deltas του stream.
• Ένα stream φέρει πάντα το usage στο τελευταίο του chunk, μαζί με το finish_reason.
• Μια κλήση εργαλείου σε stream φτάνει ως ένα chunk με ολόκληρο το string arguments.
• Μια απάντηση έχει μία επιλογή.
• Οι διαδρομές του API της OpenAI που δεν υπάρχουν στον παραπάνω πίνακα, όπως το /v1/embeddings, απαντώνται με 404.

Αν έρχεστε από SDK της Anthropic

• Ορίστε το base URL σε https://api.shannon-ai.com, χωρίς /v1, και το κλειδί στο κλειδί Shannon σας. Το SDK το στέλνει ως x-api-key.
• Το model πρέπει να είναι id Shannon.
• Το max_tokens είναι προαιρετικό σε αυτό το API. Η προεπιλογή του είναι 4,096.
• Μια απάντηση περιέχει blocks περιεχομένου τύπου thinking, text και tool_use. Το πρώτο block δεν είναι πάντα το κείμενο: επιλέγετε blocks με βάση το type.
• Το stop_reason είναι end_turn ή tool_use. Ένα stream ενός μοντέλου Shannon μπορεί να τελειώσει και με max_tokens.
• Τα anthropic-version και anthropic-beta γίνονται δεκτά, ώστε το SDK να δουλεύει αμετάβλητο. Ένα αίτημα δεν τα χρειάζεται.
• Τα σφάλματα στο /v1/messages έχουν τη μορφή της Anthropic: {"type": "error", "error": {…}}.

Τα εργαλεία προγραμματισμού που μιλούν αυτές τις μορφές ρυθμίζονται με τον ίδιο τρόπο: base URL, κλειδί και ένα id Shannon ως μοντέλο. Εργαλεία CLI για προγραμματισμό