小练笔批改

接口描述

  • 提交一段“小练笔/微写作”进行后台批改，针对 1~3 个训练目标输出短、准、可执行的反馈。
  • 支持两种作答模式：
    • 文本模式：直接传 content。
    • 图片模式：传 images，平台先 OCR 识别再批改。

注意事项

  1. AI 评分具有主观性，仅供参考。
  2. 文本模式下 content 长度需在 10~3000 字之间，过长建议改用大作文批改接口（《创建作文批改》）。
  3. 图片模式下每张图片需提供 url / width / height，单次最多 10 张，且图片需公开可访问；格式 jpg/jpeg/png/bmp，单图 ≤ 4M，最长边 ≤ 4096px。
  4. title 与 topic_content 不能同时为空。
  5. 与大作文一致，平台会异步执行批改，完成后通过 callback_url 推送结果；详细字段定义见《发送作文批改结果》。
  6. 失败回调中可能携带与大作文相同的业务错误码（如 1000 错别字过多、1001 OCR 识别失败），详见《开放平台说明》。

请求说明

  • HTTP 方法：post
  • 请求地址
    1
    https://api.21days.cloud/opi/p/c012/micro_writing
  • URL 参数：无
  • Header：accessToken 鉴权
  • Body：
字段名称 类型 默认值 是否可选 说明
subject String ‘语文’ 否 学科，可选值：’语文’ 或 ‘英语’
total_score Number 100 否 总分（建议固定 100，按比例换算客户端实际分值）
words_count Number 300 是 字数要求（小练笔上限 3000 字；同时作为内部最大字数边界）
grade String ‘四年级’ 否 适用年级（如 ‘三年级’、’初二’）
writing_type String ‘小练笔’ 是 文体类别，小练笔接口建议直接使用 ‘小练笔’，也可填写具体片段类型（如 ‘叙事片段’、’写景片段’）
title String ‘’ 是 题目，留空时必须提供 topic_content
topic_content String ‘’ 是 题干/写作要求，描述本次小练笔的情境与限制
correct_standard String ‘’ 是 评分标准/训练目标，作为本次小练笔的核心评判依据；为空时按题干达成度批改
content String ‘’ 是 学生小练笔文本，文本模式必填，长度 10~3000 字
images Array null 是 学生作答图片列表（示例：[{"url":"...","width":864,"height":1920}]），图片模式必填；要求与大作文一致
topic_content_images Array null 是 题干图片列表（如需保存题干配图）
item Array null 是 批改选项（与大作文一致，可包含评分、评语、亮点、不足和建议等）
score_items Array null 是 评分维度配置（非批改结果）。见下文「score_items 说明」；为空时使用平台默认 5 个维度，总分 100
is_pro Number 0 是 是否使用 pro 版
callback_url String ‘’ 是 回调 URL，留空时使用合作方在平台预配置的回调地址
is_dev Number 0 是 是否使用开发环境回调地址
version Number 1 是 版本号，含义与大作文一致；平台会根据 subject + version 生成 version_name（如 cn_v1、en_v1）
strictness String null 是 评分宽松度，可选值：lenient / normal / strict（默认 normal）。仅当 subject=英语 且 version=4，或 subject=语文 且 version=2 时生效；其它版本忽略
transmission Object null 是 透传字段，平台不会修改，回调结果 data.transmission 原样返回

score_items 说明

创建任务时的 score_items 与回调/查询结果中 pigai.score_items 字段名相同，但含义与结构不同，仅通过维度名称对应。

入参（创建任务）：定义「评哪些维度」

兼容大作文接口，类型为 Array，常见两种写法：

写法 1：只传维度名

1
"score_items": ["切题", "目标达成", "内容具体", "语言表达", "结构清楚"]

不传 score_items 时，平台使用以下默认 5 个维度，各项满分相加为 100：

维度名 满分 说明
切题 20 是否回应题干与写作情境
目标达成 30 是否完成本次训练目标（权重最高）
内容具体 20 内容是否有细节、有画面，避免空泛
语言表达 20 语句是否通顺，表达是否贴合年级
结构清楚 10 片段层次是否清楚，前后是否连贯

仅传维度名、未指定 max_score 时，平台按 total_score ÷ 维度数 均分每项满分（如 5 项且 total_score=100 时，每项 20 分），不会自动套用上表 20/30/20/20/10 的权重。

写法 2：带满分与说明

1
2
3
4
"score_items": [
  { "name": "切题", "max_score": 20, "rubric": "是否回应题干" },
  { "name": "目标达成", "max_score": 30, "rubric": "是否完成训练目标" }
]

对象字段兼容 name / item / dimension（维度名），max_score / score（该项满分），rubric / reason（评分说明）。未传 total_score 时，平台会按各维度 max_score 之和计算总分。

返回（pigai.score_items）：各维度实际得分

批改完成后，回调与查询接口在 pigai.score_items 中返回评分明细，结构固定为 { item, score, reason }：

字段 类型 说明
item string 维度名称，须与创建时定义的维度一致，不得增删
score int 该项实际得分，应在对应维度满分范围内
reason string 该项评分解析，约 20~60 字

示例：

1
2
3
4
"score_items": [
  { "item": "目标达成", "score": 25, "reason": "能写出心理变化，事情经过还可以更具体。" },
  { "item": "切题", "score": 18, "reason": "能围绕题干情境展开。" }
]

pigai.score / pigai.total_score 为总分，默认满分 100，会被限制在 0 ~ total_score 范围内。返回中不会回显入参里的 rubric、max_score；若客户端需要展示每项满分，请在创建时自行记录配置。

响应说明

字段 类型 必选 示例 解释
code Number 是 1 1=正常，0=异常，-1=未登录
msg String 否 “提交成功” 提示信息
data object 否 {“id”:”SyXczVD”} 核心数据（小练笔任务 ID）
  • 提交成功后会立即返回任务 ID，后台异步执行批改流程。
  • 批改完成会以 POST 方式回调到 callback_url，回调 Body 结构与大作文一致：任务 ID 位于 data.zuowen_id，并会按 subject + version 返回 data.version_name（如 cn_v1）。仅 pigai / pangpi / runse 内容为小练笔语义；详情见《发送作文批改结果》。
  • 也可以通过 查询小练笔批改详情 接口主动拉取批改结果。

文本模式请求示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "subject": "语文",
  "total_score": 100,
  "words_count": 300,
  "grade": "四年级",
  "writing_type": "小练笔",
  "title": "我的心儿怦怦跳",
  "topic_content": "围绕一次紧张、激动或害怕的经历写一段话。",
  "correct_standard": "把事情经过写清楚，并写出心理变化",
  "content": "今天上台演讲的时候，我的心怦怦直跳……",
  "score_items": ["切题", "目标达成", "内容具体", "语言表达", "结构清楚"],
  "callback_url": "https://partner.example.com/callback",
  "transmission": {
    "student_id": "s001",
    "homework_id": "h001"
  }
}

图片模式请求示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "subject": "语文",
  "total_score": 100,
  "words_count": 300,
  "grade": "四年级",
  "writing_type": "小练笔",
  "title": "我的心儿怦怦跳",
  "topic_content": "围绕一次紧张、激动或害怕的经历写一段话。",
  "correct_standard": "把事情经过写清楚，并写出心理变化",
  "images": [
    {
      "url": "https://example.com/student-writing-1.jpg",
      "width": 1080,
      "height": 1440
    }
  ],
  "callback_url": "https://partner.example.com/callback"
}

成功响应示例

1
2
3
4
5
6
7
{
  "code": 1,
  "msg": "提交成功",
  "data": {
    "id": "SyXczVD"
  }
}
  • 联调建议：
    • 服务端需确保 callback_url 在 3 秒内返回 HTTP 200；
    • 平台会按约 3 秒一次的频率最多重试 10 次；
    • 排查/对账以查询接口为辅，实时展示以回调为准。