أمثلة واختبارات سريعة

ترتيب الاختبار

اختبر بهذا الترتيب:

  1. GET /credits
  2. GET /models
  3. POST /assignments
  4. POST /evaluations
  5. GET /evaluations/:taskId/status
  6. GET /evaluations/:taskId

إذا كنت لا تريد إنشاء assignment، استخدم POST /evaluations/one-pass.

نص تجربة

Dear Mrs Tan,

I am writing to request permission for our class to organise a recycling drive next Friday after school. Many students have noticed that large amounts of paper bottles and food packaging are thrown away every day. We believe a short class project would help students build better habits and understand why recycling matters.

If the school approves the activity our class can prepare labelled collection boxes and take turns to explain the instructions to other students. We can also make a short announcement during assembly so that everyone knows what items can be collected.

I hope you will consider this proposal. Thank you for your time and support.

Yours sincerely,
Jamie Lee

curl

الرصيد

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

النماذج

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

إنشاء assignment

curl -X POST "https://keath.ai/api/keath/public/v1/assignments" \
  -H "X-API-Key: kct_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

تقييم نص

curl -X POST "https://keath.ai/api/keath/public/v1/evaluations" \
  -H "X-API-Key: kct_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "assignment_id": 1620,
    "paper_content": "Dear Mrs Tan, I am writing to request permission...",
    "style": "Bullet",
    "student_id": "anon-student-001"
  }'

تقييم ملف

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"

One-pass

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"

الاستجابة هي HTTP 202. احفظ task_id العام ثم اجلب النتيجة لاحقا.

Batch 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"}
  ]}'

الحالة والنتيجة

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

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

JavaScript بسيط

const apiKey = process.env.KEATH_API_KEY
const baseUrl = 'https://keath.ai/api/keath/public/v1'

async function submitEvaluation(assignmentId, paperContent) {
  const response = await fetch(`${baseUrl}/evaluations`, {
    method: 'POST',
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      assignment_id: assignmentId,
      paper_content: paperContent,
      style: 'Bullet',
    }),
  })
  return response.json()
}

async function waitForEvaluation(taskId) {
  for (let attempt = 1; attempt <= 20; attempt++) {
    const response = await fetch(`${baseUrl}/evaluations/${taskId}/status`, {
      headers: { 'X-API-Key': apiKey },
    })
    const payload = await response.json()
    const status = payload.data?.status || payload.status
    if (['SUCCESS', 'FAILURE', 'CANCEL'].includes(status)) return payload
    await new Promise(resolve => setTimeout(resolve, Math.min(attempt * 3000, 15000)))
  }
  throw new Error(`Evaluation ${taskId} did not finish in time`)
}

قائمة تحقق

  • المفتاح يبدأ ب kct_.
  • المسار يبدأ ب /api/keath/public/v1.
  • model_id يأتي من GET /models.
  • assignment_id يأتي من POST /assignments أو رابط assignment.
  • النموذج حالته ready.
  • كل ملف أقل من 20 MB.
  • Google Docs يجب تصديره إلى DOCX أو PDF أو نص قبل الرفع.
Last Updated:
Contributors: PJ