KEATH Public API v1

هذا الدليل مكتوب لمن يريد ربط نظامه مع KEATH وتشغيل أول تقييم بدون قراءة الكود الداخلي.

Base URL

https://keath.ai/api/keath/public/v1

كل الطلبات تستخدم:

• Header: X-API-Key: kct_your_api_key
• Response: JSON قياسي من KEATH

المفتاح المطلوب هنا هو KEATH Public API key ويبدأ عادة ب kct_. لا ترسل مفاتيح Gemini أو OpenAI أو NewAPI إلى هذه الواجهة.

أول اختبار موصى به

1. نفذ GET /credits.
2. نفذ GET /models.
3. أنشئ assignment عبر POST /assignments باستخدام model_id.
4. أرسل التقييم عبر POST /evaluations باستخدام assignment_id.
5. تابع الحالة عبر GET /evaluations/:taskId/status.
6. عندما تصبح الحالة SUCCESS أو FAILURE أو CANCEL، اجلب النتيجة عبر GET /evaluations/:taskId.

معنى المعرّفات

إذا كان لديك نموذج مخصص تم تدريبه مسبقا، استخدم model_id الخاص به لإنشاء assignment أو لتقييم one-pass.

أهم المسارات

GET /models

curl "https://keath.ai/api/keath/public/v1/models" \
  -H "X-API-Key: kct_your_api_key"

مثال:

{
  "model_id": 930,
  "assignment_name": "O Level Situational Writing Model",
  "post_status": "ready",
  "total_score": 30
}

استخدم فقط النماذج التي حالتها ready.

POST /assignments

{
  "model_id": 930,
  "assignment_name": "Situation Writing Test",
  "assignment_desc": "Student-facing writing assignment",
  "project_subject": "English",
  "deadline_time": "2026-06-01T00:00:00.000Z",
  "expected_number": 30,
  "file_type": "pdf"
}

استجابة نموذجية:

{
  "assignment_id": 1620,
  "model_id": 930,
  "status": "active"
}

POST /evaluations

يستخدم لتقييم إجابة طالب داخل assignment موجود.

الحقول المهمة:

• assignment_id: واجب الطالب، وليس نموذج التصحيح.
• paper_content: نص إجابة الطالب.
• أو ملف إجابة عبر multipart/form-data.
• style: القيم الممكنة Bullet أو Short أو Long. الافتراضي هو Bullet.
• student_id: معرّف طالب مجهول من نظامك. KEATH لا ينشئ حساب طالب بهذا المعرّف.

صيغ ملفات الإجابة:

• PDF والصور: استخراج متعدد الوسائط، مع وصف بصري عند الحاجة للتصحيح.
• DOCX وTXT وRTF: استخراج نصي على الخادم.

أسماء حقول الملف المقبولة:

• answer_file
• answer_files
• paper_file
• paper_files
• response_file
• response_files
• file أو files

مثال:

curl -X POST "https://keath.ai/api/keath/public/v1/evaluations" \
  -H "X-API-Key: kct_your_api_key" \
  -F "assignment_id=1620" \
  -F "answer_file=@./student-answer.pdf;type=application/pdf" \
  -F "student_id=anon-student-001" \
  -F "style=Bullet"

POST /evaluations/one-pass

استخدم هذا المسار إذا كنت لا تريد إنشاء assignment.

curl -X POST "https://keath.ai/api/keath/public/v1/evaluations/one-pass" \
  -H "X-API-Key: kct_your_api_key" \
  -H "Idempotency-Key: eval-student-001-attempt-1" \
  -F "model_id=930" \
  -F "question_file=@./question.pdf;type=application/pdf" \
  -F "rubric_file=@./rubric.docx;type=application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
  -F "answer_file=@./student-answer.txt;type=text/plain" \
  -F "specification=Use Question 2 only." \
  -F "style=Bullet"

الصيغ المدعومة مباشرة:

• السؤال والrubric: PDF، صور، DOCX، TXT، RTF
• إجابة الطالب: PDF، صور، DOCX، TXT، RTF

يرجع المسار HTTP 202 Accepted مع task_id عام وstatus: "QUEUED" وstage: "queued". هذا يعني أن المهمة قُبلت، وليس أن التقييم اكتمل.

استخدم Idempotency-Key فريدا لكل إرسال منطقي. إعادة الطلب نفسه تعيد task_id نفسه، بينما استخدام المفتاح نفسه مع نص أو ملفات مختلفة يرجع 409.

تُحفظ الملفات قبل دخول قائمة الانتظار. لا تُخصم credits إلا بعد التحقق من نتيجة مكتملة. المهمة الفاشلة أو الملغاة تبقى فيها credits_charged: 0.

POST /evaluations/batch

يرسل من 1 إلى 100 تقييم one-pass. كل عنصر داخل evaluations يقبل حقول /evaluations/one-pass نفسها.

curl -X POST "https://keath.ai/api/keath/public/v1/evaluations/batch" \
  -H "X-API-Key: kct_your_api_key" \
  -H "Idempotency-Key: class-5a-writing-2026-07-15" \
  -H "Content-Type: application/json" \
  -d '{
    "evaluations": [
      {"model_id":930,"question_text":"اكتب رسالة رسمية.","paper_content":"عزيزي المدير، ...","student_id":"anon-001"},
      {"model_id":930,"question_text":"اكتب رسالة رسمية.","paper_content":"عزيزي المدير، أقترح ...","student_id":"anon-002"}
    ],
    "callback_url":"https://integration.example.com/keath/results"
  }'

callback_url اختياري ويجب أن يكون عنوان HTTPS عاما. احتفظ بالاستعلام الدوري كحل احتياطي.

قراءة الأسئلة والrubrics من الملفات

استخدم:

• POST /questions-ingest-preview
• POST /rubrics-ingest-preview

إذا كان الملف يحتوي على أكثر من سؤال، أضف specification:

Only parse Question 2. Ignore sample answers and teacher notes.

حالات التقييم

• QUEUED / queued
• UPLOADING / uploading
• SUBMITTED / submitted
• PROGRESS / processing
• SUCCESS / completed
• FAILURE / failed
• CANCEL / cancelled

ابدأ بالاستعلام كل 3 ثوان ثم زد المدة تدريجيا حتى 15 ثانية. ضع حدا أقصى للانتظار ولا تستخدم حلقة بلا نهاية.

للتوافق: يحتفظ POST /evaluations الخاص بassignment موجود بالمسار القديم ويخصم credits عند قبول المهمة. أما 202 وidempotency وقائمة الانتظار الدائمة والخصم بعد الاكتمال فتخص /evaluations/one-pass و/evaluations/batch.

إذا كانت الحالة FAILURE، قد يحتوي evaluation على عنصر type: "error" ورسالة واضحة في comment. تعامل معه كتقييم فشل، وليس كنتيجة بدرجة.

حدود الملفات

• الحد الأقصى 10 ملفات في الطلب الواحد للمسارات التي تقبل عدة ملفات.
• الحد الأقصى 20 MB لكل ملف.
• في /uploads/file أرسل ملفا واحدا فقط باسم الحقل file.

الأخطاء الشائعة

• 401: المفتاح مفقود أو غير صحيح.
• 402: الرصيد غير كاف.
• 403: لا توجد صلاحية للنموذج.
• 404: النموذج أو الassignment أو التقييم غير موجود.
• 409: النموذج ليس جاهزا، أو المهمة لا يمكن إلغاؤها.
• 400: حقل ناقص، JSON غير صحيح، أو نوع ملف غير مدعوم.

التالي

• أمثلة
• الانتقال من الواجهة القديمة