نظرة عامة

خريطة API: كل نقطة نهاية، وكيف يبدو الطلب والخطأ، وكيف تُدفع تكلفة المكالمات، وما ينبغي معرفته عند القدوم من OpenAI SDK أو Anthropic SDK.

نقاط النهاية

كل نقطة نهاية تقع تحت base URL واحد وتُخدَّم عبر HTTPS.

Base URL

https://api.shannon-ai.com

نقطة النهاية (Endpoint)	الصيغة	فيم يُستخدم
`POST /v1/chat/completions`	OpenAI Chat Completions	أرسل محادثة، واحصل على الإجابة التالية. مع البث أو بدونه.
`POST /v1/messages`	Anthropic Messages	الشيء نفسه، بأشكال الطلب والرد في Anthropic SDKs.
`POST /v1/responses`	OpenAI Responses	الشيء نفسه، بأشكال Responses. لا تحتفظ نقطة النهاية بأي حالة: أرسل المحادثة مع كل طلب.
`GET /v1/models`	قائمة نماذج OpenAI	سرد النماذج مع نافذة السياق والأسعار والإمكانات. لا يحتاج إلى مفتاح.
`POST /v1/tokenize`	Shannon API	عدّ tokens نص أو طلب دردشة لنموذج مفتوح الأوزان مستضاف. مجاني.
`POST /v1/messages/count_tokens`	عدّ tokens بصيغة Anthropic	عدّ tokens المدخلات في طلب Messages لنموذج مفتوح الأوزان مستضاف. مجاني.

نقاط النهاية الثلاث التي تنتج النصوص تصل إلى النماذج نفسها. اختر النقطة التي يستخدم كودك صيغتها أصلاً.

أساسيات الطلب

الترويسة	الوصف
`Authorization: Bearer <key>`	مفتاح API الخاص بك. مطلوب في كل نقطة نهاية عدا `GET /v1/models`، ما لم ترسل `x-api-key`.
`x-api-key: <key>`	المفتاح نفسه في الترويسة التي ترسلها Anthropic SDKs. يُقرأ في كل نقطة نهاية.
`Content-Type: application/json`	مطلوب في كل `POST`. وبدونه يكون الرد `415`.
`x-request-id: <your id>`	اختياري. معرّفك الخاص للطلب؛ ويعود في ترويسة الرد `x-request-id`. وبدونه تنشئ API معرّفاً من 12 حرفاً سداسياً عشرياً.

نص كل POST كائن JSON واحد، حتى 32 MiB.
الحقل الذي لا تعرفه API لا يسبب خطأً ولا أثر له. والطلب المكتوب لمزوّد آخر لا يفشل بسبب حقل زائد.
الحقل المعروف بنوع JSON خاطئ، أو الحقل المطلوب المفقود، يُجاب عنه بـ 422. والنص الذي ليس JSON صالحاً يُجاب عنه بـ 400.
model هو أحد المعرّفات في Models & pricing. ولا فرق بين الأحرف الكبيرة والصغيرة.

الرد إما JSON، أو بث من أحداث يرسلها الخادم (server-sent events) عندما يضبط الطلب stream على true. وتجيب كل نقطة نهاية بصيغتها الخاصة. ولكل رد الترويسة x-request-id.

ما يمر به الطلب

يُفحص الطلب بترتيب ثابت قبل أن يعمل أي نموذج. وأول فحص يفشل هو الذي يجيب، ولذلك لا يخبرك 401 شيئاً بعد عن النص.

ما يُفحص، بهذا الترتيب	الحالة عند الفشل
مفتاح API	`401`
النص: الحجم ونوع المحتوى وJSON وأنواع الحقول	`413 · 415 · 400 · 422`
معرّف النموذج	`400`
الحماية من الإغراق: 120 طلباً في الدقيقة لكل حساب	`429`
الرصيد: يجب أن تتسع ميزانية مخرجات الطلب	`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.
بعد أن يبدأ البث تكون الحالة قد صارت 200. ويصل الفشل عندئذٍ كإطار خطأ داخل البث.
يحمل كل رد خطأ الترويسة x-request-id.

الحالة	النوع	متى
`400`	`invalid_request_error`	النص ليس JSON صالحاً، أو معرّف النموذج غير معروف، أو أن النموذج لا يقبل نوعاً من المدخلات أرسلته.
`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 في النافذة، أو أن النموذج مشغول. وتذكر الرسالة السبب.
`5xx`	`api_error`	الحالة `500` أو `502` أو `503` أو `504`: كان الطلب صالحاً وتعذر الرد عليه. أعد إرساله. وقد يحمل `500` النوع `server_error`.

معالجة الأخطاء

الفواتير والرصيد

يوجد رصيد واحد لكل حساب، تتشاركه الدردشة وAPI: مخصصات الخطة لليوم أولاً، ثم الرصيد المشتري. وليس لـ API حصة خاصة بها.
يحجز الطلب ميزانية مخرجاته (max_tokens، والافتراضي 4,096) ثم يُحاسَب على الـ tokens التي استخدمها فعلاً، بسعر النموذج.
يبلغ كل رد عن عدد الـ tokens في usage. وتعرض صفحة Keys & usage الرصيد وتكلفة كل طلب.
كل طلب يُخدَّم بالتساوي. والحد الوحيد على معدل الطلبات هو الحماية من الإغراق: 120 طلباً في الدقيقة لكل حساب. والطلبات المرسلة بالتوازي تنتظر في الطابور.

الحدود والرصيد النماذج والأسعار المفاتيح والاستخدام

الحقول التي تعتمد على النموذج

كل نموذج يقبل الطلب نفسه. وبعض الحقول تؤثر في بعض النماذج فقط؛ ويذكر الجدول أين. وتسرد صفحات نقاط النهاية كل حقل.

الحقل	الوصف	يطبّقه
`system`	تعليمات للنموذج: رسالة `system` في Chat Completions، و`system` في Messages، و`instructions` في Responses.	النماذج المفتوحة الأوزان المستضافة، و`shannon-1.6-`، و`shannon-2-`، و`shannon-coder-1`
`temperature`	درجة حرارة أخذ العيّنات.	النماذج المفتوحة الأوزان المستضافة، و`shannon-1.6-*`، و`shannon-coder-1`
`top_p`	أخذ العيّنات بالنواة (nucleus sampling).	النماذج المفتوحة الأوزان المستضافة
`seed`	بذرة ثابتة للعيّنات.	النماذج المفتوحة الأوزان المستضافة
`stop`	حتى 4 تسلسلات إيقاف.	النماذج المفتوحة الأوزان المستضافة
`reasoning_effort`	مقدار ما يستدل به النموذج قبل أن يجيب. `reasoning.effort` في Responses، و`thinking` في Messages.	النماذج المفتوحة الأوزان المستضافة
`web_search`	`true` يتيح للنموذج البحث على الويب في هذا الطلب. وهو حقل خاص بهذه API، في Chat Completions وMessages.	نماذج Shannon عدا `shannon-coder-1`
`max_tokens`	ميزانية المخرجات. وفي كل نموذج تحدد المقدار المحجوز من رصيدك.	بوصفه حداً لطول الإجابة: النماذج المفتوحة الأوزان المستضافة، و`shannon-1.6-*`، و`shannon-coder-1`

Chat Completions

القدوم من OpenAI SDK

اضبط base URL على https://api.shannon-ai.com/v1 واضبط المفتاح على مفتاح Shannon الخاص بك. عندئذٍ تعمل مكالمات Chat Completions وResponses مع SDK كما هو.
يجب أن يكون model معرّف Shannon. واسم نموذج لمزوّد آخر، مثل gpt-4o، يُجاب عنه بـ 400 وunknown model.
يأتي الاستدلال في حقل مستقل: reasoning_content بجانب content، في الرسالة وفي دلتا البث.
يحمل البث دائماً usage في آخر جزء، مع finish_reason.
يصل استدعاء الأداة في البث كجزء واحد يحتوي على السلسلة arguments كاملة.
للرد اختيار واحد (choice).
مسارات OpenAI API غير الموجودة في الجدول أعلاه، مثل /v1/embeddings، يُجاب عنها بـ 404.

القدوم من Anthropic SDK

اضبط عنوان base URL على https://api.shannon-ai.com، دون /v1، واضبط المفتاح على مفتاح Shannon الخاص بك. ترسله SDK باسم x-api-key.
يجب أن يكون model معرّف Shannon.
max_tokens اختياري في API هذه. وقيمته الافتراضية 4,096.
يحتوي الرد على كتل محتوى من الأنواع thinking وtext وtool_use. والكتلة الأولى ليست دائماً النص: اختر الكتل حسب type.
قيمة stop_reason هي end_turn أو tool_use. وقد ينتهي بث نموذج Shannon أيضاً بـ max_tokens.
يُقبل anthropic-version وanthropic-beta ليعمل SDK دون تغيير. ولا يحتاج الطلب إليهما.
للأخطاء على /v1/messages شكل Anthropic: {"type": "error", "error": {…}}.

أدوات البرمجة التي تتحدث بهذه الصيغ تُعدّ بالطريقة نفسها: base URL والمفتاح ومعرّف Shannon كنموذج. أدوات البرمجة بسطر الأوامر