Skip to content

مرجع 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 الرسمي في كل مرة
  • التنقل بين صفحات دروس متعددة للبحث عن شرح نفس الحقل

🎒 التحضير قبل البدء ​

الفكرة الأساسية: نقطة نهاية واحدة، وكل شيء يبدأ من بنية الطلب ​

جميع نماذج سلسلة Jev تُخدم عبر نقطة نهاية واحدة: POST https://api.typesafe.ai/v1/systemone. حقل model في الطلب يحدد أي نموذج سيتولى المعالجة — لا وجود لأمر من نوع «لكل نموذج URL خاص به».

المصادقة تعتمد على ترويسة واحدة فقط:

http
POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <你的API Key>
Content-Type: application/json

هناك نقطة نهاية مساعدة لـ«الاستعلام عن النماذج المتاحة»:

bash
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 لطباعة نص الاستجابة عند حدوث خطأ أيضًا):

bash
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 و ScoreChoice: خريطة الخيارات (1–255 عنصرًا)؛ Score: قائمة مراتب مرتبة (1–10 عنصرًا)؛ Noul: تعريف true/false نعم/لا اختياري

للإشارة إلى حقول state في instructions، ضع المسار النقطي/بالمؤشر بين علامتي backtick، مثل `ticket.messages[0].text`—انظر درس حالة State للتفاصيل.

الجدول الكامل لأنواع المشكلات وحقول الإجابة ​

يمكن خلط أي أنواع مشكلات في طلب واحد؛ تُقيَّم جميع المشكلات على نفس الـ state بشكل متوازٍ ومستقل (للحالة القصوى لهذا الاستخدام انظر الأسئلة المتوازية).

نوع المشكلةtype القيمةشكل criteriaحقل الإجابة
Choicechoiceخريطة الخيارات، 1–255 عنصرًاchoice (اسم الخيار المحدد، أي الخيار ذي الاحتمال الأعلى)، confidence، probabilities (احتمال واحد لكل خيار، ومجموعها يساوي 1 بشكل غير صارم)
Scorescoreقائمة مراتب مرتبة، 1–10 عنصرًاscore (القيمة المتوقعة الموزونة بالاحتمالات، قد تقع بين مرتبتين، مثل 0.67 / 1.7)، confidence، legend (تعيين من المرتبة إلى القيمة)، probabilities
Noulnoulاختياري: تعريف true/falsenoul (احتمال صحة/صواب 0–1؛ القرب من 0.5 = غير محسوم؛ لا يوجد حقل confidence)
Boxboxلا شيءbox (top/bottom/left/right الحواف الأربعة، كنسبة من ارتفاع/عرض الصورة ضمن النطاق 0–1)، confidence (قد يكون null). يتطلب صورة + تفعيل ترويسة الصور

كيف تختار نوع المشكلة، والاستخدام الكامل لكل نوع:

الجدول الكامل لترويسات الطلب ​

ترويسة الطلبمتى تُستخدمالوصف
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، بدون BOM400
التداخلكل من state / instructions / criteria بحد أقصى ≤ 64 مستوى من الكائنات والمصفوفات، وما هو أعمق يُسطَّح مسبقًا400
الأرقامتُقبل الأرقام المحدودة فقط: أمثال NaN وInfinity و1e400 تُرفض جميعها؛ الأرقام الكبيرة والمعرّفات تُرسل كنصوص400

يضيف الضغط قاعدتين فقط: حد بمستوى واحد، ونافذة zstd ≤ 8 MiB.

الجدول الكامل لحقول الاستجابة ​

json
{
  "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 TypeContent-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 OverloadedTypeSafe زيادة تحميل مؤقتةمثل 429: أعد المحاولة بعد التراجع

يصل نص 422 إلى دقة مستوى الحقل:

json
{
  "detail": [
    { "loc": ["body", "state"], "msg": "Field required", "type": "missing" }
  ]
}

اعثر على الحقل الذي به الخطأ عبر loc، وmsg يخبرك بما هو ناقص.

معالجة الأخطاء وإعادة المحاولة ​

القاعدة الرسمية في سطر واحد: عند استلام 429 أو 529، أعد المحاولة بتراجع أُسّي (أطل الانتظار تدريجيًا في كل مرة)، ولا تعد الإرسال كما هو فورًا؛ وإذا جاءت الاستجابة مع ترويسة retry-after فاتبعها.

إذا كنت تستخدم SDK: يأتي SDK الخاص بـ Python / JavaScript بسياسة إعادة محاولة افتراضية تتولى 429 تلقائيًا دون حاجة إلى كود إضافي. وعند الحاجة إلى تخصيص (Python):

python
from typesafe_sdk import RetryPolicy, TypeSafeClient

client = TypeSafeClient(retry=RetryPolicy(max_retries=3, backoff_max=0.2, timeout=1.0))

الطريقة القياسية لالتقاط أخطاء API في Python SDK:

python
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 الجذري للـ APIhttps://api.typesafe.ai
TYPESAFE_DEFAULT_MODELالنموذج الافتراضيjev-latest
TYPESAFE_LOG_LEVELtypesafe_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.

مراجعة حقول الإعداد الأساسية:

الحقلالقيمة الموصى بهاالشرح
modeljev-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: لماذا تُحتسب رموز الإدخال فقط
  • تفاصيل حدود السياق وثمن السياق الطويل
  • كيفية الاستعلام عن حدود المعدل وكيفية طلب زيادة الحصة

دروس ذات صلة ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.