आढावा

API चा नकाशा: प्रत्येक एंडपॉइंट, रिक्वेस्ट आणि त्रुटी कशा दिसतात, कॉल्सचे पैसे कसे दिले जातात, आणि OpenAI किंवा Anthropic SDK मधून आल्यावर काय माहीत असावे.

एंडपॉइंट्स

प्रत्येक एंडपॉइंट एकाच बेस URL खाली आहे आणि HTTPS वर दिला जातो.

बेस URL

https://api.shannon-ai.com

एंडपॉइंट	फॉरमॅट	कशासाठी
`POST /v1/chat/completions`	OpenAI Chat Completions	संभाषण पाठवा, पुढचे उत्तर मिळवा. स्ट्रीमिंगसह किंवा शिवाय.
`POST /v1/messages`	Anthropic Messages	तेच, Anthropic SDK च्या रिक्वेस्ट आणि उत्तर स्वरूपांमध्ये.
`POST /v1/responses`	OpenAI Responses	तेच, Responses स्वरूपांमध्ये. एंडपॉइंट कोणतीही स्थिती ठेवत नाही: प्रत्येक रिक्वेस्टसोबत संभाषण पाठवा.
`GET /v1/models`	OpenAI मॉडेल यादी	कॉन्टेक्स्ट विंडो, किमती आणि क्षमतांसह मॉडेल्सची यादी करा. की लागत नाही.
`POST /v1/tokenize`	Shannon API	होस्ट केलेल्या open-weight मॉडेलसाठी मजकुराची किंवा चॅट रिक्वेस्टची टोकन्स मोजा. मोफत.
`POST /v1/messages/count_tokens`	Anthropic टोकन मोजणी	होस्ट केलेल्या open-weight मॉडेलसाठी Messages रिक्वेस्टची इनपुट टोकन्स मोजा. मोफत.

मजकूर तयार करणारे तिन्ही एंडपॉइंट्स त्याच मॉडेल्सपर्यंत पोहोचतात. तुमचा कोड आधीच ज्याचा फॉरमॅट वापरतो तो निवडा.

रिक्वेस्टची मूलतत्त्वे

हेडर	वर्णन
`Authorization: Bearer <key>`	तुमची API की. `GET /v1/models` खेरीज प्रत्येक एंडपॉइंटवर आवश्यक, तुम्ही `x-api-key` पाठवत नसल्यास.
`x-api-key: <key>`	Anthropic SDK पाठवतात त्या हेडरमध्ये तीच की. प्रत्येक एंडपॉइंटवर वाचली जाते.
`Content-Type: application/json`	प्रत्येक `POST` वर आवश्यक. त्याशिवाय उत्तर `415` असते.
`x-request-id: <your id>`	ऐच्छिक. रिक्वेस्टसाठी तुमचा स्वतःचा id; तो उत्तरातील `x-request-id` हेडरमध्ये परत येतो. तो नसल्यास API 12 हेक्साडेसिमल अक्षरांचा एक तयार करते.

प्रत्येक POST ची बॉडी एक JSON ऑब्जेक्ट असते, 32 MiB पर्यंत.
API ला माहीत नसलेल्या फील्डमुळे त्रुटी येत नाही आणि त्याचा काही परिणाम होत नाही. दुसऱ्या प्रोव्हायडरसाठी लिहिलेली रिक्वेस्ट अतिरिक्त फील्डमुळे अयशस्वी होत नाही.
चुकीचा JSON प्रकार असलेल्या ज्ञात फील्डला, किंवा आवश्यक फील्ड नसल्यास, 422 मिळते. वैध JSON नसलेल्या बॉडीला 400 मिळते.
model हा Models & pricing वरील id पैकी एक असतो. मोठी आणि लहान अक्षरे महत्त्वाची नाहीत.

उत्तर JSON असते, किंवा रिक्वेस्ट stream true सेट करते तेव्हा server-sent events चा स्ट्रीम. प्रत्येक एंडपॉइंट स्वतःच्या फॉरमॅटमध्ये उत्तर देतो. प्रत्येक उत्तरात x-request-id हेडर असतो.

रिक्वेस्ट कोणत्या तपासण्यांतून जाते

मॉडेल चालण्यापूर्वी रिक्वेस्ट निश्चित क्रमाने तपासली जाते. अयशस्वी होणारी पहिली तपासणी उत्तर देते, त्यामुळे 401 बॉडीबद्दल अजून काहीही सांगत नाही.

या क्रमाने तपासले जाते	अयशस्वी झाल्यास स्टेटस
API की	`401`
बॉडी: आकार, कंटेंट प्रकार, JSON, फील्ड प्रकार	`413 · 415 · 400 · 422`
मॉडेल id	`400`
फ्लड प्रोटेक्शन: प्रति अकाउंट प्रति मिनिट 120 रिक्वेस्ट्स	`429`
बॅलन्स: रिक्वेस्टचे आउटपुट बजेट त्यात बसले पाहिजे	`429`

त्रुटीचे स्वरूप

त्रुटी म्हणजे type आणि message असलेला error धारण करणारा JSON ऑब्जेक्ट. /v1/messages तो Anthropic SDK ला अपेक्षित असलेल्या पद्धतीने गुंडाळते; इतर प्रत्येक पाथ 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 असते.
स्ट्रीम सुरू झाल्यानंतर स्टेटस आधीच 200 असते. तेव्हाचे अपयश स्ट्रीममध्ये एरर फ्रेम म्हणून येते.
प्रत्येक त्रुटी उत्तरात x-request-id हेडर असतो.

स्टेटस	प्रकार	केव्हा
`400`	`invalid_request_error`	बॉडी वैध JSON नाही, मॉडेल id अज्ञात आहे, किंवा तुम्ही पाठवलेला इनपुट प्रकार मॉडेल घेत नाही.
`401`	`authentication_error`	की नाही किंवा वैध नाही.
`404`	`not_found_error`	पाथ अस्तित्वात नाही.
`405`	`api_error`	पाथ अस्तित्वात आहे, मेथड चुकीची आहे.
`413`	`invalid_request_error`	बॉडी 32 MiB पेक्षा मोठी आहे.
`415`	`invalid_request_error`	`Content-Type` हे `application/json` नाही.
`422`	`invalid_request_error`	एखाद्या फील्डचा JSON प्रकार चुकीचा आहे किंवा आवश्यक फील्ड नाही.
`429`	`rate_limit_error`	बॅलन्स रिक्वेस्टसाठी पुरेसा नाही, एका मिनिटात 120 पेक्षा जास्त रिक्वेस्ट्स आल्या, विंडोमधील Shannon Coder कॉल्स संपले, किंवा मॉडेल व्यस्त आहे. संदेश कोणते ते सांगतो.
`5xx`	`api_error`	स्टेटस `500`, `502`, `503` किंवा `504`: रिक्वेस्ट वैध होती पण तिला उत्तर देता आले नाही. ती पुन्हा पाठवा. `500` मध्ये प्रकार `server_error` असू शकतो.

त्रुटी हाताळणी

बिलिंग आणि बॅलन्स

प्रत्येक अकाउंटसाठी एकच बॅलन्स आहे, आणि चॅट व API तो वाटून घेतात: आधी आजचा प्लॅन कोटा, मग खरेदी केलेले क्रेडिट. API ला स्वतःचा कोटा नाही.
रिक्वेस्ट तिचे आउटपुट बजेट (max_tokens, डिफॉल्ट 4,096) राखून ठेवते आणि नंतर प्रत्यक्ष वापरलेल्या टोकन्ससाठी मॉडेलच्या किमतीने आकारली जाते.
प्रत्येक उत्तर आपली टोकन संख्या usage मध्ये कळवते. Keys & usage पान बॅलन्स आणि प्रत्येक रिक्वेस्टचा खर्च दाखवते.
प्रत्येक रिक्वेस्टला समान वागणूक मिळते. रिक्वेस्ट दरावरील एकमेव मर्यादा फ्लड प्रोटेक्शन आहे: प्रति अकाउंट प्रति मिनिट 120 रिक्वेस्ट्स. समांतर पाठवलेल्या रिक्वेस्ट्स रांगेत थांबतात.

मर्यादा आणि बॅलन्स मॉडेल्स आणि किंमत की आणि वापर

मॉडेलवर अवलंबून असलेली फील्ड्स

प्रत्येक मॉडेल सारखीच रिक्वेस्ट घेते. काही फील्ड्स फक्त काही मॉडेल्सवर परिणाम करतात; तक्ता कुठे ते सांगतो. एंडपॉइंट पानांवर प्रत्येक फील्ड दिले आहे.

फील्ड	वर्णन	लागू करणारे
`system`	मॉडेलसाठी सूचना: Chat Completions वर `system` संदेश, Messages वर `system`, Responses वर `instructions`.	होस्ट केलेली open-weight मॉडेल्स, `shannon-1.6-`, `shannon-2-`, `shannon-coder-1`
`temperature`	सॅम्पलिंग टेंपरेचर.	होस्ट केलेली open-weight मॉडेल्स, `shannon-1.6-*`, `shannon-coder-1`
`top_p`	न्यूक्लियस सॅम्पलिंग.	होस्ट केलेली open-weight मॉडेल्स
`seed`	सॅम्पलिंगसाठी निश्चित सीड.	होस्ट केलेली open-weight मॉडेल्स
`stop`	जास्तीत जास्त 4 स्टॉप सीक्वेन्स.	होस्ट केलेली open-weight मॉडेल्स
`reasoning_effort`	मॉडेल उत्तर देण्यापूर्वी किती रीझनिंग करते. Responses वर `reasoning.effort`, Messages वर `thinking`.	होस्ट केलेली open-weight मॉडेल्स
`web_search`	`true` मॉडेलला या रिक्वेस्टसाठी वेबवर शोधू देते. या API चे फील्ड, Chat Completions आणि Messages वर.	`shannon-coder-1` खेरीज Shannon मॉडेल्स
`max_tokens`	आउटपुट बजेट. प्रत्येक मॉडेलवर ते तुमच्या बॅलन्समधून राखून ठेवलेली रक्कम ठरवते.	उत्तराच्या लांबीची मर्यादा म्हणून: होस्ट केलेली open-weight मॉडेल्स, `shannon-1.6-*`, `shannon-coder-1`

Chat Completions

OpenAI SDK मधून येत असल्यास

बेस URL https://api.shannon-ai.com/v1 ला सेट करा आणि की तुमच्या Shannon कीला. त्यानंतर Chat Completions आणि Responses कॉल्स SDK सोबत जसेच्या तसे चालतात.
model Shannon id असला पाहिजे. gpt-4o सारख्या दुसऱ्या प्रोव्हायडरच्या मॉडेल नावाला 400 आणि unknown model मिळते.
रीझनिंग स्वतःच्या फील्डमध्ये येते: संदेशात आणि स्ट्रीम डेल्टामध्ये content च्या शेजारी reasoning_content.
स्ट्रीम नेहमी शेवटच्या चंकमध्ये finish_reason सोबत usage देतो.
स्ट्रीममधील टूल कॉल संपूर्ण arguments स्ट्रिंग असलेल्या एका चंकमध्ये येतो.
उत्तरात एकच choice असते.
वरील तक्त्यात नसलेले OpenAI API चे पाथ, जसे /v1/embeddings, यांना 404 मिळते.

Anthropic SDK मधून येत असल्यास

बेस URL https://api.shannon-ai.com ला सेट करा, /v1 शिवाय, आणि की तुमच्या Shannon कीला. SDK ती x-api-key म्हणून पाठवतो.
model Shannon id असला पाहिजे.
या API वर max_tokens ऐच्छिक आहे. त्याचे डिफॉल्ट 4,096 आहे.
उत्तरात thinking, text आणि tool_use प्रकारचे कंटेंट ब्लॉक्स असतात. पहिला ब्लॉक नेहमीच मजकूर नसतो: ब्लॉक्स type वरून निवडा.
stop_reason end_turn किंवा tool_use असतो. Shannon मॉडेलचा स्ट्रीम max_tokens ने देखील संपू शकतो.
anthropic-version आणि anthropic-beta स्वीकारले जातात, म्हणून SDK बदल न करता चालतो. रिक्वेस्टला त्यांची गरज नाही.
/v1/messages वरील त्रुटींचे स्वरूप Anthropic प्रमाणे असते: {"type": "error", "error": {…}}.

हे फॉरमॅट बोलणारी कोडिंग टूल्स त्याच प्रकारे सेट होतात: बेस URL, की आणि मॉडेल म्हणून Shannon id. CLI कोडिंग टूल्स