班级作文报告

测试中，未正式开放

发版与变更记录见开放平台发版说明。

接口描述

面向 B 端学校 / 教培机构的「班级作文报告」开放接口。合作方在已完成单篇作文批改（或已有人工评分）后，将题目要求与全班学生作文（含每篇得分与教师总评）一次性传入，由平台一次大模型调用产出整份精简学情报告，覆盖：

班级整体概况
量化指标（平均分、分数段分布、四级分层名单）
班级共性问题（含命中学生与原文证据）
班级共性亮点
针对性教学建议
典型范例（最佳 / 最需改进各 1 篇）

报告内容不包含 ECharts 图表配置、不输出练习题；合作方平台可直接基于 JSON 自行渲染。

鉴权方式与作文批改 / 范文生成一致：请求 Header 传 accessToken。

1. 创建任务

请求说明

HTTP 方法：POST
请求地址：

1	https://api.21days.cloud/opi/p/c012/banji_report

Header：accessToken 鉴权

请求 Body

字段	类型	必填	说明
`subject`	string	否	`语文` / `英语`，默认 `语文`
`grade`	string	是	年级名（如 `四年级`）
`title`	string	`title` 与 `topic_content` 至少一项非空	作文标题
`topic_content`	string	同上	题干 / 写作要求
`correct_standard`	string	否	评分标准 / 写作要求补充
`total_score`	int	否	满分，默认 100
`students`	array	是	全班学生作文列表，长度 5~80
`students[].name`	string	是	学生姓名（最长 40 字符）
`students[].score`	int	是	该学生本篇得分（0~200，需 ≤ `total_score`）
`students[].comment`	string	否	合作方对该篇作文的总评，最长 2000 字符
`students[].content`	string	是	学生作文原文（10~3000 字符，纯文本）
`callback_url`	string	否	通知 URL；为空时回退至公司配置
`is_dev`	int	否	0 生产 / 1 测试，默认 0
`transmission`	object	否	透传字段，回调时原样返回

请求示例：

{
  "subject": "语文",
  "grade": "四年级",
  "title": "我的好朋友",
  "topic_content": "请写一位你身边的好朋友，重点写出 1~2 件能体现他/她特点的事。",
  "correct_standard": "中心明确、事例典型、细节具体；不少于 400 字。",
  "total_score": 100,
  "students": [
    {
      "name": "张三",
      "score": 88,
      "comment": "结构完整，事例典型；细节描写还可以更具体。",
      "content": "我的好朋友叫小李……（学生作文原文）"
    }
  ],
  "callback_url": "https://partner.example.com/banji_report/callback",
  "is_dev": 0,
  "transmission": {"class_id": "c001", "homework_id": "h_2026_05_27"}
}

响应说明

字段	类型	说明
code	Number	1=成功，0=失败
msg	String	提示信息
data.id	String	班级报告任务 ID（`banji_report_id`）

成功示例：

1	{"code": 1, "msg": "提交成功", "data": {"id": "SyXczVD"}}

2. 查询结果

HTTP 方法：GET
请求地址：

1	https://api.21days.cloud/opi/p/c012/banji_report/detail?banji_report_id=SyXczVD

缓存：30 秒命中级缓存

data 字段

字段	说明
`banji_report_id`	任务 ID
`version_name`	固定 `banji_report_v1`
`status`	0 未生成 / 1 已完成 / 2 进行中 / -1 失败 / -2 回调失败
`students`	入参快照（单条 content 最长保留 1500 字符）
`report`	学情报告 JSON，见下文
`transmission`	创建任务时传入的透传字段（未传则可能为空）
`note`	失败说明（成功时为 null）

任务完成后会以 POST 方式回调到 callback_url，顶层结构为 {"code":1,"msg":"班级报告生成成功","data":...}；其中 data 与本详情接口一致，并固定包含 version_name=banji_report_v1、banji_report_id。

3. 报告字段说明（`data.report`）

{
  "summary": "本次作文围绕「我的好朋友」展开……",
  "metrics": {
    "total_count": 30,
    "avg_score": 81.7,
    "max_score": 95,
    "min_score": 62,
    "score_distribution": [
      {"range": "90+", "count": 4, "ratio": 0.13},
      {"range": "80-89", "count": 14, "ratio": 0.47},
      {"range": "70-79", "count": 9, "ratio": 0.30},
      {"range": "60-69", "count": 3, "ratio": 0.10},
      {"range": "<60", "count": 0, "ratio": 0.0}
    ],
    "layered_groups": [
      {"level": "优秀", "students": ["张三"], "note": "结构清晰，细节到位。"},
      {"level": "良好", "students": ["李四"], "note": "中心明确，细节有提升空间。"},
      {"level": "合格", "students": ["孙八"], "note": "事例典型性不足。"},
      {"level": "需改进", "students": ["吴十"], "note": "中心不明确。"}
    ]
  },
  "top_issues": [
    {
      "title": "细节描写空泛",
      "hit_students": ["李四", "赵六"],
      "hit_ratio": 0.40,
      "evidence": "他是个好朋友，对我很好",
      "explanation": "学生倾向用概括性语言代替具体场景。",
      "fix_advice": "要求每一段至少出现 1 个具体动作或对话。"
    }
  ],
  "top_strengths": [
    {"title": "事例选取典型", "students": ["张三"], "example": "下雨天他默默把伞偏向我这边……"}
  ],
  "teaching_suggestions": [
    {"focus": "细节描写", "action": "用「定格一个画面」练习……", "expected_outcome": "下次作文中具体细节占比提升。"}
  ],
  "model_examples": [
    {"type": "best", "student": "张三", "snippet": "……", "why": "中心突出，细节具体。"},
    {"type": "weak", "student": "吴十", "snippet": "……", "why": "事例缺乏典型性。"}
  ]
}

字段稳定性：summary / metrics / top_issues / top_strengths / teaching_suggestions / model_examples 及 metrics 内子字段名为稳定契约；score_distribution 固定 5 档顺序，layered_groups 固定 4 级。

4. 计费

班级作文报告固定 1 元 / 次（约等于普通版作文批改 5 次）：

优先扣「普通版次数」余额：每次扣 5 次。
次数不足时扣「金额」余额：每次扣 100 分（1 元）。
余额不足返回 code=10001，任务不会创建。

独立于作文批改 / 范文 / 小练笔计费，不受 is_pro / subject / version 影响。

5. 注意事项

单次 5~~80 篇学生作文；单条 content 10~~3000 字符，超长截断。
回调重试 10 次、间隔 3 秒；失败写 status=-2。
transmission 透传缓存 24 小时。
运维补发 / 重启接口（/api/open/p/c012/banji_report/...）仅供内部使用，合作方无需对接。

专项批改-系列：