KEATH Public API v1

这页是给真实接入方看的，不是给内部系统看的。

先记住这件事：

model_id 用来选择 marking model。
assignment_id 用来给一个已经存在的学生 assignment 提交评测。
如果你不想创建 assignment，就用 POST /evaluations/one-pass，一次性传 model、题目、rubric 和学生作答。

最稳的第一次联调顺序是：

GET /credits
GET /models
用 model_id 调 POST /assignments
用返回的 assignment_id 调 POST /evaluations
轮询到 SUCCESS、FAILURE 或 CANCEL
再拉最终结果

Base URL

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

所有请求统一使用：

Header：X-API-Key: kct_your_api_key
响应：标准 KEATH JSON 返回结构

API Key 需要先在产品侧登录后创建：

POST /api/keath/public_api/keys/create
GET /api/keath/public_api/keys/list
POST /api/keath/public_api/keys/revoke

这次更新了什么

这套文档已经替换旧的 X-TOKEN-KEY + /api/open/evaluation/* 接入方式。

现在的 Public API 围绕 5 类能力：

查询 credits 和可用模型
解析题目 PDF / 图片和 rubric PDF / 图片
在确认预解析结果后创建 marking model 和学生 assignment
通过文本或文件把学生作文提交给现有 assignment 做评测
对 feedback 做风格化重写

接口总览

接口	方法	作用
`/credits`	`GET`	查询当前可用 credits
`/models`	`GET`	查询当前 API key 可访问的 marking models
`/models`	`POST`	创建 / 训练 marking model
`/assignments`	`POST`	用已有 `model_id` 创建学生 assignment
`/questions-ingest-preview`	`POST`	解析题目 PDF / 图片 / URL 资源
`/rubrics-ingest-preview`	`POST`	解析 rubric PDF / 图片 / URL 资源
`/evaluations`	`POST`	将学生作文提交给现有 assignment 进行评测
`/evaluations/one-pass`	`POST`	一次性提交 model id、题目、rubric 和学生作答进行评测
`/evaluations/batch`	`POST`	一次提交 1-100 个 one-pass 评测任务
`/evaluations/:taskId/status`	`GET`	轮询轻量状态
`/evaluations/:taskId`	`GET`	获取评测结果
`/evaluations/:taskId/cancel`	`POST`	取消排队中或进行中的评测
`/feedback-rewrite`	`POST`	将 feedback 改写成不同风格
`/uploads/file`	`POST`	上传一个本地 PDF / 图片并拿到可复用的公开 URL

认证

示例：

X-API-Key: kct_your_api_key

如果没有传 key 或 key 无效，接口会返回 401。

这里的 key 是 KEATH 账号对应的 Public API key。不要把 Gemini、NewAPI 等内部模型供应商 key 传给 Public API。

Key Scope 与扣费语义

Public API key 目前支持两种 scope：

user：只能访问 key 拥有者自己的 models
organization：可以访问所属组织下的 models

需要注意：

organization scope 只能由 organization admin 创建。
organization scope 的实际访问权限仍然取决于这个 key 拥有者当前是否还是 organization admin。
即使是 organization scope，credits 目前仍然扣在 key 拥有者自己的 KEATH 账号上，当前 billing mode 仍然是 owner_user。

`GET /credits`

用于查询当前 API key 所属用户剩余的可用 credits。

示例：

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

`GET /models`

返回该 API key 可以访问的 marking model 列表。创建 assignment 或 one-pass evaluation 时使用这里返回的 model_id。

示例：

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

典型 model item：

{
  "model_id": 930,
  "assignment_name": "O Level Situational Writing Model",
  "assignment_desc": "Reusable marking model",
  "post_status": "ready",
  "creation_method": "custom",
  "total_score": 30
}

`POST /questions-ingest-preview`

这个接口用于在创建 assignment 之前先理解题目内容。

支持三类输入：

通过 assets[] 传已存在的公开 URL
通过 multipart/form-data 直接上传本地文件
通过 specification 指定只解析某一个题目，适合一个 PDF 里有多个 question 的场景

JSON 模式

{
  "assets": [
    {
      "url": "https://cdn.example.com/question-pack.pdf",
      "mime_type": "application/pdf",
      "name": "question-pack.pdf"
    }
  ],
  "specification": "只解析 Question 2，忽略其他页面。",
  "assignment_name": "O Level Situational Writing Practice 2",
  "assignment_desc": "中学场景写作练习题"
}

Multipart 上传模式

现在接口已经支持 direct upload。

文件字段名：file 或 files
支持的 MIME type：
- application/pdf
- image/png
- image/jpeg
- image/webp
- image/gif
单次请求最多 10 个文件
单个文件最大 20 MB

建议客户端显式传 MIME type，例如 ;type=application/pdf。如果客户端只传了 application/octet-stream，或者没有传 MIME type，KEATH 会尝试根据文件扩展名兜底识别：.pdf、.png、.jpg、.jpeg、.webp、.gif。

示例：

curl -X POST "https://keath.ai/api/keath/public/v1/questions-ingest-preview" \
  -H "X-API-Key: kct_your_api_key" \
  -F "files=@./question-pack.pdf;type=application/pdf" \
  -F "files=@./page-2.png;type=image/png" \
  -F "specification=只解析这组材料里的 Question 2。" \
  -F "assignment_name=O Level Situational Writing Practice 2"

同时混合本地上传和已有 URL

如果你既要上传本地文件，又要补充一个已有 CDN / OSS URL，可以这样发：

文件放在 files
assets 作为 JSON 字符串放在 form 字段里

示例：

curl -X POST "https://keath.ai/api/keath/public/v1/questions-ingest-preview" \
  -H "X-API-Key: kct_your_api_key" \
  -F "files=@./scan-1.jpg;type=image/jpeg" \
  -F 'assets=[{"url":"https://cdn.example.com/appendix.pdf","mime_type":"application/pdf","name":"appendix.pdf"}]' \
  -F "specification=以上传图片为目标题目，appendix 只作为补充上下文。"

`POST /rubrics-ingest-preview`

这个接口用于在创建 assignment 前，先把 rubric 从 PDF / 图片中抽取出来。

支持的传输方式和题目解析一致：

JSON + assets
multipart/form-data 直接上传

rubric 相关字段：

total_score
cum_method：sum 或 average

JSON 示例：

{
  "assets": [
    {
      "url": "https://cdn.example.com/rubric.pdf",
      "mime_type": "application/pdf"
    }
  ],
  "specification": "只使用第 3 页的 rubric 表格。",
  "total_score": 30,
  "cum_method": "sum"
}

Multipart 示例：

curl -X POST "https://keath.ai/api/keath/public/v1/rubrics-ingest-preview" \
  -H "X-API-Key: kct_your_api_key" \
  -F "file=@./rubric.pdf;type=application/pdf" \
  -F "total_score=30" \
  -F "cum_method=sum" \
  -F "specification=只使用第一页的 rubric。"

`POST /models`

当 questions 和 rubrics 的预解析结果确认没问题后，再调用这个接口创建可复用的 marking model。

请求体和产品内部的 model creation DTO 对齐。通常你需要提交：

assignment_name
assignment_desc
最终确认后的 questions
最终确认后的 rubrics
total_score、cum_method 等评分信息

推荐流程：

先解析 questions
再解析 rubrics
让用户确认和编辑预解析结果
最后调用 POST /models

`POST /assignments`

用一个已有 marking model 创建面向学生的 assignment。这个流程和产品 UI 一致：先在 Model Selection 选择模型，再创建 Assignment。

必填字段：

model_id：来自 GET /models 的 ready model
assignment_name
assignment_desc
deadline_time
expected_number

可选字段：

project_subject
start_time
file_type：word、pdf、image 或 text，默认是 pdf

示例：

{
  "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,
  "assignment_name": "Situation Writing Test",
  "status": "active"
}

`POST /evaluations`

把一篇学生作文提交给一个现有学生 assignment，并启动异步评测任务。

这个接口适用于 KEATH 里已经存在 assignment 的情况。assignment_id 是产品里的 assignment / project ID，例如 /homeTab/person/assignments/detail?id=1620 里的 1620。

必填字段：

assignment_id：来自 POST /assignments 或产品 assignment 详情页 URL 的 assignment ID
二选一：
- paper_content：学生作文文本
- 通过 multipart/form-data 上传学生作答文件

可选字段：

current_feedbacks：如果你希望 KEATH 参考当前已有的 rubric-level feedback，可以传这个数组
style：可选 Bullet、Short、Long，默认是 Bullet
student_id：你们外部系统里的匿名学生 ID；KEATH 只会随任务元信息透传，不会创建或更新 KEATH 学生记录

支持的学生作答文件：

PDF 和图片：通过 Gemini 多模态抽取，会包含必要的视觉内容描述
DOCX：服务端直接抽取文本
TXT 和 RTF：服务端直接抽取文本

学生作答文件字段名：

answer_file
answer_files
paper_file
paper_files
response_file
response_files
file 或 files

上传限制：

单次请求最多 10 个文件
单个文件最大 20 MB

示例：

{
  "assignment_id": 1620,
  "paper_content": "Dear Mrs Tan,\n\nI am writing to request permission to organize a class recycling drive next Friday...",
  "current_feedbacks": [
    {
      "item": "Content",
      "comment": "作文回应了题目，但结尾请求还可以更明确。",
      "score": 6
    }
  ],
  "style": "Bullet"
}

Multipart 示例：

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"

典型响应：

{
  "task_id": "task_123",
  "status": "PENDING",
  "assignment_id": 1620,
  "model_id": 930,
  "billing_mode": "owner_user",
  "scope": "user",
  "credits_charged": 8
}

`POST /evaluations/one-pass`

不创建新的 assignment，直接提交一次评测。KEATH 会使用一个已有 model 做评分，但本次请求自己带题目、rubric 和学生作答。

这个接口适合外部系统已经知道要使用哪个 KEATH model，但不想先创建 assignment 的场景。

必填字段：

model_id：来自 GET /models 的现有 model ID
学生作答：paper_content 或上传 answer 文件二选一

Rubrics 可以来自：

rubrics：结构化 JSON 数组
rubric_text：rubric 原文
rubric_file / rubric_files：上传 rubric 文件
如果都不传，KEATH 会回退使用所选 model 已保存的 rubrics

题目 / 上下文可以来自：

question_text
question_file / question_files
assignment_desc
如果都不传，KEATH 会回退使用所选 model 已保存的描述

支持直接上传的格式：

题目 / rubric：PDF、图片、DOCX、TXT、RTF
学生作答：PDF、图片、DOCX、TXT、RTF

可选字段：

assignment_name
assignment_desc
cum_method：sum 或 average；不传则沿用所选 model 设置
total_score：rubric 总分提示
specification：解析指令，例如“只使用 Question 2”
style：Bullet、Short、Long，默认是 Bullet
student_id：外部匿名学生 ID
current_feedbacks

示例：

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 "student_id=anon-student-001" \
  -F "specification=只使用 Question 2。" \
  -F "style=Bullet"

典型响应：

{
  "task_id": "public_task_123",
  "status": "QUEUED",
  "stage": "queued",
  "model_id": 930,
  "student_id": "anon-student-001",
  "billing_mode": "owner_user",
  "scope": "user",
  "credits_charged": 0,
  "credit_cost": 8,
  "retryable": false
}

这个接口返回 HTTP 202 Accepted，意思是 KEATH 已经可靠接收任务，不代表评分已经完成。后续请使用返回的公开 task_id 查询状态。

每次业务提交建议带一个唯一的 Idempotency-Key。网络重试时，原请求和相同 key 会返回同一个 task_id；如果同一个 key 换了文本或文件，接口会返回 409，避免误建重复任务。

文件会先持久化，再进入 worker 队列处理。题目、rubric、PDF、图片、DOCX、TXT 和 RTF 的解析都在队列里完成，因此初始 HTTP 请求不需要一直等待几分钟。只有完整结果通过校验后才扣 credits；失败或取消时 credits_charged 仍是 0。

`POST /evaluations/batch`

一次提交 1 到 100 个 one-pass 评测。每个 item 的字段与 /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-student-001",
        "style": "Bullet"
      },
      {
        "model_id": 930,
        "question_text": "写一封信，提出一项学校改进建议。",
        "paper_content": "尊敬的校长，我建议……",
        "student_id": "anon-student-002",
        "style": "Bullet"
      }
    ],
    "callback_url": "https://integration.example.com/keath/results"
  }'

callback_url 可选，但必须是公网 HTTPS 地址。KEATH 会重试回调；集成方仍应保留状态轮询作为兜底。

典型 HTTP 202 响应：

{
  "task_id": "public_batch_123",
  "status": "QUEUED",
  "stage": "queued",
  "count": 2,
  "credits_charged": 0,
  "credit_cost": 16,
  "retryable": false
}

`GET /evaluations/:taskId/status`

在评测还没结束时，轮询一个轻量状态快照。

示例：

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

常见字段：

task_id
status
stage
position
length
cur_step_name
cur_step
total_step
progress
message

status 是兼容旧客户端的大写状态，stage 是更清楚的小写生命周期：

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

建议最初每 3 秒轮询一次，随后逐步退避到最多每 15 秒一次。必须设置最长等待时间，不要写无限循环。

兼容性说明：已有 assignment 使用的 POST /evaluations 仍走旧任务路径，通常从 PENDING 开始，并在任务受理时扣 credits。上面的 202、幂等、持久化队列和完成后扣费只适用于 /evaluations/one-pass 与 /evaluations/batch。

`GET /evaluations/:taskId`

获取一个属于当前 API key 拥有者的评测结果记录。

示例：

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

结果里通常会包含：

汇总分数 score
rubric-level 的 evaluation
当前使用的 rubrics
如果任务未完成，也会带排队 / 进度字段

如果评分失败，任务状态会是 FAILURE。这种情况下 evaluation 里可能会有一个 type: "error" 的条目，错误信息在 comment 里。这个要当成失败任务处理，不要当成正常分数。

典型成功响应：

{
  "task_id": "task_123",
  "status": "SUCCESS",
  "score": 15,
  "evaluation": [
    {
      "item": "Content",
      "score": 7,
      "feedback": "内容相关，但结尾请求还可以更强。"
    },
    {
      "item": "Language",
      "score": 8,
      "feedback": "语言整体清晰，只有少量小问题。"
    }
  ],
  "rubrics": [
    {
      "item": "Content"
    },
    {
      "item": "Language"
    }
  ]
}

`POST /evaluations/:taskId/cancel`

取消一个排队中或进行中的评测任务。

示例：

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

`POST /feedback-rewrite`

这个接口用于把已有 feedback 改成另一种表达形式。

支持的风格：

bullet_points
paragraph
short_sentences

另外还支持：

instruction 自由文本指令
target_item 只重写某一个 criterion

示例：

{
  "style": "bullet_points",
  "instruction": "把内容写得更短一点，更像老师给学生的反馈。",
  "sections": [
    {
      "item": "Content",
      "comment": "Your answer contains relevant ideas but the explanation remains underdeveloped.",
      "score": 7,
      "max_score": 10
    }
  ]
}

`POST /uploads/file`

上传一个本地 PDF / 图片文件，并获得一个可复用的 KEATH 托管 URL。

这个接口不是必须的，但这些场景会很有用：

你的客户端自己拿不到一个临时公开 URL
你想上传一次，之后反复在 questions-ingest-preview 或 rubrics-ingest-preview 里复用返回的 URL
你在做 CLI 或 agent 集成

支持的文件类型：

application/pdf
image/png
image/jpeg
image/webp
image/gif
application/vnd.openxmlformats-officedocument.wordprocessingml.document
application/rtf
text/rtf
text/plain

请求方式：

Content-Type：multipart/form-data
文件字段名：file
每次请求只能传 1 个文件
单个文件最大 20 MB

和预览接口一样，建议客户端显式传 MIME type。如果客户端传的是 application/octet-stream，或者没有带 MIME type，KEATH 会在文件扩展名属于支持格式时尝试自动识别。

示例：

curl -X POST "https://keath.ai/api/keath/public/v1/uploads/file" \
  -H "X-API-Key: kct_your_api_key" \
  -F "file=@./question-pack.pdf;type=application/pdf"

典型响应：

{
  "name": "question-pack.pdf",
  "mime_type": "application/pdf",
  "size": 183245,
  "path": "keath_prod/public_api/99/1746571871000_question-pack.pdf",
  "url": "https://cdn.keath.ai/keath_prod/public_api/99/1746571871000_question-pack.pdf"
}

常见错误说明

常见请求错误：

401：缺少 X-API-Key 或 key 无效
402：credits 不足
403：没有这个 model 的访问权限，或者 organization scope 已经不再有权限
404：assignment、model 或 evaluation 不存在
409：model 还没 ready，或者这个 evaluation 已经不能取消
400：assets 格式错误、文件类型不支持、请求体不合法，或者缺少必需文本 / 上传文件

对于 multipart 请求，如果你要传 assets，它必须是合法的 JSON 数组字符串。对于 multipart 评测请求，如果你要传 rubrics 或 current_feedbacks，它们必须是合法的 JSON 数组字符串。

多模态预览接口已经用线上环境验证过：

JSON assets 指向已上传图片
multipart 直接上传图片
multipart 直接上传题目 PDF
multipart 直接上传 rubric PDF

Public evaluation 相关接口已经覆盖验证：

基于现有 assignment 创建评测任务
通过上传学生作答文件创建评测任务
通过 one-pass 一次性提交 model id、题目、rubric 和学生作答
异步状态轮询
完成后的结果获取
pending 任务取消
organization scope 下的 model 可见性权限检查