从旧接口迁移

摘要

旧文档使用的是：

• Header：X-TOKEN-KEY
• 路径：/api/open/evaluation/*

现在的 Public API 使用的是：

• Header：X-API-Key
• 路径：/api/keath/public/v1/*

对照关系

使用方式的变化

旧的评测流程：

1. 直接发送文本内容和 rubrics
2. 发起评测
3. 轮询结果

现在 public v1 的评测流程：

1. 先通过 GET /models 拿到 model_id
2. 用 POST /assignments 创建学生 assignment；如果不想创建 assignment，就走 POST /evaluations/one-pass
3. 用返回的 assignment_id 调 POST /evaluations 提交作文文本或作答文件
4. 用 GET /evaluations/:taskId/status 轮询状态
5. 用 GET /evaluations/:taskId 拿最终结果

可靠异步评测

POST /evaluations/one-pass 和 POST /evaluations/batch 走新的可靠异步链路，接口会返回 HTTP 202 Accepted 和公开的 task_id。请传 Idempotency-Key；网络重试时，相同请求会拿到同一个任务，不会重复创建。batch 一次可提交 1-100 项。

任务会依次经过 QUEUED、UPLOADING、SUBMITTED、PROGRESS，最终进入 SUCCESS、FAILURE 或 CANCEL。只有完整结果通过校验后才扣 credits。轮询必须设置总超时和退避间隔，不要写无限循环。

已有 assignment 使用的 POST /evaluations 为了兼容仍走旧任务链路，通常从 PENDING 开始，并在任务被接受时扣 credits。不要把它的初始状态和扣费时机套用到 one-pass 或 batch。

如果你需要先建模型，那么新建模型流程是：

1. 先解析题目资源
2. 再解析 rubric 资源
3. 确认预解析结果
4. 用 POST /models 创建 marking model
5. 后续用这个 model 创建 assignment 或 one-pass evaluation

输入方式的变化

当前 public API 在建模阶段是明确支持多模态的：

• 支持 PDF
• 支持图片
• 支持 direct upload
• 支持已有公开 URL
• 支持用 specification 指定只解析某一个题目或 rubric

当前 public v1 的评测接口支持文本和作答文件上传：

• 通过 paper_content 传作文文本
• 通过 assignment_id 指向现有学生 assignment
• 可选传 current_feedbacks
• 可选传 style，支持 Bullet、Short、Long

POST /evaluations 已支持 PDF / 图片 / DOCX / TXT / RTF 作答文件。

客户端需要改什么

请把客户端改成：

1. 用 X-API-Key 替换 X-TOKEN-KEY
2. 用 /api/keath/public/v1/* 替换 /api/open/evaluation/*
3. 把 model_id 理解成 GET /models 返回的评分模型 ID
4. 把 assignment_id 理解成 POST /assignments 返回的学生作业 ID，或产品 assignment 详情 URL 里的 ID
5. 评测时把作文文本或作答文件提交到 POST /evaluations
6. 用 GET /evaluations/:taskId/status 轮询任务状态
7. 用 GET /evaluations/:taskId 获取最终结果
8. 如果你还需要通过 API 建模，本地 PDF / 图片走 multipart/form-data
9. 已有公开文件 URL 走 assets[]
10. 如果要混合上传和 URL，就用 multipart，再把 assets 作为 JSON 字符串一起发
11. 如果你使用 organization scope，请把它理解成更宽的 model 可见性，而不是共享扣费。credits 仍然扣在 key 拥有者身上。

建议验证

• 先重新测试 GET /credits
• 再重新测试 GET /models
• 用 POST /assignments 创建 assignment
• 提交一篇作文到 POST /evaluations
• 轮询 GET /evaluations/:taskId/status
• 获取最终结果 GET /evaluations/:taskId
• 如果还需要建模，再发一个 PDF 到 questions-ingest-preview
• 再发一个 rubric 文件到 rubrics-ingest-preview
• 确认客户端代码里已经没有 X-TOKEN-KEY