AI Teacher 智能作业批改系统 API 文档

一、概述

本 API 文档描述了 AI Teacher 产品后台服务提供的智能作业批改接口，用于自动识别、批改学生作业并提供详细的分析结果。

版本: v1

总览

统一响应格式

{
  "success": true,
  "message": "操作成功",
  "data": {}
}

错误响应示例

{
  "success": false,
  "message": "请求参数缺失：[参数名]"
}

模块划分

1. 题目解题模块 - 单道题目智能解题
2. 作业批改模块 - 完整作业智能批改
3. 课堂练习模块 - 课堂练习快速批改
4. 页面评分模块 - 页面批量评分
5. 结构化提取模块 - 题目结构化信息提取
6. 整页作业批改模块 - 整页作业自动切题并批改
7. 试卷切题模块 - 试卷题目位置提取

二、API 接口

1. 单题解题接口

接口地址： POST /v1/solve-question/

接口用途： 智能解答单道题目，支持图片识别和文本分析，返回结构化解析。

鉴权： 根据配置决定

请求参数

响应示例

{
  "success": true,
  "message": "解题完成",
  "data": {
    "analysis": "先将方程两侧同时乘以 2，化简后得到 ..."
  }
}

响应字段说明

2. 作业批改接口

接口地址： POST /v1/homework/

接口用途： 对学生提交的作业图片进行解析、批改与得分计算。

鉴权： 根据配置决定

请求参数

响应示例

{
  "success": true,
  "message": "作业批改完成",
  "data": {
    "type": "解答题",
    "question_text": "请计算 3x + 5 = 20 的解。",
    "answer": "x = 5",
    "analysis": "将等式移项得到 3x = 15，解得 x = 5。",
    "corrections": "答案正确，得分 10 / 10",
    "totalScore": 10,
    "score": 10,
    "points": [
      {"pointNo": ["MATH-EQ-001", "MATH-EQ-002"], "reason": ["掌握一次方程解法", "理解移项规则"]}
    ],
    "externals": {
      "boxes": []
    }
  }
}

响应字段说明

3. 课堂练习批改接口

接口地址： POST /v1/classwork/

接口用途： 结合题目与学生答案（图片或文字），给出课堂练习批改结果，适合课堂即时反馈场景。

鉴权： 根据配置决定

请求参数

响应示例

{
  "success": true,
  "message": "作业批改完成",
  "data": {
    "corrections": "答案思路清晰，最终结论正确",
    "score": 8,
    "totalScore": 10,
    "answer": "学生书写的答案文本"
  }
}

响应字段说明

4. 页面批量评分接口

接口地址： POST /v1/page/grading/

接口用途： 批量评分多个页面，自动识别题目并批改。

鉴权： 根据配置决定

请求参数

响应示例

{
  "success": true,
  "message": "页面批改完成",
  "data": {
    "questions": [
      {
        "question_id": "1",
        "question_type": "选择题",
        "question_content": "下列哪个是质数？\\n\\nA. 4\\nB. 6\\nC. 7\\nD. 9",
        "page_number": 1,
        "student_answer": "C",
        "detailed_feedback": "答案正确。质数是指只能被1和自身整除的大于1的自然数。7是质数。",
        "bbox": [100, 200, 300, 250],
        "is_empty": false,
        "is_correct": true
      }
    ]
  }
}

响应字段说明

5. 结构化提取接口

接口地址： POST /v1/page/structured/

接口用途： 提取题目的结构化信息，用于题库录入或题目分析。

鉴权： 根据配置决定

请求参数

响应示例

{
  "success": true,
  "message": "结构化提取完成",
  "data": {
    "type": "选择题",
    "question_text": "下列哪个是质数？\n\nA. 4\nB. 6\nC. 7\nD. 9"
  }
}

响应字段说明

6. 整页作业批改接口

接口地址： POST /v1/page/homework/

接口用途： 对整页作业图片进行自动切题并批改，支持多页图片。

鉴权： 根据配置决定

请求参数

响应示例

{
  "success": true,
  "message": "页面评分完成",
  "data": {
    "results": [
      {
        "type": "选择题",
        "question_text": "下列哪个是质数？\\n\\nA. 4\\nB. 6\\nC. 7\\nD. 9",
        "answer": "C",
        "analysis": "质数是指只能被1和自身整除的大于1的自然数。7是质数。",
        "corrections": "答案正确",
        "totalScore": 5,
        "score": 5,
        "points": [],
        "externals": {"boxes": []}
      }
    ]
  }
}

响应字段说明

注意事项

• files 和 urls 必须提供其中一个，如果两者都提供，全部使用
• 接口会自动使用 YOLO 模型进行切题，然后对每道题进行批改

7. 试卷切题接口

接口地址： POST /v1/page/split/

接口用途： 从多页试卷图片中提取题目位置信息，不包含批改功能。

鉴权： 根据配置决定

请求参数

响应示例

{
  "success": true,
  "message": "试卷切题完成",
  "data": {
    "questions": [
      {
        "question_id": "1",
        "image_bbox": [
          {
            "page": 1,
            "position": "left",
            "location": [100, 200, 300, 400]
          },
          {
            "page": 1,
            "position": "right",
            "location": [500, 200, 700, 350]
          }
        ]
      },
      {
        "question_id": "2",
        "image_bbox": [
          {
            "page": 1,
            "position": "left",
            "location": [100, 450, 300, 650]
          }
        ]
      }
    ]
  }
}

响应字段说明

注意事项

• files 和 urls 必须提供其中一个，如果两者都提供，全部使用
• 本接口仅返回题目位置信息，不进行批改

三、错误码说明

四、使用示例

Python 调用示例

import requests

# /v1/homework/ 批改示例
homework_url = "http://localhost:8080/v1/homework/"
with open("homework.jpg", "rb") as fp:
    files = {"file": ("homework.jpg", fp, "image/jpeg")}
    data = {
        "subject": "数学",
        "grade": "三年级",
        "semester": "上册",
        "book_id": "1001",
        "mode": "accuracy",
    }
    response = requests.post(homework_url, files=files, data=data, timeout=30)
    response.raise_for_status()
    payload = response.json()
    if payload.get("success"):
        print("批改得分:", payload["data"]["score"])
    else:
        raise RuntimeError(payload.get("error", "批改失败"))

# /v1/solve-question/ 求解示例
solve_url = "http://localhost:8080/v1/solve-question/"
solve_data = {
    "subject": "数学",
    "grade": "三年级",
    "mode": "speed",
    "url": "https://example.com/question.jpg",
}
solve_resp = requests.post(solve_url, data=solve_data, timeout=30)
solve_resp.raise_for_status()
print("题目解析:", solve_resp.json().get("data", {}).get("analysis"))

# /v1/classwork/ 课堂练习示例
classwork_url = "http://localhost:8080/v1/classwork/"
classwork_data = {
    "subject": "英语",
    "grade": "三年级",
    "question": "data:image/png;base64,...",
    "answer_text": "I am a student"
}
classwork_resp = requests.post(classwork_url, data=classwork_data, timeout=30)
print("课堂练习得分:", classwork_resp.json().get("data", {}).get("score"))

cURL 示例

# 单题解题
curl -X POST "http://localhost:8080/v1/solve-question/" \
  -F "url=https://example.com/question.jpg" \
  -F "subject=数学" \
  -F "grade=三年级" \
  -F "mode=speed"

# 作业批改
curl -X POST "http://localhost:8080/v1/homework/" \
  -F "file=@homework.jpg" \
  -F "subject=数学" \
  -F "grade=三年级" \
  -F "semester=上册" \
  -F "book_id=1001" \
  -F "mode=accuracy"

# 课堂练习
curl -X POST "http://localhost:8080/v1/classwork/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "subject=英语&grade=三年级&question=data:image/jpeg;base64,...&answer_text=I am a student"

# 页面批量评分
curl -X POST "http://localhost:8080/v1/page/grading/" \
  -F "files=@page1.jpg" \
  -F "files=@page2.jpg" \
  -F "subject=数学" \
  -F "grade=三年级" \
  -F "mode=auto"

# 结构化提取
curl -X POST "http://localhost:8080/v1/page/structured/" \
  -F "file=@question.jpg"

# 整页作业批改
curl -X POST "http://localhost:8080/v1/page/homework/" \
  -F "files=@page1.jpg" \
  -F "files=@page2.jpg" \
  -F "subject=数学" \
  -F "grade=三年级" \
  -F "mode=auto"

# 试卷切题
curl -X POST "http://localhost:8080/v1/page/split/" \
  -F "files=@page1.jpg" \
  -F "files=@page2.jpg"

五、支持的科目与年级

支持的科目

• 数学、英语、物理、化学、语文
• 生物、历史、地理、政治（道法）
• 其他需要支持的学科

支持的年级

• 小学：一年级至六年级
• 初中：初一至初三
• 高中：高一至高三

六、注意事项

1. 图片质量要求： 建议上传清晰图片，分辨率不低于 1024×768，文件大小控制在 10MB 以内
2. 网络可达性： 使用 URL 方式时需确保图片链接可直接访问
3. 超时设置： 建议调用端设置不低于 30 秒的请求超时
4. 错误处理： 接口返回 success=false 时会在 message 字段提供可读的错误信息
5. book_id 参数： 支持字符串格式，单个值如 1001，多个值用逗号分隔如 1001,1002,1003