ወደ ይዘቱ እለፍ
Chat Completions

Chat Completions

POST /v1/chat/completions ውይይትን ተቀብሎ የሞዴሉን ቀጣይ መልእክት በOpenAI Chat Completions ቅርጸት ይመልሳል። ከማንኛውም የOpenAI SDK ወይም በተራ HTTP ይጠቀሙት፤ ይህ ገጽ መስክ በመስክ ማጣቀሻ ነው።

POST https://api.shannon-ai.com/v1/chat/completions

ትንሹ ጥያቄ የሞዴል id እና አንድ የተጠቃሚ መልእክት ነው።

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1",
)

response = client.chat.completions.create(
    model="shannon-3",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)

print(response.choices[0].message.content)

ምላሹ አንድ የJSON ነገር ነው፦

200 JSON 
{
  "id": "chatcmpl-5f0c1e7a9b3d4c62a8e1f07d2b46c9a3",
  "object": "chat.completion",
  "created": 1791625200,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello, it is good to meet you.",
        "reasoning_content": "The user wants a greeting in one sentence. Keep it short and friendly."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1184,
    "completion_tokens": 46,
    "total_tokens": 1230
  }
}

Headers

የጥያቄ headers

Header እሴት መግለጫ
Authorization Bearer YOUR_API_KEY የእርስዎ API ቁልፍ። በእያንዳንዱ endpoint ላይ በቦታው x-api-key: YOUR_API_KEY ተቀባይነት አለው።
Content-Type application/json ያስፈልጋል። ሌላ ማንኛውም እሴት 415 ይመልሳል።
x-request-id አማራጭ። ለጥያቄው የራስዎ id። በምላሹ ላይ ሳይቀየር ይመለሳል።

የምላሽ headers

Header መግለጫ
x-request-id በእያንዳንዱ ምላሽ ላይ፣ ስህተቶችና streams ጨምሮ፦ የላኩት እሴት፣ ወይም ምንም ካልላኩ 12 ሄክሳዴሲማል ቁምፊዎች። ችግር ሲያሳውቁ ይጥቀሱት።
content-type application/json፣ ወይም stream true ሲሆን text/event-stream።

የጥያቄ መስኮች

የሚያስፈልገው messages ብቻ ነው። የሚተገብሩት ዓምድ መስኩ ምላሹን የሚለውጥባቸውን ሞዴሎች ይጠራል። የሆስት open-weight ሞዴሎች በሞዴል ዝርዝሩ ውስጥ ያሉት አስራ ሁለት ids ናቸው፤ የShannon 3 ቤተሰብ shannon-3, shannon-3-pro, shannon-3.1 እና shannon-3.1-pro ነው። ሞዴሎችና ዋጋ

መስክ ዓይነት ነባሪ መግለጫ የሚተገብሩት
model string shannon-1.6-lite የሚመልሰው ሞዴል፦ ከሞዴል ዝርዝሩ id። በእያንዳንዱ ጥያቄ ይላኩት። ማዛመዱ ለአቢይ/ትንሽ ፊደል ግድ የለውም። ያልታተመ id 400 unknown model ይመልሳል። ሁሉም ሞዴሎች
messages array ያስፈልጋል። ውይይቱ፣ የቆየው መልእክት መጀመሪያ። ከታች ያሉትን መልእክቶች ይመልከቱ። ሁሉም ሞዴሎች
stream boolean false true ምላሹን በሚጻፍበት ጊዜ እንደ server-sent events ይልካል። ሁሉም ሞዴሎች
max_tokens integer 4096 የምላሹ ከፍተኛ ገደብ፣ በtokens። ከ 1 እስከ 65,536 ውጭ ያለ እሴት ወደዚያ ክልል ይወሰዳል። ጥያቄው በሚሰራበት ጊዜ ከቀሪ ሂሳብዎ ተለይቶ የሚቀመጠውም መጠን ነው። ከታች ያለውን የውጤት ርዝመት ይመልከቱ። የሆስት open-weight ሞዴሎች፣ shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
max_completion_tokens integer ከmax_tokens ጋር አንድ ነው። ሁለቱም ሲላኩ max_tokens ይጠቀማል። የሆስት open-weight ሞዴሎች፣ shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
temperature number Sampling temperature። በሆስት open-weight ሞዴሎች ላይ ነባሪው 1 ነው እና እሴቶች ከ 0 እስከ 2 መካከል ይቆያሉ። የሆስት open-weight ሞዴሎች፣ shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
top_p number 0.95 Nucleus sampling። እሴቶች ከ 0 እስከ 1 መካከል ይቆያሉ። የሆስት open-weight ሞዴሎች
seed integer የsampler ዘር፣ ማንኛውም ኢንቲጀር። ከሌለ ዘሩ ከሞዴሉና ከውይይቱ ይመነጫል፣ ስለዚህ ሁለት ጊዜ የተላከ ተመሳሳይ ጥያቄ ተመሳሳይ ዘር ይጠቀማል። የሆስት open-weight ሞዴሎች
stop string | array string ወይም የstrings array። እስከ 4 ይጠቀማሉ። መልሱ ከሚታየው የመጀመሪያው በፊት ያበቃል፤ የማቆሚያው ጽሑፍ ራሱ አይመለስም። የሆስት open-weight ሞዴሎች
reasoning_effort string high ሞዴሉ ከመመለሱ በፊት ምን ያህል እንደሚያስብ፦ off, low, medium ወይም high። none እና minimal off ማለት ናቸው፣ default medium ማለት ነው፣ max high ማለት ነው። ሌላ ማንኛውም እሴት 400 ይመልሳል። የሆስት open-weight ሞዴሎች
reasoning object ተመሳሳይ ቅንብር በነገር ቅርጽ፦ {"effort": "low"}። ሁለቱም ሲላኩ reasoning_effort ይጠቀማል። የሆስት open-weight ሞዴሎች
tools array ሞዴሉ ሊጠራቸው የሚችሉ ፋንክሽኖች፣ እያንዳንዱ እንደ {"type": "function", "function": {"name", "description", "parameters"}}። የሞዴሉ ጥሪዎች በtool_calls ይመለሳሉ፤ ኮድዎ ያስኬዳቸዋል። ሁሉም ሞዴሎች
tool_choice string | object auto "auto" ሞዴሉ እንዲወስን ያደርጋል። "required" tool እንዲጠራ ያደርገዋል። {"type": "function", "function": {"name": "…"}} ያንን tool እንዲጠራ ያደርገዋል። የሆስት open-weight ሞዴሎች
response_format object ለJSON መልስ {"type": "json_object"}፣ ወይም schemaዎን ለሚከተል መልስ {"type": "json_schema", "json_schema": {…}}። ሁሉም የShannon ደረጃዎች፤ የሆስት open-weight ሞዴሎች በid እንደተዘረዘረው
web_search boolean false true ሞዴሉ ከመመለሱ በፊት ድሩን እንዲፈልግ ያደርገዋል። shannon-1.6-*, shannon-2-*, Shannon 3 ቤተሰብ

ሌሎች የOpenAI መስኮች፣ ለምሳሌ n, user, stream_options, parallel_tool_calls, presence_penalty, frequency_penalty, logit_bias, logprobs, metadata, store እና prompt_cache_key፣ ነባር የክላይንት ኮድ ሳይቀየር እንዲሰራ ይቀበላሉ። ምላሹን አይለውጡም፦ ሁልጊዜ አንድ choice ብቻ አለ፣ እና stream ሁልጊዜ በusage ያበቃል።

የተሳሳተ የJSON ዓይነት ያለው መስክ፣ ለምሳሌ "max_tokens": "100"፣ 422 ይመልሳል። messages የሌለው ጥያቄም እንዲሁ።

Tools፣ የተዋቀረ ውጤት፣ reasoning እና ድር ፍለጋ እያንዳንዳቸው የራሳቸው ገጽ አላቸው፦ ፋንክሽን ጥራት, የተዋቀሩ ውጤቶች, Reasoning effort, የተገናኘ ድር ፍለጋ.

አማራጮች ያሉት ጥያቄ

ይህ ጥያቄ የsystem መልእክት፣ የsampling መስኮችን እና የreasoning effortን ያዘጋጃል። ሁሉንም የሚተገብር የሆስት open-weight ሞዴል ይጠቀማል።

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1",
)

response = client.chat.completions.create(
    model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    messages=[
        {"role": "system", "content": "You are a physics teacher. Answer in two sentences."},
        {"role": "user", "content": "Why is the sky blue?"},
    ],
    max_tokens=512,
    temperature=0.3,
    top_p=0.9,
    seed=7,
    stop=["\n\n"],
    reasoning_effort="low",
)

message = response.choices[0].message
print(message.reasoning_content)  # the reasoning
print(message.content)            # the answer
print(response.usage)

ምላሹ ከላይ ያለው ቅርጽ አለው። በሆስት open-weight ሞዴሎች ላይ usageው ሁለት ዝርዝሮችን ይጨምራል፦ ከcache የተነበቡ የprompt tokens እና በreasoning ላይ የዋሉ tokens።

200 JSON 
{
  "usage": {
    "prompt_tokens": 31,
    "completion_tokens": 62,
    "total_tokens": 93,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 21
    }
  }
}

የውጤት ርዝመት

max_tokens ሁለት ነገሮችን ያደርጋል። አንደኛ፣ ጥያቄው ሲጀምር ከቀሪ ሂሳብዎ ተለይተው የሚቀመጡ የtokens ብዛት ነው። ምላሹ ሲጠናቀቅ ያ መጠን ጥያቄው በተጠቀመባቸው tokens ይተካል። max_tokens ከቀሪ ሂሳብዎ ከቀረው ከበለጠ፣ ምላሹ ራሱ የሚበቃ ቢሆንም ጥያቄው 429 Quota exceeded ይመልሳል። ያነሰ ለማስቀመጥ ዝቅተኛ max_tokens ይላኩ።

shannon-coder-1 በዚህ endpoint ላይ በተለየ መንገድ ይቆጠራል፦ እያንዳንዱ ጥያቄ ከፕላንዎ የShannon Coder ጥሪዎች አንዱ ነው፣ እና ለእሱ ምንም tokens ተለይተው አይቀመጡም። ገደቦች እና ቀሪ ሂሳብ

ሁለተኛ፣ በእነዚህ ሞዴሎች ላይ የምላሹን ርዝመት ይገድባል፦

ሞዴሎች max_tokens ምን ያደርጋል
shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 ምላሹ ገደቡ ላይ ሲደርስ ይቆማል። ከዚያ stream በfinish_reason length ያበቃል።
የሆስት open-weight ሞዴሎች የመልሱ ጽሑፍ በmax_tokens ይቆማል። Reasoning በእሱ ላይ አይቆጠርም። ከ256 በታች ያሉ እሴቶች እንደ 256 ይሰራሉ።

max_tokens ወይም max_completion_tokens ከሌለ እሴቱ 4,096 ነው። በshannon-coder-1 ላይ 65,536 ነው።

መልእክቶች

እያንዳንዱ መልእክት role እና content ያለው ነገር ነው። content string ነው፣ ወይም መልእክቱ ከጽሑፍ በላይ ሲይዝ የክፍሎች array።

ሚና መግለጫ የሚተገብሩት
system ለሞዴሉ መመሪያዎች። መጀመሪያ ያስቀምጡት። በShannon ደረጃዎች ላይ የሚጠቀመው የመጀመሪያው system መልእክት ነው። የሆስት open-weight ሞዴሎች፣ shannon-1.6-*, shannon-2-*, shannon-coder-1
developer እንደ system ይነበባል። የሆስት open-weight ሞዴሎች
user የሚጠይቁት። በShannon ደረጃዎች ላይ የመጨረሻው user መልእክት prompt ነው እና ከእሱ በፊት ያሉት መልእክቶች ታሪኩ ናቸው። ሁሉም ሞዴሎች
assistant የሞዴሉ ቀድሞ ምላሾች። ከእሱ በኋላ የtool ውጤት ሲልኩ tool_callsን ያቆዩ። ሁሉም ሞዴሎች
tool የtool ጥሪ ውጤት፦ tool_call_id የጥሪውን id ይይዛል እና content ውጤቱን እንደ string። ሁሉም ሞዴሎች

የShannon 3 ቤተሰብ id ሲጠቀሙ፣ መከበር ያለባቸውን መመሪያዎች በuser መልእክት ውስጥ ያስገቡ።

በShannon ደረጃዎች ላይ የተጠቃሚ ጽሑፍ እና tools የሌለው ጥያቄ 400 No user message provided ይመልሳል።

የይዘት ክፍሎች

ክፍል መግለጫ የሚገኘው በ
{"type": "text", "text": "…"} ተራ ጽሑፍ። ሁሉም ሞዴሎች
{"type": "image_url", "image_url": {"url": "…"}} ምስል፣ እንደ base64 ይዘት ያለው data: URL ወይም እንደ http(s) URL። Shannon 3 ቤተሰብ፣ shannon-1.6-lite, shannon-1.6-pro, እና የምስል input የሚዘረዝሩ የሆስት open-weight ሞዴሎች
{"type": "file", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} ሰነድ (PDF፣ Word፣ PowerPoint ወይም Excel)፣ እንደ base64 ወይም በURL። Shannon 3 ቤተሰብ

መጠኖች፣ ገደቦች እና የቅርጾች ሙሉ ዝርዝር የራሳቸው ገጽ አላቸው። ምስሎች እና ፋይሎች

የምላሽ ነገር

መስክ ዓይነት መግለጫ
id string chatcmpl- እና ከዚያ 32 ሄክሳዴሲማል ቁምፊዎች።
object string ሁልጊዜ chat.completion።
created integer የምላሹ ጊዜ፣ በUnix ሰከንዶች።
model string የመለሰው ሞዴል ትክክለኛ id። ከላኩት id በፊደል አጻጻፍ ሊለይ ይችላል።
choices array ሁልጊዜ በትክክል አንድ choice፣ index 0 ያለው።
choices[0].message.role string ሁልጊዜ assistant።
choices[0].message.content string | null የመልሱ ጽሑፍ። ከtool_calls ጋር በShannon ደረጃዎች ላይ null ነው፤ የሆስት open-weight ሞዴሎች ከጥሪዎቹ ጎን ጽሑፍ ሊልኩ ይችላሉ።
choices[0].message.reasoning_content string | null ሞዴሉ ከመልሱ በፊት የጻፈው reasoning፣ ወይም ምንም ከሌለ null።
choices[0].message.tool_calls array ሞዴሉ tools ሲጠራ ብቻ ይኖራል። እያንዳንዱ ግቤት id፣ type function፣ እና name እና arguments እንደ JSON string ያለው function አለው።
choices[0].message.annotations array ፍለጋው አንድ ነገር ባገኘ web_search: true ባለው ጥያቄ ላይ ብቻ። በcontent ውስጥ ያለ ምልክት ለሰየመው እያንዳንዱ ምንጭ አንድ url_citation፣ ከurl፣ title፣ start_index እና end_index ጋር (የምልክቱ አቀማመጥ በቁምፊዎች ተቆጥሮ፣ መጨረሻው አይካተትም)።
choices[0].finish_reason string ምላሹ ለምን እንዳበቃ። የማብቂያ ምክንያቶችን ይመልከቱ።
usage object የጥያቄው tokens። አጠቃቀምን ይመልከቱ።
sources array ፍለጋው አንድ ነገር ባገኘ web_search: true ባለው ጥያቄ ላይ ብቻ፦ ለሞዴሉ የተሰጡት ውጤቶች፣ እያንዳንዳቸው ከindex፣ title እና url ጋር። በመልሱ ውስጥ ያለው [1] index 1 ያለው ግቤት ነው።

የማብቂያ ምክንያቶች

finish_reason መግለጫ
stop ሞዴሉ መልሱን ጨርሷል፣ ወይም stop string ታይቷል።
tool_calls ሞዴሉ አንድ ወይም ከዚያ በላይ tools ይጠራል። ያስኬዷቸው እና ውጤቶቹን በtool መልእክቶች ይላኩ።
length ምላሹ በውጤት ገደቡ ላይ ተቆርጧል። በshannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 እና በShannon 3 ቤተሰብ streams ውስጥ ይገለጻል።

stream ያልሆነ ምላሽ stop ወይም tool_calls ያሳውቃል።

አጠቃቀም

መስክ ዓይነት መግለጫ የሚገኘው በ
usage.prompt_tokens integer Input tokens። ሁሉም ሞዴሎች
usage.completion_tokens integer Output tokens፦ reasoning፣ መልስ እና የtool ጥሪዎች በአንድ ላይ። ሁሉም ሞዴሎች
usage.total_tokens integer prompt_tokens ሲደመር completion_tokens። ሁሉም ሞዴሎች
usage.prompt_tokens_details.cached_tokens integer ከprompt cache የተነበበው የprompt_tokens ክፍል። የሆስት open-weight ሞዴሎች
usage.completion_tokens_details.reasoning_tokens integer በreasoning ላይ የዋለው የcompletion_tokens ክፍል። የሆስት open-weight ሞዴሎች

በሆስት open-weight ሞዴሎች ላይ prompt_tokens መልእክቶችዎና የtool ትርጓሜዎችዎ በሞዴሉ የራሱ tokenizer ተቆጥረው፣ ከምስሎች tokens ጋር ነው። የtoken ቆጠራ endpoints ከመላክዎ በፊት ተመሳሳዩን ቁጥር ይመልሳሉ። የToken ቆጠራ

በShannon ደረጃዎች ላይ prompt_tokens ምላሹን ለመጻፍ ሞዴሉ ያነበበውን ሁሉ ይቆጥራል፣ ስለዚህ ከመልእክቶችዎ ጽሑፍ ብቻ ይበልጣል።

Streaming

stream ወደ true ሲዘጋጅ ምላሹ እንደ chat.completion.chunk events ይደርሳል እና በdata: [DONE] ያበቃል። ከእሱ በፊት ያለው የመጨረሻ chunk finish_reason እና usage ይይዛል፤ stream_options አያስፈልጉም። የchunk ቅርጾች፣ keep-alive መስመሮች እና በstream ውስጥ ያሉ ስህተቶች የራሳቸው ገጽ አላቸው። ስትሪሚንግ

ስህተቶች

ስህተት error አባል ያለው የJSON ነገር ነው። ፍተሻዎች በዚህ ቅደም ተከተል ይካሄዳሉ፦ API ቁልፍ፣ የጥያቄ አካል፣ የሞዴል id፣ ከዚያ ቀሪ ሂሳብ። ሠንጠረዡ ይህ endpoint ብዙ ጊዜ የሚመልሰውን ይዘረዝራል። ሙሉ ዝርዝሩ፣ ምን እንደገና መሞከር እንዳለበት ጋር፣ የራሱ ገጽ አለው። ስህተት አስተዳደር

400 JSON 
{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}
ሁኔታ ዓይነት መልእክት መቼ
401 authentication_error Missing authentication
Invalid API key 		API ቁልፍ አልተላከም፣ ወይም ቁልፉ የማይታወቅ ወይም የተሰረዘ ነው።
400 invalid_request_error unknown model: <id> model የታተመ id አይደለም።
400 invalid_request_error No user message provided የShannon ደረጃዎች፦ ጥያቄው የተጠቃሚ ጽሑፍ የለውም እና tools የለውም።
400 invalid_request_error <id> does not accept image input የምስል ክፍል የምስል input ለሌለው የሆስት open-weight ሞዴል ተልኳል።
400 invalid_request_error <id> does not accept response_format response_format የተዋቀረ ውጤት ለሌለው የሆስት open-weight ሞዴል ተልኳል።
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high reasoning_effort ከዝርዝሩ ውጭ የሆነ እሴት ይዟል።
422 invalid_request_error Failed to deserialize the JSON body into the target type: … messages የለም፣ ወይም አንድ መስክ የተሳሳተ የJSON ዓይነት አለው።
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan max_tokens ከቀሪ ሂሳብዎ ከቀረው ይበልጣል።
429 rate_limit_error Too many requests. Retry in <n>s. Flood protection፦ በመለያዎ በአንድ ደቂቃ ከ120 በላይ ጥያቄዎች።
500 server_error The model backend failed to answer. Please retry. ሞዴሉ ምላሽ አላመረተም። ጥያቄውን እንደገና ይላኩ።
502 api_error The model backend failed to answer. Please retry. ተመሳሳይ፣ በShannon 3 ቤተሰብ እና በሆስት open-weight ሞዴሎች ላይ።