مرجع API سريع: الطلبات والاستجابات والأخطاء
من البدء السريع إلى التطبيق العملي في السيناريوهات، كنت تتعامل طوال الوقت مع الشيء نفسه: نقطة النهاية /v1/systemone في TypeSafe API. هذه الصفحة تستخرجها وحدها وتضغطها في جدول مرجعي واحد — حقول الطلب، وإجابات أنواع الأسئلة، وترويسات الطلب، وقواعد الطلب، ورموز الحالة، كلها في جدول واحد يمكن الاستعلام عنه. أبقِ هذه الصفحة مفتوحة أثناء كتابة الكود؛ فهي أسرع من تقليب وثائق API الرسمية.
ماذا ستستطيع أن تفعل بعد إتمام الدرس
- ذكر نقطتي النهاية لـ TypeSafe API وطريقة المصادقة وحقول نص الطلب الأربعة (model / state / questions / assets)
- الاستعلام عن حقول الإرجاع الدقيقة لكل نوع إجابة حسب نوع السؤال (Choice / Score / Noul / Box)
- تحديد موقع الأخطاء وفق جدول رموز الحالة: ماذا يعني كل رمز من
400إلى529وما الذي يجب تعديله - معرفة متى يجب إضافة ترويسة
TypeSafe-Danger-Zone-*ومتى يجب كتابة إعادة المحاولة بنفسك - استخدام جدول الأساليب المكافئة في SDK لتنفيذ نفس الاستدعاء في Python / JavaScript
معضلتك الحالية
- في كل مرة تكتب فيها كودًا تعود لدرس البدء السريع لنسخ بنية الطلب، ولا توجد صفحة واحدة يمكن الاستعلام منها مباشرة
- عند حدوث خطأ لا تعرف سوى رقم رمز الحالة، ولا تدري هل نص الطلب مكتوب بشكل خاطئ أم أن المفتاح خاطئ
- طريقتان للكتابة — الاتصال المباشر بـ curl وSDK — تتصارعان في ذهنك وأسماء الحقول لا تتطابق
متى تستخدم هذه الطريقة
عندما تحتاج إلى:
- صفحة واحدة في متناول اليد للرجوع إليها فورًا أثناء الكتابة للاستعلام عن حقول TypeSafe API ورموز الحالة
- عند استكشاف الأخطاء، الحكم بسرعة على «هل هذا الخطأ 4xx من عندي أم من الخدمة»
ولا تريد:
- تقليب الوثيقة الطويلة لمرجع API الرسمي في كل مرة
- التنقل بين صفحات دروس متعددة للبحث عن شرح نفس الحقل
🎒 التحضير قبل البدء
- أن يكون قد تم تشغيل أول طلب بنجاح: تثبيت Python SDK وإرسال أول طلب (أو الاتصال المباشر بـ curl)
- مفتاح API موجود في متغير البيئة
TYPESAFE_API_KEY - إذا لم تنجح عملية التثبيت أو التشغيل، فاذهب أولًا إلى استكشاف أخطاء البدء وإصلاحها — هذه الصفحة للمرجع السريع فقط، وليست لاستكشاف الأخطاء خطوة بخطوة
الفكرة الأساسية: نقطة نهاية واحدة، وكل شيء يبدأ من بنية الطلب
جميع نماذج سلسلة Jev تُخدم عبر نقطة نهاية واحدة: POST https://api.typesafe.ai/v1/systemone. حقل model في الطلب يحدد أي نموذج سيتولى المعالجة — لا وجود لأمر من نوع «لكل نموذج URL خاص به».
المصادقة تعتمد على ترويسة واحدة فقط:
POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <你的API Key>
Content-Type: application/jsonهناك نقطة نهاية مساعدة لـ«الاستعلام عن النماذج المتاحة»:
curl https://api.typesafe.ai/v1/models \
-H "Authorization: Bearer $TYPESAFE_API_KEY"يجب أن ترى: مصفوفة models يحتوي كل عنصر منها على name وdescription وrelease_date (مثل قيم نموذجية مثل jev-latest وGeneral-purpose system one model. و2026-09-15). ضع قيمة name التي حصلت عليها مباشرة في حقل model في الطلب.
كيف يبدو نص الطلب؟ مثال التذكرة من البدء السريع الرسمي (نسخة الاتصال المباشر بـ curl، مقتطف من سؤالين، ويتطلب curl 7.76+، و--fail-with-body لطباعة نص الاستجابة عند حدوث خطأ أيضًا):
curl --fail-with-body --silent --show-error \
https://api.typesafe.ai/v1/systemone \
-H "Authorization: Bearer $TYPESAFE_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <<'JSON'
{
"state": "Our API integration started returning 500 errors...",
"model": "jev-latest",
"questions": {
"department": {
"type": "choice",
"instructions": "Which team should handle this",
"criteria": {
"billing": "Payment or subscription issues",
"technical": "Bugs or integration problems",
"sales": "Pricing or account questions"
}
},
"is_urgent": {
"type": "noul",
"instructions": "The message conveys urgency or time-sensitivity"
}
}
}
JSONواجهة API بأكملها لها هذا الشكل الواحد فقط. فيما يلي تفكيكها قطعةً قطعة للمرجع السريع.
الجدول الكامل لحقول الطلب
| الحقل | إلزامي | النوع | الشرح |
|---|---|---|---|
model | ✅ | سلسلة نصية | اسم النموذج أو اسمه البديل؛ الأسماء المتاحة يرجعها GET /v1/models. مثل jev-latest وjev-preview |
state | ✅ | سلسلة نصية / كائن JSON / مصفوفة نصوص | المحتوى الذي تُقيَّم على أساسه جميع الأسئلة. الأشكال الثلاثة موضحة بالتفصيل في حالة State |
questions | ✅ | كائن (1 سؤال على الأقل) | المفتاح هو معرّف السؤال الذي تختاره بنفسك، والقيمة هي كائن السؤال؛ لا يوجد حد أقصى لعدد الأسئلة، والقيد الوحيد هو طول السياق |
assets | ❌ | كائن (1 عنصر على الأقل) | موارد الصور، والمفاتيح عبارة عن عناصر نائبة (التوصية الرسمية هي UUID واحد لكل صورة)؛ عند استخدام الصور يجب إرفاق الترويسة TypeSafe-Danger-Zone-Images: true |
حقول كائن المشكلة:
| الحقل | مطلوب | الوصف |
|---|---|---|
| المعرف (مفتاح الكائن) | ✅ | تختاره بنفسك، وتستخدمه لمطابقة الإجابة في الاستجابة؛لا يُرسل إلى النموذج—يجب كتابة المشكلة الكاملة في instructions، حتى لو بدا المعرف بديهيًا |
type | ✅ | اختيار واحد من أربعة: choice / score / noul / box |
instructions | يمكن حذفه في الأنواع الأربعة من أنواع الأسئلة في schema | المشكلة الكاملة؛ يمكن أن تكون سلسلة نصية أو كائن JSON أو مصفوفة (يمكن فصل المشكلة عن البيانات التي تشير إليها). المعرف لا يُرسل إلى النموذج، لذا يجب كتابته فعليًا لكل مشكلة |
criteria | مطلوب لـ Choice و Score | Choice: خريطة الخيارات (1–255 عنصرًا)؛ Score: قائمة مراتب مرتبة (1–10 عنصرًا)؛ Noul: تعريف true/false نعم/لا اختياري |
للإشارة إلى حقول state في instructions، ضع المسار النقطي/بالمؤشر بين علامتي backtick، مثل `ticket.messages[0].text`—انظر درس حالة State للتفاصيل.
الجدول الكامل لأنواع المشكلات وحقول الإجابة
يمكن خلط أي أنواع مشكلات في طلب واحد؛ تُقيَّم جميع المشكلات على نفس الـ state بشكل متوازٍ ومستقل (للحالة القصوى لهذا الاستخدام انظر الأسئلة المتوازية).
| نوع المشكلة | type القيمة | شكل criteria | حقل الإجابة |
|---|---|---|---|
| Choice | choice | خريطة الخيارات، 1–255 عنصرًا | choice (اسم الخيار المحدد، أي الخيار ذي الاحتمال الأعلى)، confidence، probabilities (احتمال واحد لكل خيار، ومجموعها يساوي 1 بشكل غير صارم) |
| Score | score | قائمة مراتب مرتبة، 1–10 عنصرًا | score (القيمة المتوقعة الموزونة بالاحتمالات، قد تقع بين مرتبتين، مثل 0.67 / 1.7)، confidence، legend (تعيين من المرتبة إلى القيمة)، probabilities |
| Noul | noul | اختياري: تعريف true/false | noul (احتمال صحة/صواب 0–1؛ القرب من 0.5 = غير محسوم؛ لا يوجد حقل confidence) |
| Box | box | لا شيء | box (top/bottom/left/right الحواف الأربعة، كنسبة من ارتفاع/عرض الصورة ضمن النطاق 0–1)، confidence (قد يكون null). يتطلب صورة + تفعيل ترويسة الصور |
كيف تختار نوع المشكلة، والاستخدام الكامل لكل نوع:
- Choice أسئلة الاختيار · Score أسئلة التقييم · Noul أسئلة نعم/لا · Box والصور
- كيف يُحسب confidence وكيف تضبط العتبة: الثقة Confidence
الجدول الكامل لترويسات الطلب
| ترويسة الطلب | متى تُستخدم | الوصف |
|---|---|---|
Authorization: Bearer <key> | كل طلب | مفقودة أو غير صالحة → 401 |
Content-Type: application/json | طلبات النصوص | الصور تمر عبر multipart/form-data: الـ JSON كجزء أول (باسم request)، ولكل صورة جزء مستقل |
Content-Encoding: gzip أو x-gzip / zstd | ضغط جسم الطلبات الكبير | طبقة واحدة فقط؛ نافذة zstd ≤ 8 MiB؛ غير مدعوم أو متعدد الطبقات → 415، جسم مضغوط تالف → 400 |
TypeSafe-Danger-Zone-Images: true | عندما يحتوي الطلب على صور أو أسئلة Box | يجب إرفاقها مع كل طلب يحتوي صورًا؛ إغفالها → 400 |
TypeSafe-Danger-Zone-Long-Context: true | عندما لا يتسع النص الطويل في السياق الافتراضي | يصبح السياق لكل طلب ولكل مشكلة 262k؛ السعر لا يتغير، لكنه أبطأ وأقل دقة، فاستخدمه فقط للطلبات التي تحتاجه |
حدود السياق الافتراضية (نفس Jev 1.14 و 1.13): لكل طلب 64k / لكل مشكلة 32k token؛ لا يوجد حد أقصى لعدد المشكلات نفسه. للمراجعة السريعة للأسعار وإصدارات النماذج انظر النماذج والأسعار.
قواعد الطلب والضغط
تحدد وثائق errors الرسمية أربع قواعد صارمة لكل طلب:
| القاعدة | الحد | رمز حالة المخالفة |
|---|---|---|
| حجم نص الطلب | ≤ 32 MiB (بدون الترويسات) | 413 (عند تجاوز الحد يُحتسب قبل الضغط وبعده) |
| الترميز | JSON بترميز UTF-8، بدون BOM | 400 |
| التداخل | كل من state / instructions / criteria بحد أقصى ≤ 64 مستوى من الكائنات والمصفوفات، وما هو أعمق يُسطَّح مسبقًا | 400 |
| الأرقام | تُقبل الأرقام المحدودة فقط: أمثال NaN وInfinity و1e400 تُرفض جميعها؛ الأرقام الكبيرة والمعرّفات تُرسل كنصوص | 400 |
يضيف الضغط قاعدتين فقط: حد بمستوى واحد، ونافذة zstd ≤ 8 MiB.
الجدول الكامل لحقول الاستجابة
{
"model": "jev-1.14.0",
"answers": {
"department": {
"type": "choice",
"choice": "technical",
"confidence": 1.0,
"probabilities": { "technical": 1.0, "billing": 0.0, "sales": 0.0 }
},
"frustration": {
"type": "score",
"score": 0.67,
"confidence": 0.5,
"legend": { "0": "Calm…", "1": "Frustrated…", "2": "Very angry…" },
"probabilities": { "0": 0.33, "1": 0.67, "2": 0.0 }
},
"is_urgent": { "type": "noul", "noul": 0.99 }
},
"usage": { "input_tokens": 428, "output_tokens": 73 }
}(قيم نموذجية، تتغير مع الإصدارات؛ للنموذج الكامل انظر درس الطلب الأول.)
| الحقل | الموضع | الوصف |
|---|---|---|
model | المستوى الأعلى | اسم النموذج الذي أجاب فعليًا؛قد يختلف عن الاسم المستعار في الطلب (مثل طلب jev-latest وإرجاع رقم إصدار محدد) |
answers | المستوى الأعلى | يطابق معرّفات الأسئلة التي حددتها واحدًا واحدًا؛type لكل سؤال يطابق type لسؤاله |
usage.input_tokens | المستوى الأعلى | عدد الرموز المدخلة المحسوبة في الفوترة هذه المرة (تحتسب الفوترة على المدخلات فقط) |
usage.output_tokens | المستوى الأعلى | عدد رموز المخرجات، مجاني حاليًا |
الجدول الكامل لرموز الحالة
| رمز الحالة | المعنى | ما يجب عليك فعله |
|---|---|---|
200 | نجاح | احصل على الإجابات حسب المعرّف |
400 Bad Request | مخالفة قواعد الطلب (UTF-8 غير صالح، تداخل يتجاوز 64 مستوى، رقم غير محدود، نص مضغوط تالف، ترويسة صورة ناقصة)؛max_tokens_exceeded = تجاوز طول السياق | راجع جدول «قواعد الطلب» وصحّح نص الطلب؛ عند تجاوز السياق قلّص state أو فعّل ترويسة السياق الطويل |
401 Unauthorized | المفتاح مفقود أو غير صالح | تحقق من ترويسة Authorization؛ ومستخدمو SDK يتحققون من TYPESAFE_API_KEY (انظر تنبيهات المخاطر أدناه) |
413 Payload Too Large | نص الطلب يتجاوز 32 MiB | قلّص state؛ الضغط لن ينقذك 413——حد 32 MiB يسري قبل الضغط وبعده |
415 Unsupported Media Type | Content-Encoding غير مدعوم أو ضغط متعدد المستويات | استخدم واحدًا فقط من gzip / x-gzip / zstd، بمستوى واحد |
422 Unprocessable Entity | فشل التحقق من نص الطلب: حقول إلزامية ناقصة، تنسيق أسئلة خاطئ، إلخ | انظر مصفوفة detail في الـ body لتحديد الموضع |
429 Too Many Requests | تجاوز حد المعدل (يُحسب لكل مؤسسة: tokens/s + requests/s، يمكن الاطلاع عليه في console.typesafe.ai/rate-limits بالوحدة التحكم) | أعد المحاولة بتراجع أُسّي؛ يتولاه SDK تلقائيًا افتراضيًا |
529 Overloaded | TypeSafe زيادة تحميل مؤقتة | مثل 429: أعد المحاولة بعد التراجع |
يصل نص 422 إلى دقة مستوى الحقل:
{
"detail": [
{ "loc": ["body", "state"], "msg": "Field required", "type": "missing" }
]
}اعثر على الحقل الذي به الخطأ عبر loc، وmsg يخبرك بما هو ناقص.
معالجة الأخطاء وإعادة المحاولة
القاعدة الرسمية في سطر واحد: عند استلام 429 أو 529، أعد المحاولة بتراجع أُسّي (أطل الانتظار تدريجيًا في كل مرة)، ولا تعد الإرسال كما هو فورًا؛ وإذا جاءت الاستجابة مع ترويسة retry-after فاتبعها.
إذا كنت تستخدم SDK: يأتي SDK الخاص بـ Python / JavaScript بسياسة إعادة محاولة افتراضية تتولى 429 تلقائيًا دون حاجة إلى كود إضافي. وعند الحاجة إلى تخصيص (Python):
from typesafe_sdk import RetryPolicy, TypeSafeClient
client = TypeSafeClient(retry=RetryPolicy(max_retries=3, backoff_max=0.2, timeout=1.0))الطريقة القياسية لالتقاط أخطاء API في Python SDK:
from typesafe_sdk import TypeSafeAPIError
try:
client.system_one(state, questions)
except TypeSafeAPIError as error:
print(error.status, error.request_id)error.status هو رمز الحالة، وerror.request_id هو معرّف الطلب——أرفقهما عند التواصل مع الدعم الرسمي.
إذا كنت تتصل بالـ API مباشرة: عليك كتابة إعادة المحاولة بنفسك. خيار --fail-with-body في curl يضمن على الأقل رؤية نص الاستجابة عند حدوث خطأ.
مختصر عميلي Python
TypeSafe API لهما أسماء طرق متطابقة على عميلي Python: TypeSafeClient (متزامن) وAsyncTypeSafeClient (غير متزامن)، وكلاهما system_one(). متغيرات البيئة التي يقرأها SDK:
| المتغير | الدور | الافتراضي |
|---|---|---|
TYPESAFE_API_KEY | مفتاح API (إلزامي) | — |
TYPESAFE_BASE_URL | عنوان URL الجذري للـ API | https://api.typesafe.ai |
TYPESAFE_DEFAULT_MODEL | النموذج الافتراضي | jev-latest |
TYPESAFE_LOG_LEVEL | typesafe_sdk مستوى التسجيل، يسري مرة واحدة عند الـ import | غير مضبوط |
مختصر إجابات TypeScript
في SDK الخاص بـ JS/TS (@typesafe-ai/sdk) تُجلب الإجابات مباشرة حسب المعرّف: response.answers.department.choice، والأنواع تُستنتج من تعريف السؤال (مثل "billing" | "technical" | "sales").
تنبيهات المخاطر
❌ طلبت jev-latest، لكن model في الاستجابة ليس هو
هذا ليس خطأً — model في الاستجابة هو اسم النموذج الذي أجاب فعليًا، وقد يختلف عن الاسم المستعار في الطلب (مواصفات API الرسمية توضح ذلك صراحةً). لمعرفة ما يشير إليه الاسم المستعار حاليًا، راجع النماذج والأسعار.
❌ اختلطت مسافات أو أسطر جديدة في الـ Key
عند الاتصال المباشر، هذا النوع من المفاتيح يفشل دائمًا بـ 401. يقوم SDK بإزالة الفراغات من بداية الـ Key ونهايته (بما في ذلك الأسطر الجديدة المقروءة من ملف)، لكن المسافات الداخلية ومحارف التحكم وغير ASCII تُرفض مباشرةً (يظهر الخطأ عند إنشاء العميل، فلا يصل إلى 401)؛ تمرير Key فارغ صراحةً لا يتراجع إلى متغير البيئة. عند نسخ الـ Key من لوحة التحكم، احرص على عدم تحديد مسافة زائدة.
❌ تخمين مكان الخطأ من رمز حالة 422
لا تخمّن، اقرأ الـ body: loc في مصفوفة detail هو مسار الحقل (مثل ["body", "questions", "urgency", "criteria"])، وmsg هو السبب.
❌ لا تجد confidence في إجابة Noul
لم يضِع — Noul بطبيعته لا يحتوي على حقل confidence. لتوحيد العتبة يمكنك حساب |2p − 1| بنفسك، والنقطة المقترحة رسميًا: yes ≥ 0.7، no ≤ 0.3 (انظر أسئلة Noul بنعم/لا).
❌ الاستدعاءات المتكررة للـ API بالاتصال المباشر تغمرها رسائل 429
حدود المعدل تُحسب لكل مؤسسة (tokens/s + requests/s). يقوم SDK افتراضيًا بإعادة المحاولة مع التراجع الأُسّي؛ عند الاتصال المباشر اكتب التراجع الأُسّي بنفسك. للحصول على حصة أعلى استخدم نموذج الطلب الرسمي (support.typesafe.ai).
خلاصة هذا الدرس
✅ نقطة نهاية واحدة POST /v1/systemone، والمصادقة عبر ترويسة واحدة، وجسم الطلب بأربعة حقول (model / state / questions / assets).
✅ أربعة أنواع من الأسئلة بأربعة أنواع من الإجابات: Choice يخرج اختيارًا + احتمالات + confidence، وScore يخرج الدرجة المتوقعة + legend، وNoul يخرج احتمال 0–1 فقط، وBox يخرج نسب الأضلاع الأربعة.
✅ رموز الحالة في سلسلة واحدة: 400 قواعد / 401 Key / 413 الحجم / 415 الضغط / 422 التحقق (انظر الـ body) / 429 و529 إعادة المحاولة مع التراجع.
✅ ترويستا Danger Zone تُضافان عند الحاجة: للصور TypeSafe-Danger-Zone-Images، وللسياق الطويل TypeSafe-Danger-Zone-Long-Context.
مراجعة حقول الإعداد الأساسية:
| الحقل | القيمة الموصى بها | الشرح |
|---|---|---|
model | jev-latest | اسم مستعار، يشير حاليًا إلى Jev 1.14؛ لتثبيت الإصدار اكتب jev-1.14.0 |
state | سلسلة نصية / كائن JSON / مصفوفة نصوص | اختر أيًا من الأشكال الثلاثة |
questions | {ID: {type, instructions, criteria}} | لا يُرسل الـ ID إلى النموذج؛ اكتب السؤال الكامل في instructions |
| السياق | 64k / طلب · 32k / سؤال | بعد إضافة ترويسة السياق الطويل يصبح كلاهما 262k |
| جسم الطلب | JSON بترميز UTF-8 ≤ 32 MiB · تعشيق ≤ 64 مستوى · يجب أن تكون الأرقام محدودة | يُسمح بضغط طبقة واحدة gzip / zstd |
استعراض الدرس التالي
أتقنت استدعاء API، وحان وقت فهم الحساب أيضًا: النماذج والأسعار: الإصدارات وحدود السياق والتعريفات.
ستتعلم:
- الجدول الزمني لإصدارات
jev-1.14.0وjev-1.13.0وما تشير إليه الأسماء المستعارة - طريقة فوترة $42/Btok: لماذا تُحتسب رموز الإدخال فقط
- تفاصيل حدود السياق وثمن السياق الطويل
- كيفية الاستعلام عن حدود المعدل وكيفية طلب زيادة الحصة
دروس ذات صلة
- ماذا تفعل إذا فشل التثبيت أو التشغيل: استكشاف أخطاء البداية وإصلاحها — النسخة الكاملة لاستكشاف الأخطاء رسالةً برسالة
- تثبيت Python SDK وإرسال أول طلب — شرح خطوة بخطوة لبنية الطلب
- طرق تثبيت بديلة: uv وnpm وcurl للاتصال المباشر بالـ API — المسار الكامل للاتصال المباشر عبر curl