学生学习测试自用网站接口

整套接口围绕「练习—作答—判分—回顾」四步循环设计，调用方是我自己的练习页面与命令行脚本， 因此结构上尽量保持扁平：一次请求完成一件事，返回体里直接带上判分结果与解析。

适用场景

专项刷题前的知识点摸底、单元复习后的自测、考前限时模拟，以及为自己的错题本补充题目来源。 这些都是个人学习流程里的固定环节，接口负责把其中重复的动作自动化。

1. 取得访问凭据 凭据用于识别调用方身份，每个凭据可单独设置题量上限与有效期。
2. 确认基础地址与协议 接口基址为 https://api.hatsumi.fun/v1，全部走 HTTPS，仅接受 JSON 请求体。
3. 放置请求头 请求头携带 Authorization: Bearer $HATSUMI_TOKEN，并声明 Content-Type: application/json。
4. 本地验证连通性 先调用健康检查接口确认服务可达，再进入业务接口的联调。

下面给出一段创建测试会话的调用写法，以及等价的脚本版本，按手头工具挑一种即可。

# 创建一次练习会话：从指定题库抽取 10 题
curl -X POST https://api.hatsumi.fun/v1/sessions \
  -H "Authorization: Bearer $HATSUMI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bank_id":"math-g7-algebra","count":10,"mode":"practice"}'

等价的脚本版本，可直接放进练习页面的加载逻辑里：

const token = process.env.HATSUMI_TOKEN;

const res = await fetch("https://api.hatsumi.fun/v1/sessions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + token,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ bank_id: "math-g7-algebra", count: 10, mode: "practice" })
});

if (!res.ok) {
  throw new Error("请求失败：HTTP " + res.status);
}

const { session_id, questions } = await res.json();
console.log(session_id, questions.length);

返回体结构统一为 code / message / data 三段：

{
  "code": 0,
  "message": "ok",
  "data": {
    "session_id": "s_2026_0418_7f3c9a",
    "bank_id": "math-g7-algebra",
    "count": 10,
    "expires_at": "2026-04-18T21:30:00+08:00"
  }
}

全部路径均以基址 https://api.hatsumi.fun/v1 开头，限频按单个凭据计算。

题库标识约定

题库标识采用「科目-年级-章节」的写法，例如 math-g7-algebra 表示七年级代数， physics-g8-optics 表示八年级光学。做题时先查题库列表，再拿标识去抽题，避免写死。

业务错误一律通过 code 字段表达，HTTP 状态码只反映传输与鉴权层面。

判分结果字段

提交作答后返回的 data 中包含 correct、score、 answer_key 与 explain 四个字段， 分别表示是否答对、本次得分、标准答案与解析。主观题按关键词命中比例给分，命中情况会一并写入 explain。

接口相关问题、题库纠错或使用建议，欢迎通过邮箱联系我；涉及账号与凭据的事项请直接说明域名 hatsumi.fun 与调用时间，便于我定位日志。