发送作文批改结果

一句话说明

批改完成后，平台向你配置的回调地址发送 POST JSON。
你方在约 3 秒内回 HTTP 200；其他状态视为未收到，平台会按约 3 秒间隔最多重试 10 次。

创建入口见 创建作文批改。
未收到回调时可用 查询作文详情 补拉同一套 data。
发版变更见 开放平台发版说明。

你会收到什么

顶层结构固定如下：

1
2
3
4
5
{
  "code": 1,
  "msg": "批改成功",
  "data": { }
}
顶层字段 说明
code 1=本篇批改成功拿到结果；0=失败
msg 简要说明
data 成功时为完整结果；失败时至少含 zuowen_id，可能含 error_code

下文列出的字段全部位于 data 内。不同版本字段会有差异，以版本文档为准。

data 公共字段

字段 类型 说明
zuowen_id String 作文任务 ID（与创建返回的 data.id 对应）
version_name String 版本名，如 cn_v1、en_v4
status Number 1 表示本篇已完成（详情接口更常看到）
title String 作文标题
content String 纠错前正文（纯文本）
correct_words String 纠错后正文
ocr_text Object 识别结果（含图片与文字坐标，见下）
wrong_words Object 错别字信息；部分定制版为空
pangpi Object / Array 旁批；定制版可能为 []
pigai Object 批改与评分主体（随版本变化最大）
runse Object 润色稿；定制版可能为 {}
materials_push Object / null 素材推送；默认 null
transmission Object 创建时透传字段，原样返回
note Object / null 备注；未作答等场景可能带说明信息

version_name 怎么读

规则 示例
语文 + version cn_v1 / cn_v2 / cn_v3 …
英语 + version en_v1 / en_v2 / en_v3 / en_v4 …
范文接口 fanwen_v1（独立接口）
班级报告 banji_report_v1（独立接口）

成功时：重点看哪些块

你要展示的 看哪里 备注
总分 / 分项 pigai 标准版常见 score + score_items；高级评分常见 score + score_detail
总评 / 建议 pigai.comment 等 随创建时 item 勾选出现
旁批 pangpi.commit_items 含句子与坐标，便于原图标注
错别字 wrong_words 下标 → 错误类型与建议字
润色稿 runse V3 另有 runse.versions 两档
原文 content / correct_words 纠错前 / 后

各版本 pigai / runse 细节见对应版本文档。

ocr_text（识别结果）

用于还原版面或抽取纯文本。层级从外到内：

  1. ocr_text.img_list：多张图片
  2. 每张图的 columns：多栏
  3. 每栏 column：二维数组（行 → 字）
  4. 每个字形如 ["长", left, top, width, height]

阅读顺序建议：图片 → 列 → 行 → 字，按坐标拼接正文。

短示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "img_list": [
    {
      "url": "https://example.com/page1.jpg",
      "width": 864,
      "height": 1920,
      "columns": [
        {
          "left": 40,
          "right": 820,
          "column": [
            [["今", 50, 80, 40, 48], ["天", 95, 80, 40, 48]]
          ]
        }
      ]
    }
  ]
}

部分版本在特殊识别场景下，ocr_text 可能带 vision_only=true：此时旁批坐标与逐字错别字可能为空，但评分 / 批改 / 润色仍可能正常返回（见 语文 V3）。

pangpi（旁批）

字段 说明
commit_items 旁批条目数组
commit_total 旁批总结

单条 commit_items 常见字段：

字段 说明
commit 旁批文字
good_or_bad good / bad
origin_sentence 纠错后的句子
matched_sentence 纠错前的句子
position 在纯文本中的起始位置
line 页-列-行坐标，用于原图高亮

wrong_words（错别字）

对象：key 为错误下标字符串，value 为长度为 6 的数组：

下标 含义
0 类型：i 多写 / d 少写 / m 写错
1 / 2 正文起止位置
3 原文字
4 建议正确文字
5 图片坐标 [页, x, y, w, h]

短示例：

1
2
3
{
  "83": ["m", 83, 84, "在", "再", [0, 489, 512, 61, 57]]
}

pigai（批改主体，通用字段）

不同版本字段不同。标准语文常见字段如下（是否出现取决于创建时 item）：

字段 说明
score 总分
score_items 分项：item / score / reason
comment 总评
highlights / suggestions 亮点 / 建议
title / first_p / last_p 改标题 / 开头 / 结尾
modify / paragraphs / questions 等 改错、段评、提问等

高级评分版（如语文 V2、英语 V4）用 score_detail 替代或补充 score_items，见各版本文档。

runse（润色）

字段 说明
title 润色后标题
content 润色后正文（可用换行分段）
explain 改了什么、为什么
versions 仅语文 V3：额外 2 篇（轻润色、大改写）；默认顶层字段为中度润色

materials_push（可选）

仅当创建时 subject=语文 且 item 含 素材推送 时，可能返回；否则为 null，不影响成功判定。

1
2
3
4
5
6
7
8
9
10
11
12
{
  "weakness_summary": "本次作文主要弱点：…",
  "materials": [
    {
      "category": "典例",
      "source": "出处",
      "content": "素材正文",
      "target_weakness": "针对的弱点",
      "usage_hint": "使用建议"
    }
  ]
}

category 常见：典例 / 名著 / 金句。出处给不出可核验信息时可能为空字符串。

未作答场景（仍算成功）

创建时传了非空 continuation_text，且判定学生几乎未作答时：

字段 值
顶层 code 1（成功，不是失败）
pigai.score 0
pigai.no_answer true
pangpi / runse 空

按「未作答」展示，不要按 error_code 失败处理。

失败回调

字段 说明
顶层 code 0
msg 失败原因摘要
data.zuowen_id 任务 ID
data.error_code 可选：1000 / 1001 / 1002
error_code 含义 建议
1000 错别字过多 换清晰稿件后重新提交
1001 识别失败 / 字过少 检查图片后重试
1002 越权指令 清理原文后重试；确认误判可带 skip_injection_check=1

成功回调短示例（结构示意）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "code": 1,
  "msg": "批改成功",
  "data": {
    "zuowen_id": "u3EDmPW",
    "version_name": "cn_v1",
    "status": 1,
    "title": "难忘的一天",
    "content": "今天是我难忘的一天……",
    "correct_words": "今天是我难忘的一天……",
    "wrong_words": {},
    "pangpi": {
      "commit_items": [],
      "commit_total": ""
    },
    "pigai": {
      "score": 82,
      "score_items": [
        { "item": "内容", "score": 85, "reason": "事情完整，细节可再丰富" }
      ],
      "comment": "能把事情写清楚，中间可再补具体动作或对话。"
    },
    "runse": {
      "title": "难忘的一天",
      "content": "……",
      "explain": "1. …"
    },
    "materials_push": null,
    "transmission": { "homework_id": "hw_001" }
  }
}

完整字段含义与版本差异，请对照学科版本文档；无需依赖超长原始 dump。

你方应如何回复

  • 只需保证 HTTP 状态码 200
  • Body 可不校验；可自定义返回如 { "code": 1, "msg": "ok" } 便于自查

对接检查清单

  1. 回调服务是否公网可达，并在约 3 秒内回 200
  2. 是否先看顶层 code，再解析 data
  3. 是否用 version_name 分支解析不同版本的 pigai
  4. 是否保存 zuowen_id，以便详情接口补拉
  5. 未作答（no_answer=true）与失败（error_code）是否分开处理
  6. 是否原样保存 transmission 做业务关联

关联文档

主题 文档
创建接口 创建作文批改
补拉详情 查询作文详情
错误码 开放平台说明
接口索引 接口总览索引