Exemples et tests rapides

Ordre de test recommandé

Ne commencez pas par l'endpoint le plus complexe. Testez dans cet ordre :

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

Si vous ne voulez pas créer d'assignment, remplacez les étapes 3 et 4 par POST /evaluations/one-pass.

Texte de test pour une copie

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

Crédits

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

Modèles

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

Créer un 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"
  }'

Corriger avec du texte

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

Corriger avec un fichier

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"

La réponse est HTTP 202. Enregistrez le task_id public et récupérez le résultat plus tard.

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":"Rédigez une lettre.","paper_content":"Madame, Monsieur, ...","student_id":"anon-001"},
    {"model_id":930,"question_text":"Rédigez une lettre.","paper_content":"Madame, Monsieur, je propose ...","student_id":"anon-002"}
  ]}'

Statut et résultat

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 minimal

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`)
}

Liste de vérification

  • La clé commence par kct_.
  • La route commence par /api/keath/public/v1.
  • model_id vient de GET /models.
  • assignment_id vient de POST /assignments ou de l'URL du devoir.
  • Le modèle est ready.
  • Les fichiers font moins de 20 MB.
  • Les Google Docs doivent être exportés en DOCX, PDF ou texte avant l'envoi.
Last Updated:
Contributors: PJ