کتنه

د API نقشه: هر endpoint، غوښتنه او تېروتنه څنګه ښکاري، calls څنګه تادیه کیږي، او کله چې د 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 هیڅ حالت نه ساتي: ګفتګه له هرې غوښتنې سره ولیږئ.
`GET /v1/models`	د OpenAI ماډلونو لیست	ماډلونه د context window، نرخونو او وړتیاوو سره لیست کړئ. کیلي ته اړتیا نشته.
`POST /v1/tokenize`	Shannon API	د متن یا چیټ غوښتنې ټوکنونه د کوربه شوي open-weight ماډل لپاره وشمیرئ. وړیا.
`POST /v1/messages/count_tokens`	د Anthropic د ټوکنونو شمېرنه	د کوربه شوي open-weight ماډل لپاره د Messages غوښتنې input ټوکنونه وشمیرئ. وړیا.

درې endpoints چې متن جوړوي همدا ماډلونو ته رسیږي. هغه غوره کړئ چې بڼه یې ستاسو کوډ لا دمخه کاروي.

د غوښتنې بنسټونه

Header	تشریح
`Authorization: Bearer <key>`	ستاسو API کیلي. په هر endpoint کې اړینه ده پرته له `GET /v1/models`، مګر دا چې تاسو `x-api-key` ولیږئ.
`x-api-key: <key>`	هماغه کیلي په هغه header کې چې Anthropic SDKs یې لیږي. په هر endpoint کې لوستل کیږي.
`Content-Type: application/json`	په هر `POST` کې اړین. پرته له هغه ځواب `415` دی.
`x-request-id: <your id>`	اختیاري. د غوښتنې لپاره ستاسو خپل id؛ دا په ځواب header `x-request-id` کې بیرته راځي. پرته له هغه API د 12 هیکساډیسیمل توریو یو id جوړوي.

د هر POST بدنه یو JSON څیز دی، تر 32 MiB پورې.
هغه ساحه چې API یې نه پېژني تېروتنه نه رامنځته کوي او اغېز نه لري. هغه غوښتنه چې د بل provider لپاره لیکل شوې د اضافي ساحې له امله ناکامه نه کیږي.
پېژندل شوې ساحه چې د JSON غلط ډول ولري، یا اړینه ساحه چې نشته، په 422 ځواب کیږي. هغه بدنه چې معتبره JSON نه وي په 400 ځواب کیږي.
model د Models & pricing د id ګانو څخه یو دی. لوی او کوچني توري مهم نه دي.

ځواب JSON دی، یا د server-sent events stream کله چې غوښتنه stream په true ټاکي. هر endpoint په خپله بڼه ځواب ورکوي. هر ځواب header x-request-id لري.

غوښتنه کوم چکونه تیروي

غوښتنه مخکې له دې چې ماډل وچلیږي په ټاکلي ترتیب چک کیږي. لومړی چک چې ناکام شي ځواب ورکوي، نو 401 تاسو ته تر اوسه د بدنې په اړه هیڅ نه وايي.

چک شوی، په دې ترتیب	کله ناکام شي حالت
API کیلي	`401`
بدنه: اندازه، د منځپانګې ډول، JSON، د ساحو ډولونه	`413 · 415 · 400 · 422`
د ماډل id	`400`
Flood protection: په هر حساب کې په دقیقه 120 غوښتنې	`429`
بیلانس: د غوښتنې output بودجه باید ځای شي	`429`

د تېروتنې بڼه

تېروتنه د JSON څیز دی چې error لري چې type او message سره. /v1/messages دا هغسې تاوه کوي لکه Anthropic SDKs چې تمه کوي؛ هر بل مسیر د OpenAI بڼه کاروي.

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

type او message ولولئ. code او param یوازې په ځینو تېروتنو کې شتون لري: دوی اختیاري وګڼئ. param تل null دی.
وروسته له دې چې stream پیل شي، حالت لا دمخه 200 دی. ناکامي بیا د stream دننه د error frame په توګه رارسیږي.
د تېروتنې هر ځواب header x-request-id لري.

حالت	ډول	کله
`400`	`invalid_request_error`	بدنه معتبره JSON نه ده، د ماډل id نامعلوم دی، یا ماډل هغه ډول input نه مني چې تاسو لیږلی.
`401`	`authentication_error`	کیلي نشته یا معتبره نه ده.
`404`	`not_found_error`	لاره نشته.
`405`	`api_error`	لاره شتون لري، میتود غلط دی.
`413`	`invalid_request_error`	بدنه له 32 MiB لویه ده.
`415`	`invalid_request_error`	`Content-Type` `application/json` نه دی.
`422`	`invalid_request_error`	یوه ساحه د JSON غلط ډول لري یا اړینه ساحه نشته.
`429`	`rate_limit_error`	بیلانس غوښتنه نه پوښي، په یوه دقیقه کې له 120 زیاتې غوښتنې رسیدلې، د کړکۍ Shannon Coder calls ختم شوي، یا ماډل بوخت دی. پیغام وايي کوم یو.
`5xx`	`api_error`	حالت `500`، `502`، `503` یا `504`: غوښتنه معتبره وه او ځواب نشو ورکول کیدی. بیا یې ولیږئ. `500` کولی شي ډول `server_error` ولري.

د تېروتنې اداره کول

بیلینګ او بیلانس

د هر حساب لپاره یو بیلانس شته، او چیټ او API یې شریکوي: لومړی د نن ورځې د پلان اجازه، بیا اخیستل شوی کریډیټ. API خپله کوټه نه لري.
غوښتنه خپله output بودجه (max_tokens، ډیفالټ 4,096) ساتي او بیا د هغو ټوکنونو لپاره بیل کیږي چې ریښتیا یې کارولي، د ماډل په نرخ.
هر ځواب خپلې د ټوکنونو شمیرې په usage کې راپور کوي. د Keys & usage پاڼه بیلانس او دا ښیي چې هرې غوښتنې څومره لګښت درلود.
هره غوښتنه برابره خدمت کیږي. د غوښتنو په کچه یوازینی حد flood protection دی: په هر حساب کې په دقیقه 120 غوښتنې. هغه غوښتنې چې موازي لیږل کیږي په صف کې انتظار کوي.

حدونه او بیلانس ماډلونه او بیې کیلي او کارونه

هغه ساحې چې د ماډل پورې اړه لري

هر ماډل هماغه غوښتنه مني. یو څو ساحې یوازې په ځینو ماډلونو اغېز کوي؛ جدول نوموي چیرته. د endpoint پاڼې هره ساحه لیست کوي.

ساحه	تشریح	پلي کوونکی
`system`	ماډل ته لارښوونې: په Chat Completions کې `system` message، په 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`	ماډل مخکې له ځواب ورکولو څومره reasoning کوي. په Responses کې `reasoning.effort`، په Messages کې `thinking`.	کوربه شوي open-weight ماډلونه
`web_search`	`true` ماډل ته اجازه ورکوي چې د دې غوښتنې لپاره په ویب کې ولټوي. د دې API ساحه، په Chat Completions او Messages کې.	د Shannon ماډلونه پرته له `shannon-coder-1`
`max_tokens`	د output بودجه. په هر ماډل کې دا هغه مقدار ټاکي چې ستاسو له بیلانس ساتل کیږي.	د ځواب د اوږدوالي د حد په توګه: کوربه شوي open-weight ماډلونه، `shannon-1.6-*`، `shannon-coder-1`

Chat Completions

د OpenAI SDK څخه راتلل

base URL په https://api.shannon-ai.com/v1 وټاکئ او کیلي ستاسو د Shannon کیلي ته. بیا Chat Completions او Responses calls له SDK سره هماغسې کار کوي.
model باید د Shannon id وي. د بل provider د ماډل نوم، لکه gpt-4o، په 400 او unknown model ځواب کیږي.
Reasoning په جلا ساحه کې راځي: reasoning_content د content تر څنګ، په message او په stream deltas کې.
Stream تل په خپل وروستي chunk کې usage لري، د finish_reason سره یوځای.
په stream کې tool call د یوه chunk په توګه د بشپړ arguments string سره رارسیږي.
ځواب یو choice لري.
د OpenAI API هغه لارې چې په پورتني جدول کې نشته، لکه /v1/embeddings، په 404 ځواب کیږي.

د Anthropic SDK څخه راتلل

base URL په https://api.shannon-ai.com وټاکئ، پرته له /v1، او کیلي ستاسو د Shannon کیلي ته. SDK یې د x-api-key په توګه لیږي.
model باید د Shannon id وي.
max_tokens پدې API کې اختیاري دی. ډیفالټ یې 4,096 دی.
ځواب د ډول thinking، text او tool_use منځپانګې 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": {…}}.

د کوډ لیکلو tools چې دا بڼې خبرې کوي په همدې ډول جوړیږي: base URL، کیلي، او د Shannon id د ماډل په توګه. د CLI کوډ لیکلو وسیلې