ወደ ይዘቱ እለፍ
አጠቃላይ እይታ

አጠቃላይ እይታ

የAPI ካርታ፦ እያንዳንዱ endpoint፣ ጥያቄና ስህተት ምን እንደሚመስሉ፣ ጥሪዎች እንዴት እንደሚከፈሉ፣ እና ከOpenAI ወይም ከAnthropic SDK ሲመጡ ማወቅ የሚገባዎት።

Endpoints

እያንዳንዱ endpoint በአንድ base URL ስር ይገኛል እና በHTTPS ይቀርባል።

Base URL 
https://api.shannon-ai.com
ኤንድ-ፖይንት (Endpoint) ፎርማት ለምን ይጠቅማል
POST /v1/chat/completions OpenAI Chat Completions ውይይት ይላኩ፣ ቀጣዩን መልስ ያግኙ። ከstreaming ጋር ወይም ያለሱ።
POST /v1/messages Anthropic Messages ተመሳሳይ፣ በAnthropic SDKs የጥያቄና የምላሽ ቅርጾች።
POST /v1/responses OpenAI Responses ተመሳሳይ፣ በResponses ቅርጾች። endpoint ምንም state አይይዝም፦ ውይይቱን በእያንዳንዱ ጥያቄ ይላኩ።
GET /v1/models OpenAI model list ሞዴሎችን ከcontext window፣ ዋጋዎች እና ችሎታዎች ጋር ይዘርዝሩ። ቁልፍ አያስፈልግም።
POST /v1/tokenize Shannon API የጽሑፍ ወይም የchat ጥያቄ tokens ለተስተናገደ open-weight ሞዴል ይቁጠሩ። ነፃ።
POST /v1/messages/count_tokens Anthropic token count የMessages ጥያቄን input tokens ለተስተናገደ open-weight ሞዴል ይቁጠሩ። ነፃ።

ጽሑፍ የሚያመነጩት ሦስቱ endpoints ወደ ተመሳሳይ ሞዴሎች ይደርሳሉ። ኮድዎ አስቀድሞ ፎርማቱን የሚጠቀምበትን ይምረጡ።

የጥያቄ መሠረታዊ ነገሮች

Header መግለጫ
Authorization: Bearer <key> የእርስዎ API ቁልፍ። x-api-key ካልላኩ ከGET /v1/models በስተቀር በእያንዳንዱ endpoint ላይ ግዴታ ነው።
x-api-key: <key> ተመሳሳዩ ቁልፍ Anthropic SDKs በሚልኩት header ውስጥ። በእያንዳንዱ endpoint ላይ ይነበባል።
Content-Type: application/json በእያንዳንዱ POST ላይ ግዴታ ነው። ያለ እሱ ምላሹ 415 ነው።
x-request-id: <your id> አማራጭ። ለጥያቄው የራስዎ id፤ በምላሽ header x-request-id ይመለሳል። ያለ እሱ API የ12 ሄክሳዴሲማል ቁምፊዎች id ይፈጥራል።
  • የእያንዳንዱ POST body አንድ JSON object ነው፣ እስከ 32 MiB።
  • API የማያውቀው መስክ ምንም ስህተት አያስከትልም እና ምንም ውጤት የለውም። ለሌላ አቅራቢ የተጻፈ ጥያቄ በተጨማሪ መስክ ምክንያት አይከሽፍም።
  • የተሳሳተ JSON አይነት ያለው የሚታወቅ መስክ ወይም የጎደለ አስፈላጊ መስክ በ422 ይመለሳል። ትክክለኛ JSON ያልሆነ body በ400 ይመለሳል።
  • model በModels & pricing ላይ ካሉት id ዎች አንዱ ነው። ትላልቅና ትናንሽ ፊደላት ለውጥ አያመጡም።

ምላሽ JSON ነው፣ ወይም ጥያቄው streamን ወደ true ሲያዘጋጅ የserver-sent events stream። እያንዳንዱ endpoint በራሱ ፎርማት ይመልሳል። እያንዳንዱ ምላሽ x-request-id header አለው።

ጥያቄ የሚያልፈው

ጥያቄ ሞዴል ከመስራቱ በፊት በተወሰነ ቅደም ተከተል ይፈተሻል። መጀመሪያ የሚወድቀው ፍተሻ ይመልሳል፣ ስለዚህ 401 ስለ body እስካሁን ምንም አይነግርዎትም።

በዚህ ቅደም ተከተል የሚፈተሸው ሲከሽፍ ያለው Status
API ቁልፍ 401
Body፦ መጠን፣ content type፣ JSON፣ የመስክ አይነቶች 413 · 415 · 400 · 422
የሞዴል id 400
የጥያቄ ብዛት ጥበቃ፦ በመለያ በደቂቃ 120 ጥያቄዎች 429
ቀሪ ሂሳብ፦ የጥያቄው የውጤት በጀት መግባት አለበት 429

የስህተት ቅርጽ

ስህተት type እና message የያዘ error ያለው JSON object ነው። /v1/messages የAnthropic SDKs በሚጠብቁት መንገድ ይጠቀልለዋል፤ ሌሎች መንገዶች ሁሉ የOpenAI ቅርጽ ይጠቀማሉ።

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}
  • type እና message ያንብቡ። code እና param በአንዳንድ ስህተቶች ላይ ብቻ ይገኛሉ፦ እንደ አማራጭ ይያዟቸው። param ሁልጊዜ null ነው።
  • stream ከጀመረ በኋላ status አስቀድሞ 200 ነው። ከዚያ የሚከሰት ብልሽት በstream ውስጥ እንደ error frame ይመጣል።
  • እያንዳንዱ የስህተት ምላሽ x-request-id header ይይዛል።
ሁኔታ ዓይነት መቼ
400 invalid_request_error body ትክክለኛ JSON አይደለም፣ የሞዴሉ id አይታወቅም፣ ወይም ሞዴሉ የላኩትን የግብዓት አይነት አይቀበልም።
401 authentication_error ቁልፉ የለም ወይም ትክክል አይደለም።
404 not_found_error መንገዱ የለም።
405 api_error መንገዱ አለ፣ method ግን ስህተት ነው።
413 invalid_request_error body ከ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 Status 500፣ 502፣ 503 ወይም 504፦ ጥያቄው ትክክለኛ ነበር ግን ሊመለስ አልቻለም። እንደገና ይላኩት። 500 የserver_error አይነት ሊይዝ ይችላል።

ስህተት አስተዳደር

ክፍያ እና ቀሪ ሂሳብ

  • በአንድ መለያ አንድ ቀሪ ሂሳብ አለ፣ chat እና API ይጋሩታል፦ መጀመሪያ የዛሬው የዕቅድ ዕለታዊ መጠን፣ ከዚያ የተገዛ ክሬዲት። API የራሱ quota የለውም።
  • ጥያቄ የውጤት በጀቱን (max_tokens፣ default 4,096) ይይዛል፣ ከዚያ በእውነት ለተጠቀመባቸው tokens በሞዴሉ ዋጋ ይከፈላል።
  • እያንዳንዱ ምላሽ የtoken ቆጠራውን በusage ያሳውቃል። የKeys & usage ገጽ ቀሪ ሂሳቡን እና እያንዳንዱ ጥያቄ ምን እንዳስከፈለ ያሳያል።
  • እያንዳንዱ ጥያቄ እኩል ይስተናገዳል። በጥያቄ ፍጥነት ላይ ያለው ብቸኛ ገደብ የጥያቄ ብዛት ጥበቃ ነው፦ በመለያ በደቂቃ 120 ጥያቄዎች። በትይዩ የተላኩ ጥያቄዎች ተራ ይጠብቃሉ።

ገደቦች እና ቀሪ ሂሳብ ሞዴሎችና ዋጋ Keys & usage

በሞዴሉ ላይ የሚመሰረቱ መስኮች

እያንዳንዱ ሞዴል ተመሳሳዩን ጥያቄ ይቀበላል። ጥቂት መስኮች በአንዳንድ ሞዴሎች ላይ ብቻ ይሰራሉ፤ ሠንጠረዡ የት እንደሆነ ይጠቅሳል። የendpoint ገጾች እያንዳንዱን መስክ ይዘረዝራሉ።

መስክ መግለጫ የሚተገብሩት
system ለሞዴሉ መመሪያዎች፦ በChat Completions ላይ system መልእክት፣ በMessages ላይ system፣ በResponses ላይ instructions። የተስተናገዱ open-weight ሞዴሎች፣ shannon-1.6-*፣ shannon-2-*፣ shannon-coder-1
temperature የsampling temperature። የተስተናገዱ open-weight ሞዴሎች፣ shannon-1.6-*፣ shannon-coder-1
top_p Nucleus sampling። የተስተናገዱ open-weight ሞዴሎች
seed ለናሙና አወሳሰድ (sampling) የሚያገለግል ቋሚ 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 ሲመጡ

  • base URL ን ወደ https://api.shannon-ai.com/v1 ያዘጋጁ፣ ቁልፉንም ወደ Shannon ቁልፍዎ። ከዚያ የChat Completions እና የResponses ጥሪዎች ከSDK ጋር እንዳሉ ይሰራሉ።
  • model የShannon id መሆን አለበት። እንደ gpt-4o ያለ የሌላ አቅራቢ የሞዴል ስም በ400 እና በunknown model ይመለሳል።
  • Reasoning በራሱ መስክ ይመጣል፦ reasoning_content ከcontent ጎን፣ በመልእክቱ እና በstream deltas ውስጥ።
  • stream ሁልጊዜ usageን በመጨረሻው chunk ከfinish_reason ጋር ይይዛል።
  • በstream ውስጥ የtool ጥሪ ሙሉ arguments string ባለው አንድ chunk ይደርሳል።
  • ምላሽ አንድ choice አለው።
  • ከላይ ባለው ሠንጠረዥ ውስጥ የሌሉ የOpenAI API መንገዶች፣ ለምሳሌ /v1/embeddings፣ በ404 ይመለሳሉ።

ከAnthropic SDK ሲመጡ

  • base URL ን ወደ https://api.shannon-ai.com ያለ /v1 ያዘጋጁ፣ ቁልፉንም ወደ Shannon ቁልፍዎ። SDK እንደ x-api-key ይልከዋል።
  • model የShannon id መሆን አለበት።
  • በዚህ API ላይ max_tokens አማራጭ ነው። default 4,096 ነው።
  • ምላሽ የthinking፣ text እና tool_use አይነት content blocks ይይዛል። የመጀመሪያው block ሁልጊዜ ጽሑፉ አይደለም፦ blocks ን በtype ይምረጡ።
  • stop_reason end_turn ወይም tool_use ነው። የShannon ሞዴል stream በmax_tokens ሊያበቃም ይችላል።
  • anthropic-version እና anthropic-beta ተቀባይነት አላቸው፣ ስለዚህ SDK ሳይቀየር ይሰራል። ጥያቄው አያስፈልጋቸውም።
  • በ/v1/messages ላይ ያሉ ስህተቶች የAnthropic ቅርጽ አላቸው፦ {"type": "error", "error": {…}}።

እነዚህን ፎርማቶች የሚናገሩ coding tools በተመሳሳይ መንገድ ይዋቀራሉ፦ base URL፣ ቁልፍ፣ እና እንደ ሞዴል የShannon id። የCLI ኮዲንግ መሣሪያዎች