ናብ ትሕዝቶ ዝለል
Chat Completions

Chat Completions

POST /v1/chat/completions ዘተ ወሲዱ ቀጻሊ መልእኽቲ ናይ ሞዴል ብቅርጺ OpenAI Chat Completions ይመልስ። ካብ ዝኾነ OpenAI SDK ወይ ብቀሊል HTTP ተጠቐሞ፤ እዚ ገጽ field-ብ-field መወከሲ እዩ።

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

እቲ ዝንእሰ ጠለብ ሞዴል id ከምኡውን ሓደ user መልእኽቲ እዩ።

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 object እዩ፦

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 ቁልፍኻ። ኣብ ክንዲኡ x-api-key: YOUR_API_KEY ኣብ ነፍሲ ወከፍ endpoint ይቕበል።
Content-Type application/json ግዴታ። ዝኾነ ካልእ ዋጋ 415 ይመልስ።
x-request-id ኣማራጺ። ናትካ ባዕልኻ id ናይ ጠለብ። ኣብ ምላሽ ከይተቐየረ ይምለስ።

ናይ ምላሽ headers

Header መግለጺ
x-request-id ኣብ ነፍሲ ወከፍ ምላሽ፣ ጌጋታትን streamsን ጨሚሩ፦ ዝልእኽካዮ ዋጋ፣ ወይ ዋላ ሓንቲ ምስ ዘይለኣኽካ 12 hexadecimal ፊደላት። ጸገም ክትሕብር ከሎ ጠቐስዎ።
content-type application/json፣ ወይ stream true ክኸውን ከሎ text/event-stream።

ናይ ጠለብ fields

messages ጥራይ ግዴታ እዩ። እቲ ዝተጠቐመሉ ዓምዲ field ምላሽ ዝቕይረሉ ሞዴላት ይሰምዮም። ዝተሃንደሱ open-weight ሞዴላት እቶም ኣብ ዝርዝር ሞዴላት ዘለዉ ዓሰርተው ክልተ ids እዮም፤ Shannon 3 ስድራ shannon-3፣ shannon-3-pro፣ shannon-3.1 ከምኡውን shannon-3.1-pro እዮም። ሞዴላትን ዋጋን

Field ዓይነት ነባሪ መግለጺ ዝተጠቐመሉ
model string shannon-1.6-lite እቲ ዝምልስ ሞዴል፦ ካብ ዝርዝር ሞዴላት ዝተወስደ id። ምስ ነፍሲ ወከፍ ጠለብ ልኣኾ። ምስንዳይ ኣብ ዓቐን ፊደል ኣይውሰድን። ዘይታወጀ id 400 unknown model ይመልስ። ኩሎም ሞዴላት
messages array ግዴታ። እቲ ዘተ፣ እቲ ዝቀደመ መልእኽቲ ቀዳማይ። ኣብ ታሕቲ Messages ርአ። ኩሎም ሞዴላት
stream boolean false true እቲ ምላሽ ክጽሓፍ ከሎ ከም server-sent events ይልእኽ። ኩሎም ሞዴላት
max_tokens integer 4096 ናይ ምላሽ ላዕለዋይ ገደብ፣ ብ tokens። ካብ 1 ክሳብ 65,536 ወጻኢ ዝኾነ ዋጋ ናብዚ ወሰን ይእተው። ጠለብ ክሰርሕ ከሎ ካብ ሚዛንካ ዝተነጸለ መጠን እውን እዩ። ኣብ ታሕቲ Output length ርአ። ዝተሃንደሱ 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 Seed ናይ sampler፣ ዝኾነ ምሉእ ቁጽሪ። ብዘይ እዚ፣ seed ካብ ሞዴልን ዘተን ይውሰድ፣ ስለዚ ክልተ ግዜ ዝተላእከ ተመሳሳሊ ጠለብ ተመሳሳሊ seed ይጥቀም። ዝተሃንደሱ open-weight ሞዴላት
stop string | array String ወይ array ናይ strings። ክሳብ 4 ይጥቀሙ። እቲ መልሲ ቅድሚ እቲ ቀዳማይ ዝርከብ ይውዳእ፤ እቲ ናይ stop ጽሑፍ ባዕሉ ኣይምለስን። ዝተሃንደሱ open-weight ሞዴላት
reasoning_effort string high እቲ ሞዴል ቅድሚ ምምላሱ ክሳብ ክንደይ ይሓስብ፦ off፣ low፣ medium ወይ high። none ከምኡውን minimal off ማለት እዩ፣ default medium ማለት እዩ፣ max high ማለት እዩ። ዝኾነ ካልእ ዋጋ 400 ይመልስ። ዝተሃንደሱ open-weight ሞዴላት
reasoning object እቲ ተመሳሳሊ ቅጥዒ ብቅርጺ object፦ {"effort": "low"}። ክልቲኦም ምስ ዝልኣኹ፣ reasoning_effort ይጥቀም። ዝተሃንደሱ open-weight ሞዴላት
tools array እቲ ሞዴል ክጽውዖም ዝኽእል functions፣ ነፍሲ ወከፍ ከም {"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 እቲ ሞዴል ቅድሚ ምምላሱ ኣብ web ክደሊ የኽእሎ። shannon-1.6-*፣ shannon-2-*፣ Shannon 3 ስድራ

ካልኦት ናይ OpenAI fields፣ ከም n፣ user፣ stream_options፣ parallel_tool_calls፣ presence_penalty፣ frequency_penalty፣ logit_bias፣ logprobs፣ metadata፣ store ከምኡውን prompt_cache_key፣ ዘሎ ናይ ክላይንት ኮድ ከይተቐየረ ክሰርሕ ይቕበሉ። ምላሽ ኣይቕይሩን፦ ኩሉ ግዜ ሓደ choice ኣሎ፣ stream ድማ ኩሉ ግዜ ብ usage ይውዳእ።

ጌጋ JSON ዓይነት ዘለዎ field፣ ንኣብነት "max_tokens": "100"፣ 422 ይመልስ። ብዘይ messages ዝኾነ ጠለብ እውን።

Tools፣ ዝተዋቀረ ውጽኢት፣ reasoning ከምኡውን web ድሌት ነፍሲ ወከፎም ናቶም ገጽ ኣለዎም፦ ግብር ጥሪ, የተዋቀረ ውጤት, Reasoning effort, የድር ፍለጋ.

ጠለብ ምስ options

እዚ ጠለብ system መልእኽቲ፣ እቶም sampling fields ከምኡውን 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)

እቲ ምላሽ ከምቲ ላዕሊ ዘሎ ተመሳሳሊ ቅርጺ ኣለዎ። usage ኣብ ዝተሃንደሱ open-weight ሞዴላት ክልተ ዝርዝራት የወስኽ፦ ካብ 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 ዘለዎ object እዩ። content string፣ ወይ እቲ መልእኽቲ ካብ ጽሑፍ ዝበዝሕ ምስ ዝሓዝ array ናይ ክፍልታት እዩ።

ግደ መግለጺ ዝተጠቐመሉ
system መምርሕታት ንሞዴል። ቀዳማይ ኣቐምጥ። ኣብ Shannon ደረጃታት ቀዳማይ system መልእኽቲ እቲ ዝጥቀም እዩ። ዝተሃንደሱ open-weight ሞዴላት፣ shannon-1.6-*፣ shannon-2-*፣ shannon-coder-1
developer ከም system ይነበብ። ዝተሃንደሱ open-weight ሞዴላት
user እትሓትቶ። ኣብ Shannon ደረጃታት ዳሕረዋይ user መልእኽቲ እቲ prompt እዩ እቶም ቅድሚኡ ዘለዉ መልእኽትታት ድማ history እዮም። ኩሎም ሞዴላት
assistant ናይ ሞዴል ዝሓለፉ ምላሻት። ድሕሪኡ ውጽኢት ናይ tool ክትልእኽ ከሎ tool_calls ናቱ ሓዞ። ኩሎም ሞዴላት
tool ውጽኢት ናይ tool ጥሪ፦ tool_call_id id ናይ ጥሪ ይሓዝ content ድማ እቲ ውጽኢት ከም string። ኩሎም ሞዴላት

ምስ id ናይ ስድራ Shannon 3፣ ክሕሉ ዘለዎም መምርሕታት ኣብ user መልእኽቲ ኣእቱ።

ኣብ Shannon ደረጃታት ጠለብ ብዘይ ናይ user ጽሑፍ ከምኡውን ብዘይ tools 400 No user message provided ይመልስ።

ክፍልታት ትሕዝቶ

ክፍሊ መግለጺ ዝርከብሉ
{"type": "text", "text": "…"} ቀሊል ጽሑፍ። ኩሎም ሞዴላት
{"type": "image_url", "image_url": {"url": "…"}} ስእሊ፣ ከም data: URL ምስ base64 ትሕዝቶ ወይ ከም http(s) URL። Shannon 3 ስድራ፣ shannon-1.6-lite፣ shannon-1.6-pro፣ ከምኡውን ስእሊ ኣተዋዕዎ ዝዝርዝሩ ዝተሃንደሱ open-weight ሞዴላት
{"type": "file", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} ሰነድ (PDF፣ Word፣ PowerPoint ወይ Excel)፣ ከም base64 ወይ ብ URL ዝቐርብ። Shannon 3 ስድራ

ዓቐናት፣ ገደባትን ምሉእ ዝርዝር ቅርጽታትን ናቶም ገጽ ኣለዎም። ስእልታትን ፋይላትን

ናይ ምላሽ object

Field ዓይነት መግለጺ
id string chatcmpl- ተኸቲሉ 32 hexadecimal ፊደላት።
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 ምስ ዝጽውዕ ጥራይ ይርከብ። ነፍሲ ወከፍ entry id፣ type function፣ ከምኡውን function ምስ name ከምኡውን arguments ከም JSON string ኣለዎ።
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 እቲ ምላሽ ኣብ ወሰን ውጽኢት ተቖሪጹ። ኣብ streams ናይ shannon-1.6-lite፣ shannon-1.6-pro፣ shannon-coder-1 ከምኡውን ስድራ Shannon 3 ይሕበር።

ዘይ-streamed ምላሽ stop ወይ tool_calls ይሕብር።

ኣጠቓቕማ

Field ዓይነት መግለጺ ዝርከብሉ
usage.prompt_tokens integer ኣተዋዕዎ tokens። ኩሎም ሞዴላት
usage.completion_tokens integer ውጽኢት 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 መልእኽትታትካን ትርጉም ናይ tools ብናይ ሞዴል ባዕሉ 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 member ዘለዎ JSON object እዩ። ምርመራታት ብዚ ትእዛዝ ይግበሩ፦ API ቁልፊ፣ request body፣ ሞዴል 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 ደረጃታት፦ እቲ ጠለብ ናይ user ጽሑፍ የብሉን ከምኡውን tools የብሉን።
400 invalid_request_error <id> does not accept image 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 ጎድሉ፣ ወይ ሓደ field ጌጋ 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 ሞዴላት።