Ejemplos y pruebas

Orden recomendado

Pruebe en este orden:

GET /credits
GET /models
POST /assignments
POST /evaluations
GET /evaluations/:taskId/status
GET /evaluations/:taskId

Si no quiere crear un assignment, use POST /evaluations/one-pass.

Texto de prueba

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éditos

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

Modelos

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

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

Evaluar con texto

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

Evaluar con archivo

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 respuesta es HTTP 202. Guarde el task_id público y consulte el resultado después.

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":"Escriba una carta.","paper_content":"Estimado director: ...","student_id":"anon-001"},
    {"model_id":930,"question_text":"Escriba una carta.","paper_content":"Estimado director, propongo ...","student_id":"anon-002"}
  ]}'

Estado y resultado

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 mínimo

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

Lista de revisión

La key empieza con kct_.
La ruta empieza con /api/keath/public/v1.
model_id viene de GET /models.
assignment_id viene de POST /assignments o de la URL del assignment.
El modelo está ready.
Cada archivo pesa menos de 20 MB.
Google Docs debe exportarse a DOCX, PDF o texto antes de subirlo.