特别版简易评分（V5）

指定客户专用能力，不作为通用对接方案。

接口行为、返回字段与计费可能随业务调整。未开通本能力的合作方请勿调用；新业务请优先对接标准批改版本。

一句话说明

用同一个创建接口，传 version=5，对学生作文做快速打分 + 短评。
适合只要分数和简短评语、不需要旁批/润色/错别字校对的场景。

学科	结果里的版本名
语文	cn_v5
英语	en_v5

---

你会得到什么

完成后（回调或详情查询）主要看这些：

你要的	在哪里	说明
总分	pigai.score	满分等于创建时的 total_score（默认 100）
分项分	pigai.score_items	每个维度：名称、分数（0~100）、简短理由
短评	pigai.comment	中文，约 30~80 字（英语作文的评语也是中文）
作文正文	content	见下文「结果里的 content」

本版不会返回：旁批、错别字校对、润色、详细改写、素材推送等。对应字段一般为 pangpi=[]、runse={}、wrong_words 为空。

评分由 AI 完成，结果仅供快速阅卷参考。

---

怎么提交作文

创建接口与大作文相同：POST /p/c012/create_zuowen，**version 固定传 5**。

提交成功后立刻拿到作文 ID；评分在后台完成，再通过回调推送（也可用详情接口查询）。

两种提交方式（二选一）

方式	传什么	说明
图片	images	学生作文原图；须含 url、width、height；图片须公网可访问
纯文本	content	学生作文正文；去首尾空白后 10~8000 字

都传时：优先按图片评分，忽略文本。
其它标准版本仍要求必须传图片；只有本版（及同类定制版）支持纯文本。

结果里的 content（作文正文）

请求里的 content 和结果里的 content 名字相同，含义不同，请按下面理解：

你怎么提交的	结果里 content 是什么
纯文本	就是你提交的那篇正文
图片，且未开回传原文	一般为空字符串
图片，且 return_content=1	平台从图片中识别出的作文正文（语文、英语均可）

关于 return_content：

• 默认 0：不回传图片原文（只返回分数和短评）。
• 传 1：图片提交时生效（语文、英语均可）；纯文本提交时传了也会被忽略（纯文本本身就会回传你提交的正文）。
• 开启后若识别不成功，分数和短评仍会正常返回，此时 content 可能仍为空。
• 是否开启不额外计费。

---

计费

每次成功创建并扣费后：

扣费方式	扣减
次数余额（balance / pro_balance）	0.3 次
金额余额（amount，单位分）	6 分（0.06 元）

余额不足时，创建接口会直接失败（如 code=10001，提示余额不足），不会进入评分。

---

请求字段

• 方法：POST
• 地址：https://api.21days.cloud/opi/p/c012/create_zuowen
• Header：accessToken（见 开放平台说明）

下表只列本版对接时需要关心的字段。鉴权、回调地址、透传字段等与大作文一致，见 创建作文批改。

字段	类型	默认	必填	说明
subject	String	语文	是	语文 或 英语
version	Number	—	是	固定传 5
grade	String	四年级	是	年级，如 四年级、初二
title	String	''	条件	作文题目；与 topic_content 不能同时为空
topic_content	String	''	条件	题干 / 写作要求；与 title 不能同时为空
total_score	Number	100	否	作文满分；总分按此换算
images	Array	—	条件	与 content 二选一，见上表
content	String	—	条件	与 images 二选一；纯文本正文 10~8000 字
return_content	Number	0	否	1=需要回传图片识别出的正文；图片提交时生效（语文/英语），见上文
score_items	Array	见下节	否	要评哪些维度；不传则用默认
correct_standard	String	''	否	自定义评分标准；有则参与阅卷参考
callback_url	String	''	否	本次回调地址；空则用账号预配置地址
is_dev	Number	0	否	1=走开发回调地址（仅在未传 callback_url 时）
transmission	Object	—	否	透传对象，回调时原样带回，便于对账

可不传、传了也无影响的字段

字段	说明
words_count	可不传。本版评分不按字数要求扣分或卡控，传了只落库，不影响结果。
writing_type	可不传。本版不校验文体白名单。
strictness	可不传。本版不使用宽松/严苛档位。
item 里的旁批、润色类选项	可不传。本版不会产出这些结果。
is_pro	可不传。本版单价固定，不区分 Pro 能力包。

图片要求（传 images 时）

与大作文一致：公网可访问；建议裁掉桌面、地板等无关背景；常见格式 jpg/jpeg/png/bmp；单图建议 ≤4M，最长边建议 ≤4096px。

---

评分维度（score_items）

创建时：告诉平台「评哪几项」

推荐直接传维度名数组：

"score_items": ["内容", "结构", "语言"]

也支持对象写法（只取名称）：{"item":"内容"} 或 {"name":"内容"}。

不传或传空时的默认维度：

学科	默认维度
语文	内容、结构、语言
英语	内容、语言准确性、结构与连贯

传入自定义维度时：平台按你给的名称逐项打分，不会自行增删或改名。

结果里：每一项长什么样

pigai.score_items 中每项为：

字段	说明
item	维度名（与创建时一致）
score	0~100 的整数
reason	该维简短中文理由（约 15~30 字）

总分 pigai.score 的满分是创建时的 total_score。一般情况下，总分与各维度均分大致对应（约等于「维度均分 × total_score ÷ 100」）。

---

创建成功时的立即响应

字段	说明
code	1 表示提交成功
msg	提示信息
data.id	作文 ID（回调、查详情都用它）

常见失败：参数不合法（如未提供图片也未提供文本、标题和题干都空）、余额不足等。完整错误码见 开放平台说明。

---

评分完成后的回调

通用回调格式见 发送作文批改结果。
也可用 查询作文详情 拉取同一套结果。

成功时重点字段

字段	说明
version_name	cn_v5 或 en_v5
status	1 表示本篇已完成
content	作文正文；来源规则见上文「结果里的 content」
pigai.score	总分
pigai.total_score	满分
pigai.score_items	分项分列表
pigai.comment	中文短评
pangpi	固定为 []
runse	固定为 {}
wrong_words	一般为 null
transmission	若创建时传了，原样返回

成功回调示例

{
  "code": 1,
  "msg": "批改成功",
  "data": {
    "zuowen_id": "u3EDmPW",
    "version_name": "cn_v5",
    "status": 1,
    "content": "",
    "pigai": {
      "score": 78,
      "total_score": 100,
      "score_items": [
        { "item": "内容", "score": 80, "reason": "事情经过较清楚，细节略少" },
        { "item": "结构", "score": 75, "reason": "有开头结尾，中间层次一般" },
        { "item": "语言", "score": 78, "reason": "语句大体通顺，个别表达重复" }
      ],
      "comment": "能把事情写完整，开头也点了题；中间可再补一两处具体动作或对话，会更生动。"
    },
    "pangpi": [],
    "runse": {},
    "wrong_words": null
  }
}

上例是「图片评分且未要求回传原文」时的形态，content 为空。若图片并传了 return_content=1 且识别成功，content 会是识别出的正文。

失败时

一般回调顶层 code=0（例如无可评分内容、评分失败）。
本版不做错别字校对链路，对接时通常不必按 error_code=1000 / 1001 处理本版任务。

---

请求示例

1）语文 · 图片 · 只要分数（最常见）

{
  "subject": "语文",
  "version": 5,
  "total_score": 100,
  "grade": "四年级",
  "title": "难忘的一天",
  "topic_content": "写一件让你难忘的事",
  "score_items": ["内容", "结构", "语言"],
  "images": [
    { "url": "https://example.com/essay1.jpg", "width": 864, "height": 1920 }
  ],
  "callback_url": "https://partner.example.com/callback",
  "is_dev": 1
}

2）语文 · 图片 · 同时要原文

在上例基础上增加：

"return_content": 1

3）语文 · 纯文本

{
  "subject": "语文",
  "version": 5,
  "total_score": 100,
  "grade": "四年级",
  "title": "难忘的一天",
  "topic_content": "写一件让你难忘的事",
  "score_items": ["内容", "结构", "语言"],
  "content": "今天是我难忘的一天。早上爸爸带我去公园……",
  "callback_url": "https://partner.example.com/callback",
  "is_dev": 1
}

纯文本无需传 return_content；完成后结果里的 content 就是你提交的正文。

4）英语

把 subject 改为 "英语"，version 仍为 5。
不传 score_items 时，使用英语默认三维：内容、语言准确性、结构与连贯。
英语图片若也需要原文，同样传 "return_content": 1。

---

对接检查清单

1. version 是否为 5，学科是否为 语文 / 英语。
2. title 与 topic_content 是否至少一个有值；grade 是否已传。
3. images 与 content 是否只选了一种（或都传且接受优先图片）。
4. 是否需要默认维度；需要自定义时 score_items 名称是否已定好。
5. 图片提交若业务侧要展示学生原文，是否已传 return_content=1，并兼容识别失败时 content 为空。
6. 回调地址是否可用；是否需要 transmission 做请求关联。
7. 不要依赖旁批、润色、错别字、字数扣分等本版不提供的能力。

---

关联文档

主题	文档
创建接口（通用字段）	创建作文批改
回调格式	发送作文批改结果
查询详情	查询作文详情
接口索引	接口总览索引