ወደ ይዘቱ እለፍ
ፈጣን መጀመሪያ

ፈጣን መጀመሪያ

የመጀመሪያ ጥያቄ ያድርጉ፦ ቁልፍዎን ያግኙ፣ አንድ መልእክት ይላኩ እና ምላሹን ያንብቡ። API የOpenAI እና የAnthropic ፎርማቶችን ይናገራል፣ ስለዚህ አስቀድመው የሚጠቀሙበት SDK base URL እና ቁልፉን ከቀየሩ በኋላ ይሰራል።

1. ቁልፍዎን ያግኙ

እያንዳንዱ መለያ አንድ API ቁልፍ አለው። ይግቡ፣ Keys & usage ን ይክፈቱ እና ይቅዱት። ቁልፉ በእያንዳንዱ endpoint እና በእያንዳንዱ ሞዴል ላይ ይሰራል። Keys & usage

2. client ዎን ወደ API ያመልክቱ

ሁሉም endpoints በአንድ base URL ስር ይገኛሉ። የOpenAI SDK መጨረሻው ላይ /v1 ይዞ ይቀበለዋል፤ የAnthropic SDK ያለ እሱ ይቀበለዋል፣ ምክንያቱም /v1/messages ራሱ ይጨምራል።

Client Base URL
OpenAI SDKs እና OpenAI-ተኳሃኝ clients https://api.shannon-ai.com/v1
Anthropic SDKs https://api.shannon-ai.com

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

ኤንድ-ፖይንት (Endpoint) ፎርማት
POST /v1/chat/completions OpenAI Chat Completions
POST /v1/messages Anthropic Messages
POST /v1/responses OpenAI Responses

3. የመጀመሪያ ጥያቄ ይላኩ

በChat Completions endpoint ላይ አንድ user መልእክት ወደ shannon-3 ይላኩ። YOUR_API_KEY ን በቁልፍዎ ይተኩ።

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

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": "Hello, Shannon!"}
    ],
    max_tokens=1024
)

print(response.choices[0].message.content)
መስክ ዓይነት ነባሪ መግለጫ
model string የሚመልሰው ሞዴል id። id ዎቹ በModels & pricing ላይ ተዘርዝረዋል።
messages array እስካሁን ያለው ውይይት፦ role እና content ያላቸው objects። የመጨረሻው user መልእክት prompt ነው። ግዴታ።
max_tokens integer 4096 የጥያቄው የውጤት በጀት፣ ከ1 እስከ 65,536። ጥያቄው ይህን መጠን ከቀሪ ሂሳብዎ ይይዛል እና በእውነት ለተጠቀመበት ይከፈላል።
stream boolean false true መልሱ ሲጻፍ ቁራጭ በቁራጭ ይልካል።

የጥያቄው body JSON ነው እና Content-Type: application/json header ያስፈልገዋል። የመስኮቹ ሙሉ ዝርዝር በendpoint ገጽ ላይ ነው። Chat Completions

ምላሹ

ያለ stream የተደረገ ጥሪ መልሱ ሲጠናቀቅ አንድ JSON object ይመልሳል። ከታች ያሉት ጽሑፎችና ቁጥሮች ምሳሌዎች ናቸው።

200 JSON 
{
  "id": "chatcmpl-9b2f6c1e4a7d4f0f8a3c5d2e1b6a7c90",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! What would you like to work on?",
        "reasoning_content": "A greeting. A short, friendly reply fits."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1386,
    "completion_tokens": 74,
    "total_tokens": 1460
  }
}
መስክ ዓይነት መግለጫ
id string chatcmpl- እና ከዚያ 32 የሄክሳዴሲማል ቁምፊዎች።
object string ሁልጊዜ chat.completion።
created integer የምላሹ ጊዜ በUnix ሰከንዶች።
model string የመለሰው ሞዴል የታተመ id፣ alias ወይም ሌላ አጻጻፍ ቢልኩም።
choices array ሁልጊዜ አንድ ግቤት፣ index 0 ያለው።
choices[0].message.role string ሁልጊዜ assistant።
choices[0].message.content string | null መልሱ። ምላሹ tool_calls ሲይዝ null ሊሆን ይችላል።
choices[0].message.reasoning_content string | null ሞዴሉ ከመልሱ በፊት ያደረገው reasoning፣ ወይም ምንም ከሌለ null።
choices[0].message.tool_calls array ሞዴሉ ካወጁት tools አንዱን ሲጠራ ብቻ ይገኛል።
choices[0].finish_reason string ለመልስ stop፣ ሞዴሉ tool ሲጠራ tool_calls።
usage.prompt_tokens integer ሞዴሉ ለዚህ መልስ ያነበባቸው tokens። በshannon-2-* እና በShannon 3 ቤተሰብ ላይ ይህ ከላኩት ጽሑፍ ሊበልጥ ይችላል።
usage.completion_tokens integer ሞዴሉ የጻፈባቸው tokens።
usage.total_tokens integer ድምሩ። የShannon ሞዴል ክፍያ የሚሰላው ከዚህ ቁጥር ነው።
  • usage የtoken ቆጠራ ይይዛል እንጂ ገንዘብ አይደለም። ጥሪው ከቀሪ ሂሳብዎ ምን እንደወሰደ በKeys & usage ላይ በየጥያቄው ይታያል፤ እንዴት እንደሚሰላ በ ገደቦች እና ቀሪ ሂሳብ ገጽ ላይ ነው። ገደቦች እና ቀሪ ሂሳብ
  • እያንዳንዱ ምላሽ፣ ስህተትና stream ጭምር፣ x-request-id header አለው። ጥያቄዎ x-request-id header ከያዘ እሴቱ ይመለሳል፤ ካልሆነ እሴቱ 12 የሄክሳዴሲማል ቁምፊዎች ነው። በlogs ውስጥ ያስቀምጡት፦ ይህን አንድ ጥያቄ ይሰይማል።

ተመሳሳዩ ጥሪ እንደ stream

መልሱ ሲጻፍ ለማንበብ streamን ወደ true ያዘጋጁ። በጥያቄው ውስጥ ሌላው ሁሉ አይቀየርም።

from openai import OpenAI

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

stream = client.chat.completions.create(
    model="shannon-3",
    messages=[
        {"role": "user", "content": "Hello, Shannon!"}
    ],
    max_tokens=1024,
    stream=True
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

የstream እያንዳንዱ frame በdata: የሚጀምር እና JSON object የያዘ አንድ መስመር ነው። አንድ frame፣ በበርካታ መስመሮች የታተመ፦

አንድ frame 
{
  "id": "chatcmpl-9b2f6c1e4a7d4f0f8a3c5d2e1b6a7c90",
  "object": "chat.completion.chunk",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "Hello! "
      },
      "finish_reason": null
    }
  ]
}
Frames፣ በቅደም ተከተል delta finish_reason
ሞዴሉ በሚያስብበት ጊዜ። ዜሮ ወይም ከዚያ በላይ frames። {"reasoning_content": "…"} null
መልሱ፣ ቁራጭ በቁራጭ። ዜሮ ወይም ከዚያ በላይ frames። {"content": "…"} null
የመጨረሻው JSON frame። usageንም ይይዛል፤ መጠየቅ አያስፈልግዎትም። {} "stop"
የstream መጨረሻ፦ መስመሩ data: [DONE]።
  • ምላሹ status 200 እና content-type: text/event-stream አለው። እያንዳንዱ frame data: <json> መስመር እና ከዚያ ባዶ መስመር ነው።
  • መስመር : ping በየ15 ሰከንዱ ይደርሳል። ግንኙነቱን ክፍት የሚያደርግ comment ነው፤ SSE clients ይዘለሉታል።
  • stream ከተከፈተ በኋላ የሚከሰት ብልሽት እንደ frame data: {"error": {…}} ይመጣል። status 200 ሆኖ ይቆያል፣ ስለዚህ frames ን ይመርምሩ።

ስትሪሚንግ

ጥሪው ቢከሽፍ

ስህተት type እና message የያዘ error ያለው JSON object ነው። የመጀመሪያ ጥሪ ብዙ ጊዜ የሚያጋጥማቸው ምላሾች እነዚህ ናቸው።

ሁኔታ ዓይነት መልእክት ምን ማለት ነው
401 authentication_error Missing authentication ምንም ቁልፍ ወደ API አልደረሰም። Authorization: Bearer እና ከዚያ ቁልፍዎን ይላኩ።
401 authentication_error Invalid API key ቁልፉ የመለያ የአሁኑ ቁልፍ አይደለም። ከKeys & usage እንደገና ይቅዱት።
400 invalid_request_error unknown model: <id> model የታተመ id አይደለም። ከModels & pricing id ይጠቀሙ።
422 invalid_request_error Failed to deserialize the JSON body into the target type… መስክ የተሳሳተ JSON አይነት አለው፣ ወይም messages ይጎድላል።
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan የጥያቄው የውጤት በጀት በቀሪ ሂሳብዎ ውስጥ አይገባም።

ስህተት አስተዳደር

ቀጥሎ የት መሄድ

  • ሞዴሎችና ዋጋ — ሞዴል ይምረጡ፦ id ዎች፣ context windows እና ዋጋዎች።
  • Chat Completions — የጠሩት endpoint እያንዳንዱ የጥያቄ መስክ፣ የምላሽ መስክ እና stream event።
  • ስትሪሚንግ — የstream frames፣ keep-alive መስመሮች እና በstream ውስጥ ያሉ ስህተቶች።
  • ፋንክሽን ጥራት — ሞዴሉ የእርስዎን functions እንዲጠራ ያድርጉ።
  • ገደቦች እና ቀሪ ሂሳብ — ጥያቄ ምን እንደሚይዝና እንደሚያስከፍል፣ እና ስንት ጥያቄዎች መላክ እንደሚችሉ።
  • API Playground — ጥያቄዎችን በብሮውዘር ውስጥ በቁልፍዎ ይሞክሩ።