创建小练笔批改

接口描述

  • 提交一段“小练笔/微写作”进行后台批改，针对 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 是 评分明细（示例：['切题','目标达成','内容具体','语言表达','结构清楚']）；为空时使用平台默认 5 个维度
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 是 评分宽松度（仅英语 v4 生效），可选值：lenient / normal / strict
transmission Object null 是 透传字段，平台不会修改，回调结果 data.transmission 原样返回

响应说明

字段 类型 必选 示例 解释
code Number 是 1 1=正常，0=异常，-1=未登录
msg String 否 “提交成功” 提示信息
data object 否 {“id”:”SyXczVD”} 核心数据（小练笔任务 ID）
  • 提交成功后会立即返回任务 ID，后台异步执行批改流程。
  • 批改完成会以 POST 方式回调到 callback_url，回调 Body 结构与大作文完全一致，仅 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 次；
    • 排查/对账以查询接口为辅，实时展示以回调为准。