ናብ ትሕዝቶ ዝለል
ፈጣን መጀመር

ፈጣን መጀመር

ቀዳማይ ጠለብ ግበር፦ ቁልፍካ ውሰድ፣ ሓንቲ መልእኽቲ ልኣኽ ከምኡውን ምላሽ ኣንብብ። እቲ API ቅርጺ OpenAI ከምኡውን Anthropic ይዛረብ፣ ስለዚ እቲ ሕጂ ትጥቀመሉ SDK base URL ከምኡውን ቁልፊ ምስ ቀየርካ ይሰርሕ።

1. ቁልፍካ ውሰድ

ነፍሲ ወከፍ ኣካውንት ሓደ API key ኣለዎ። እቶ፣ Keys & usage ክፈት እሞ ቅዳሖ። እቲ ቁልፊ ኣብ ነፍሲ ወከፍ endpoint ከምኡውን ነፍሲ ወከፍ ሞዴል ይሰርሕ። ቁልፍታትን ኣጠቓቕማን

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)
Field ዓይነት ነባሪ መግለጺ
model string እቲ ዝመልስ ሞዴል id። እቲ ids ኣብ Models & pricing ተዘርዚሮም ኣለዉ።
messages array እቲ ክሳብ ሕጂ ዘሎ ዕላል፦ objects ምስ role ከምኡውን content። እቲ ናይ መወዳእታ user መልእኽቲ እቲ prompt እዩ። ዘድሊ።
max_tokens integer 4096 እቲ ናይ ጠለብ output budget፣ ካብ 1 ክሳብ 65,536። እቲ ጠለብ እዚ መጠን ካብ ሚዛንካ የቐምጥ ከምኡውን ብእቲ ብሓቂ ዝተጠቀመሉ ይኽፈል።
stream boolean false true መልሲ ቁራጽ ብቁራጽ ከም ዝጽሓፍ ይልእኽ።

እቲ body ናይ ጠለብ JSON እዩ ከምኡውን header Content-Type: application/json የድልዮ። ምሉእ ዝርዝር field ታት ኣብ ገጽ 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
  }
}
Field ዓይነት መግለጺ
id string chatcmpl- ድሕሪኡ 32 hexadecimal ፊደላት።
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_calls ድማ እቲ ሞዴል tool ምስ ዝጽውዕ።
usage.prompt_tokens integer እቲ ሞዴል ንዚ መልሲ ዝኣንበቦ tokens። ኣብ shannon-2-* ከምኡውን ስድራ Shannon 3 እዚ ካብቲ ዝለኣኽካዮ ጽሑፍ ክበዝሕ ይኽእል።
usage.completion_tokens integer እቲ ሞዴል ዝጸሓፎ tokens።
usage.total_tokens integer እቲ ጠቕላላ። ክፍሊት ናይ Shannon ሞዴል ካብዚ ቁጽሪ ይሰላ።
  • usage ቁጽሪ tokens እዩ ዘለዎ፣ ገንዘብ ኣይኮነን። እቲ ጥሪ ካብ ሚዛንካ ዝወሰዶ ኣብ Keys & usage ንነፍሲ ወከፍ ጠለብ ይርኣይ፤ ኣሰላልኣ ኣብ Limits and balance እዩ። ገደባትን ሚዛንን
  • ኩሉ ምላሽ፣ ጌጋን stream እውን፣ header x-request-id ኣለዎ። ጠለብካ header x-request-id ምስ ዝሕዝ፣ ዋጋኡ ይምለስ፤ እንተ ዘይኮነ ዋጋኡ 12 hexadecimal ፊደላት እዩ። ኣብ 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)

ነፍሲ ወከፍ frame ናይ stream ሓንቲ መስመር እያ፣ ብ 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 ሰከንድ ትመጽእ። ርእይቶ እያ ነቲ ርክብ ክፉት ትሕዝ፤ SSE clients የሕልፍዋ።
  • stream ድሕሪ ምክፋቱ ዝመጽእ ውድቀት ከም frame data: {"error": {…}} ይመጽእ። እቲ status 200 ይተርፍ፣ ስለዚ frames ርአ።

ስትሪም

እቲ ጥሪ እንተ ወዲቑ

ጌጋ ሓደ error ዘለዎ JSON object እዩ፣ እቲ type ከምኡውን message ዝሕዝ። እዚኣቶም ቀዳማይ ጥሪ ብዙሕ ግዜ ዝረኽቦም ምላሻት እዮም።

ኩነታት ዓይነት መልእኽቲ እንታይ ማለት እዩ
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… ሓደ field ጌጋ ዓይነት JSON ኣለዎ፣ ወይ messages ጎደሎ እዩ።
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan ናይ ጠለብ output budget ኣብ ሚዛንካ ኣይሽፈንን።

ሓጋይ ኣስተዳደር

ናበይ ክትቅጽል

  • ሞዴላትን ዋጋን — ሞዴል ምረጽ፦ ids፣ context windows ከምኡውን ዋጋታት።
  • Chat Completions — ነፍሲ ወከፍ ጠለብ field፣ ምላሽ field ከምኡውን stream event ናይቲ ዝጸዋዕካዮ endpoint።
  • ስትሪም — Frames ናይ stream፣ keep-alive መስመራትን ጌጋታትን ውሽጢ stream።
  • ግብር ጥሪ — እቲ ሞዴል functions ናትካ ይጸውዕ።
  • ገደባትን ሚዛንን — እንታይ ጠለብ ከም ዝሕዝን ከም ዘኽፍልን፣ ከምኡውን ክንደይ ጠለባት ክትልእኽ ከም ዝትኽእል።
  • API Playground — ጠለባት ኣብ browser ምስ ቁልፍካ ፈትን።