Têkilî

نەخشەی API: هەموو endpoint ێک، داواکاری و هەڵە چۆن دەردەکەون، بانگکردنەکان چۆن نرخیان دەگیرێت، و ئەوەی دەبێت بیزانیت کاتێک لە SDK ی OpenAI یان Anthropic ەوە دێیت.

Endpoint ـەکان

هەموو endpoint ێک لەژێر یەک base URL دایە و بە HTTPS خزمەت دەکرێت.

Base URL

https://api.shannon-ai.com

Endpoint	فۆرمات	بۆ چی بەکاردێت
`POST /v1/chat/completions`	OpenAI Chat Completions	گفتوگۆیەک بنێرە، وەڵامی دواتر وەربگرە. بە stream یان بەبێ.
`POST /v1/messages`	Anthropic Messages	هەمان شت، بە شێوەی داواکاری و وەڵامی SDK ـەکانی Anthropic.
`POST /v1/responses`	OpenAI Responses	هەمان شت، بە شێوەی Responses. endpoint ـەکە هیچ state ێک ناهێڵێتەوە: گفتوگۆکە لەگەڵ هەر داواکارییەک بنێرە.
`GET /v1/models`	لیستی مۆدێلەکانی OpenAI	مۆدێلەکان لیست بکە لەگەڵ context window، نرخ و تواناکان. پێویستی بە کلیل نییە.
`POST /v1/tokenize`	Shannon API	تۆکنەکانی دەقێک یان داواکارییەکی chat بۆ مۆدێلێکی open-weight ی میوانداریکراو هەژمار بکە. بێبەرامبەر.
`POST /v1/messages/count_tokens`	هەژمارکردنی تۆکنی Anthropic	تۆکنەکانی input ی داواکارییەکی Messages بۆ مۆدێلێکی open-weight ی میوانداریکراو هەژمار بکە. بێبەرامبەر.

ئەو سێ endpoint ـەی دەق دروست دەکەن هەمان مۆدێلەکان بەکاردەهێنن. ئەوە هەڵبژێرە کە فۆرماتەکەی کۆدەکەت پێشتر بەکاری دەهێنێت.

بنەماکانی داواکاری

Header	وەسف
`Authorization: Bearer <key>`	کلیلی API ـەکەت. لەسەر هەموو endpoint ێک پێویستە جگە لە `GET /v1/models`، مەگەر `x-api-key` بنێریت.
`x-api-key: <key>`	هەمان کلیل لەو header ـەدا کە SDK ـەکانی Anthropic دەینێرن. لەسەر هەموو endpoint ێک دەخوێنرێتەوە.
`Content-Type: application/json`	لەسەر هەموو `POST` ێک پێویستە. بەبێ ئەوە وەڵامەکە `415` ە.
`x-request-id: <your id>`	ئارەزوومەندانە. id ی خۆت بۆ داواکارییەکە؛ لە header ی وەڵامی `x-request-id` دا دەگەڕێتەوە. بەبێ ئەوە API یەکێک دروست دەکات لە 12 پیتی هەژدەیی.

body ی هەموو POST ێک یەک ئۆبجێکتی JSON ە، تا 32 MiB.
بوارێک کە API نایناسێت هیچ هەڵەیەک دروست ناکات و هیچ کاریگەرییەکی نییە. داواکارییەک کە بۆ provider ێکی دیکە نووسراوە بەهۆی بوارێکی زیادەوە شکست ناخوات.
بوارێکی ناسراو بە جۆری JSON ی هەڵە، یان بوارێکی پێویستی ون، بە 422 وەڵام دەدرێتەوە. body ێک کە JSON ی دروست نییە بە 400 وەڵام دەدرێتەوە.
model یەکێکە لە id ـەکانی Models & pricing. پیتی گەورە و بچووک گرنگ نین.

وەڵام JSON ە، یان stream ی server-sent events کاتێک داواکارییەکە stream دادەنێت بە true. هەر endpoint ێک بە فۆرماتی خۆی وەڵام دەداتەوە. هەموو وەڵامێک header ی x-request-id ی هەیە.

داواکارییەک بە چی تێدەپەڕێت

داواکارییەک بە ڕیزبەندییەکی جێگیر دەپشکنرێت پێش ئەوەی مۆدێلێک کار بکات. یەکەم پشکنین کە شکست بخوات وەڵام دەداتەوە، بۆیە 401 هێشتا هیچ دەربارەی body پێت ناڵێت.

دەپشکنرێت، بەم ڕیزبەندییە	Status کاتێک شکست دەخوات
کلیلی API	`401`
Body: قەبارە، جۆری ناوەڕۆک، JSON، جۆری بوارەکان	`413 · 415 · 400 · 422`
id ی مۆدێل	`400`
Flood protection: 120 داواکاری لە خولەکێکدا بۆ هەر هەژمارێک	`429`
باڵانس: بودجەی output ی داواکارییەکە دەبێت بگونجێت	`429`

شێوەی هەڵە

هەڵە ئۆبجێکتێکی JSON ە بە error ێک کە type و message هەڵدەگرێت. /v1/messages بەو شێوەیە دەیپێچێتەوە کە SDK ـەکانی Anthropic چاوەڕێی دەکەن؛ هەموو ڕێگایەکی دیکە شێوەی 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، status پێشتر 200 ە. شکستێک ئەو کات وەک frame ی هەڵە لەناو stream دا دێت.
هەر وەڵامێکی هەڵە header ی x-request-id هەڵدەگرێت.

دۆخ	جۆر	کەی
`400`	`invalid_request_error`	body ی JSON ی دروست نییە، id ی مۆدێل نەناسراوە، یان مۆدێلەکە جۆرێک input وەرناگرێت کە تۆ ناردووتە.
`401`	`authentication_error`	کلیلەکە نییە یان دروست نییە.
`404`	`not_found_error`	ڕێگاکە بوونی نییە.
`405`	`api_error`	ڕێگاکە هەیە، شێوازەکە هەڵەیە.
`413`	`invalid_request_error`	body لە 32 MiB گەورەترە.
`415`	`invalid_request_error`	`Content-Type` `application/json` نییە.
`422`	`invalid_request_error`	بوارێک جۆری JSON ی هەڵەیە یان بوارێکی پێویست نییە.
`429`	`rate_limit_error`	باڵانس داواکارییەکە ناگرێتەوە، زیاتر لە 120 داواکاری لە خولەکێکدا گەیشتن، بانگکردنەکانی Shannon Coder ی پەنجەرەکە تەواو بوون، یان مۆدێلەکە ماندووە. پەیامەکە دەڵێت کامیان.
`5xx`	`api_error`	Status ی `500`، `502`، `503` یان `504`: داواکارییەکە دروست بوو و نەتوانرا وەڵام بدرێتەوە. دووبارە بینێرە. `500` دەتوانێت جۆری `server_error` هەڵبگرێت.

Çewtî

نرخگرتن و باڵانس

بۆ هەر هەژمارێک یەک باڵانس هەیە، و chat و API هاوبەشن تێیدا: سەرەتا ڕێپێدانی پلانی ئەمڕۆ، پاشان کرێدیتی کڕدراو. API quota ی تایبەتی خۆی نییە.
داواکارییەک بودجەی output ی خۆی ڕادەگرێت (max_tokens، بنەڕەتی 4,096) و پاشان نرخی ئەو تۆکنانە دەگیرێت کە بەڕاستی بەکاری هێناون، بە نرخی مۆدێلەکە.
هەر وەڵامێک ژمارەی تۆکنەکانی لە usage ڕاپۆرت دەکات. لاپەڕەی Keys & usage باڵانس و تێچووی هەر داواکارییەک نیشان دەدات.
هەموو داواکارییەک یەکسان خزمەت دەکرێت. تەنها سنوورێک لەسەر ڕێژەی داواکاری flood protection ە: 120 داواکاری لە خولەکێکدا بۆ هەر هەژمارێک. ئەو داواکارییانەی بە پاڕالێل دەنێردرێن لە ڕیزدا چاوەڕێ دەکەن.

سنوور و باڵانس مۆدێل و نرخ Keys & usage

ئەو بوارانەی بەندن بە مۆدێلەوە

هەموو مۆدێلێک هەمان داواکاری وەردەگرێت. چەند بوارێک تەنها لەسەر هەندێک مۆدێل کاریگەرییان هەیە؛ خشتەکە دەڵێت لە کوێ. لاپەڕەکانی endpoint هەموو بوارێک لیست دەکەن.

بوار	وەسف	جێبەجێکراو لەلایەن
`system`	ڕێنمایی بۆ مۆدێلەکە: نامەی `system` لە Chat Completions، `system` لە Messages، `instructions` لە Responses.	مۆدێلە open-weight ـە میوانداریکراوەکان، `shannon-1.6-`، `shannon-2-`، `shannon-coder-1`
`temperature`	تەمپەرچەری sampling.	مۆدێلە open-weight ـە میوانداریکراوەکان، `shannon-1.6-*`، `shannon-coder-1`
`top_p`	Nucleus sampling.	مۆدێلە open-weight ـە میوانداریکراوەکان
`seed`	seed ێکی جێگیر بۆ sampling.	مۆدێلە open-weight ـە میوانداریکراوەکان
`stop`	تا 4 ڕیزبەندی وەستان.	مۆدێلە open-weight ـە میوانداریکراوەکان
`reasoning_effort`	مۆدێلەکە چەند بیرکردنەوە دەکات پێش وەڵامدانەوە. `reasoning.effort` لە Responses، `thinking` لە Messages.	مۆدێلە 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

کاتێک لە SDK ی OpenAI ەوە دێیت

base URL بکە بە https://api.shannon-ai.com/v1 و کلیلەکە بە کلیلی Shannon ـەکەت. ئەو کات بانگکردنەکانی Chat Completions و Responses لەگەڵ SDK ـەکە وەک خۆی کار دەکەن.
model دەبێت id ی Shannon بێت. ناوی مۆدێلی provider ێکی دیکە، وەک gpt-4o، بە 400 و unknown model وەڵام دەدرێتەوە.
بیرکردنەوە لە بوارێکی تایبەتدا دێت: reasoning_content لەتەنیشت content، لە نامەکەدا و لە delta ـەکانی stream دا.
stream هەمیشە usage لە دوایین chunk ـەکەیدا هەڵدەگرێت، لەگەڵ finish_reason.
بانگکردنی ئامراز لە stream دا وەک یەک chunk دەگات لەگەڵ string ی arguments ی تەواو.
وەڵامێک یەک choice ی هەیە.
ئەو ڕێگایانەی API ی OpenAI کە لە خشتەی سەرەوەدا نین، وەک /v1/embeddings، بە 404 وەڵام دەدرێنەوە.

کاتێک لە SDK ی Anthropic ەوە دێیت

base URL بکە بە https://api.shannon-ai.com، بەبێ /v1، و کلیلەکە بە کلیلی Shannon ـەکەت. SDK ـەکە وەک x-api-key دەینێرێت.
model دەبێت id ی Shannon بێت.
max_tokens لەسەر ئەم API ـە ئارەزوومەندانەیە. بنەڕەتییەکەی 4,096 ە.
وەڵامێک بلۆکی ناوەڕۆک هەڵدەگرێت بە جۆری thinking، text و tool_use. یەکەم بلۆک هەمیشە دەق نییە: بلۆکەکان بەپێی type هەڵبژێرە.
stop_reason end_turn یان tool_use ە. stream ی مۆدێلێکی Shannon دەتوانێت بە max_tokens یش کۆتایی بێت.
anthropic-version و anthropic-beta وەردەگیرێن، بۆیە SDK بێ گۆڕان کار دەکات. داواکارییەک پێویستی پێیان نییە.
هەڵەکانی /v1/messages شێوەی Anthropic یان هەیە: {"type": "error", "error": {…}}.

ئامرازەکانی کۆدکردن کە ئەم فۆرماتانە بەکاردەهێنن بە هەمان شێوە ڕێک دەخرێن: base URL، کلیل، و id ی Shannon وەک مۆدێل. ئامرازەکانی کۆدنووسینی CLI