创建作文批改

一句话说明

提交一篇作文到平台做异步批改：立刻拿到作文 ID，批改完成后推送到你的回调地址（也可用详情接口补拉）。
语文、英语各版本共用本接口，靠 subject + version 区分方案。

新对接必须显式传 version。
不传时平台默认 version=1（语文 cn_v1 / 英语 en_v1），不是当前推荐版。
推荐：语文 version=2（V2），英语 version=4（V4）。

发版与变更见 开放平台发版说明。
鉴权见 开放平台说明。

你会得到什么

时机 得到什么
创建成功（立即） data.id：作文任务 ID
批改完成（回调 / 查询） 评分、旁批、错别字、润色等（随版本与 item 变化）

各版本差异见 语文版本怎么选、英语版本怎么选。新对接推荐语文 V2、英语 V4。
回调字段总览见 发送作文批改结果。

整体流程

  1. 服务端调用本接口，带上图片（或定制版文本）、题目信息、回调地址
  2. 平台校验参数并扣费，立即返回作文 ID
  3. 后台完成识别与批改后，向 callback_url（或账号预配置地址）推送结果
  4. 你的服务端在约 3 秒内回 HTTP 200；未收到会按约 3 秒间隔最多重试 10 次
  5. 若回调未收到，用 查询作文详情 按 ID 补拉

计费（常见标准批改）

创建成功并扣费后才进入批改。余额不足时直接失败（常见 code=10001），不会批改。

场景 次数余额 金额余额（分）
标准批改（多数版本） 1 次 20（0.2 元）
语文 V2 高级评分 1.5 次 30（0.3 元）
Pro（is_pro=1） Pro 次数 1 次 按 Pro 约定（常见约 90 分）
特别版 V5 / 定制版 V6 见专项文档 见专项文档

优先扣次数余额，其次金额余额。各版本以对应文档为准。

请求说明

  • 方法：POST
  • 地址：https://api.21days.cloud/opi/p/c012/create_zuowen
  • Header：accessToken

必填与条件必填（先看这张）

字段 要求
grade 必填（如 四年级、初二）
title / topic_content 不能同时为空
images 标准批改必填（每项含 url、width、height；url 须公网可访问）
content 仅 version=5/6 可与图片二选一作答
version 请显式传；不传默认 1（不是推荐版）
回调 传 callback_url，或账号已配置生产 / 开发回调；都没有会创建失败

主要字段一览

字段 类型 默认 必填 说明
subject String 语文 否 语文 或 英语
version Number 1 建议必传 批改方案版本。新对接语文传 2、英语传 4；不传则落在历史默认 1
grade String 四年级 是 年级
title String '' 条件 作文题目
topic_content String '' 条件 题干 / 写作要求
total_score Number 100 否 满分；结果按此换算展示
words_count Number 400 否 字数 / 词数要求；英语 V4 会参与字数扣分
writing_type String 不限 否 文体；语文 V2/V3 有白名单，尽量细分
images Array — 条件 作文原图列表
content String — 条件 纯文本正文；仅 V5/V6
return_content Number 0 否 1=图片场景回传识别正文；仅 V5 生效
item Array [] 否 需要哪些批改能力（见下）
score_items Array — 否 自定义评分维度名；需 item 含「评分」；高级评分版无效
correct_standard String '' 否 自定义评分标准说明
continuation_text String '' 否 续写 / 参考原文；传入后启用未作答检测
topic_content_images Array — 否 题干配图，不影响作文识别
is_pro Number 0 否 1=Pro；V6 禁止为 1
callback_url String '' 否 本次回调地址；空则用账号预配置
is_dev Number 0 否 1=走开发回调（仅在未传 callback_url 时）
strictness String — 否 lenient / normal / strict；生效范围见各版本文档
transmission Object — 否 透传对象，回调原样带回
skip_injection_check Number 0 否 1=跳过越权指令检测（仅人工确认误判后使用）

item：需要哪些结果

可包含（按需组合）：

评分、改写标题、改写开头结尾、修改错误、评语、段评、亮点、写作要求、写作思路、不足和建议、提问、精简批改

控制项（仅语文）：素材推送 — 开启后回调可能带 materials_push，默认不开启。

不传或传空时，按平台默认能力组合处理（以实际回调为准）。

图片要求

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

版本怎么选

兼容原因：接口层默认值仍是 version=1。
文档推荐与接口默认不一致，请在请求里写死推荐版本号，不要依赖默认。

subject version version_name 文档
语文 2（请显式传） cn_v2 语文 V2（新对接推荐；约 0.3 元 / 1.5 次）
英语 4（请显式传） en_v4 英语 V4（新对接首选）
语文 1（不传时的默认值） cn_v1 语文 V1
语文 3 cn_v3 语文 V3（beta）
英语 1（不传时的默认值） en_v1 英语 V1（历史）
英语 2 en_v2 英语 V2（历史）
英语 3 en_v3 英语 V3（历史）
语文/英语 5 cn_v5 / en_v5 特别版 V5（指定客户，请勿通用对接）
语文/英语 6 cn_v6 / en_v6 定制版 V6（指定客户，请勿通用对接）

version_name 由平台根据学科与版本自动生成，出现在回调与详情中。

续写未作答检测（continuation_text）

  • 把题目给出的「续写原文 / 参考原文」放进该字段（不要放写作要求说明）
  • 仅当字段非空时启用
  • 若判定学生几乎未作答：回调顶层仍为 code=1，但 pigai.score=0、pigai.no_answer=true，旁批 / 润色为空
  • 按「已处理但未作答」展示，不要当成失败错误码

失败拦截（会回调 code=0）

error_code 含义
1000 错别字占比过高，不予批改
1001 图片识别失败或有效文字过少
1002 含试图操纵批改的越权指令

详见 开放平台说明。

其他注意：AI 评分仅供参考；图片过暗、敏感内容等可能导致无法批改。

创建成功时的立即响应

字段 说明
code 1 表示提交成功
msg 提示信息
data.id 作文 ID（回调、查详情都用它） 
1
2
3
4
5
6
7
{
  "code": 1,
  "msg": "提交成功",
  "data": {
    "id": "u3EDmPW"
  }
}

请求示例

语文新对接（V2，推荐）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "subject": "语文",
  "version": 2,
  "grade": "四年级",
  "title": "难忘的一天",
  "topic_content": "写一件让你难忘的事",
  "writing_type": "叙事为主的记叙文",
  "total_score": 100,
  "words_count": 400,
  "strictness": "normal",
  "images": [
    { "url": "https://example.com/essay1.jpg", "width": 864, "height": 1920 }
  ],
  "callback_url": "https://partner.example.com/callback",
  "is_dev": 1,
  "transmission": { "homework_id": "hw_001", "student_id": "s_88" }
}

英语新对接（V4，推荐）

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "subject": "英语",
  "version": 4,
  "grade": "初二",
  "title": "My Hobby",
  "topic_content": "Write about your hobby in at least 80 words.",
  "words_count": 80,
  "strictness": "normal",
  "images": [
    { "url": "https://example.com/en1.jpg", "width": 864, "height": 1920 }
  ],
  "callback_url": "https://partner.example.com/callback"
}

对接检查清单

  1. 是否仅在服务端携带 accessToken
  2. grade、题目信息是否齐全；标准版是否传了可访问的 images
  3. **是否显式传了 version**（语文推荐 2，英语推荐 4；勿依赖默认 1）
  4. 回调地址是否可在约 3 秒内回 HTTP 200
  5. 是否需要 transmission 关联业务侧作业 / 学生 ID
  6. 余额是否充足（语文 V2 按约 1.5 次 / 0.3 元预留；可先查 查询账户）
  7. 不要把 V5/V6 当通用方案

关联文档

主题 文档
回调格式 发送作文批改结果
查询详情 查询作文详情
账户余额 查询账户
接口索引 接口总览索引
鉴权与错误码 开放平台说明