生成范文

测试中，未正式开放

发版与变更记录见开放平台发版说明。

接口描述

给定作文题目（标题 / 题干 / 字数要求 / 评分标准等），由 AI 先对题目做完整解析，再一次性生成 N 篇（默认 9 篇） 不同立意 / 角度的范文。
完全独立于作文批改接口，使用独立任务表、独立回调链路；不影响既有 V1 / V2 / V3 作文批改流程。
异步任务，立即返回任务 ID，完成后通过 callback_url 回调通知合作方。
按普通版价位 0.2 元/次 计费。

1. 创建范文任务

请求说明

HTTP 方法：post
请求地址：

1	https://api.21days.cloud/opi/p/c012/generate_fanwen

URL 参数：无
Header：accessToken 鉴权
Body：

字段名称	类型	默认值	是否可选	说明
subject	String	‘语文’	否	学科，支持 `语文` / `英语`
grade	String	‘四年级’	否	年级
writing_type	String	‘不限’	是	文体类别
title	String	‘’	是	作文标题；与 `topic_content` 至少传一个
topic_content	String	‘’	是	题干 / 写作要求；与 `title` 至少传一个
words_count	Number	400	否	期望字数（每篇范文会尽量满足 `要求字数 × 0.9` 的兜底约束）
correct_standard	String	‘’	是	评分标准 / 写作要求补充
count	Number	9	是	需要生成的范文篇数，取值范围 1~9
callback_url	String	‘’	是	本次任务专属回调地址；不传则使用公司维度配置
is_dev	Number	0	是	是否使用开发环境回调（与现有作文批改接口一致）
transmission	Object	null	是	透传字段，回调时原样返回

响应说明

字段	类型	必选	示例	解释
code	Number	是	1	1=正常，0=异常
msg	String	否	“提交成功”	提示信息
data	object	否	{“id”: “u3EDmPW”}	范文任务 ID

创建成功后立即返回任务 ID，任务执行可能需要数十秒到几分钟（取决于 count 与 words_count），完成后通过 callback_url 回调通知。

2. 范文任务回调

顶层结构

字段	类型	描述
code	Number	1=生成成功，0=生成失败
msg	String	提示信息
data	Object	范文结果详情，见下

data 字段结构

字段名	类型	描述
zuowen_id	String	范文任务 ID（即创建接口返回的 id）
version_name	String	固定 `fanwen_v1`
createtime	Number	创建时间戳
status	Number	0=未生成，2=生成中，1=完成，-1=失败，-2=回调失败
analysis	Object	题目解析结果，详见下
essays	Array	范文列表，每项一篇范文，详见下
transmission	Object	创建任务时传入的透传字段（未传则可能为空）
note	Object	失败时的错误说明（成功时为空）

analysis 对象结构

字段名	类型	描述
requirements	String	写作要求要点提炼（题眼、必答要素、文体限制、字数限制等），约 200 字
angles	String[]	可写的不同立意 / 角度 / 选材方向列表（每项 30~80 字）
materials	String	选材建议、可用情境与素材，约 200 字

essays 数组元素结构

字段名	类型	描述
angle	String	本篇范文采用的立意 / 角度
title	String	范文标题
outline	String	行文提纲（开头 / 中间 / 结尾的展开思路），80~150 字
content	String	范文正文，使用换行符分段；字数尽量贴近 `words_count`，不低于 `words_count × 0.9`
words_count	Number	实际字数（系统自动统计）

回调示例

{
  "code": 1,
  "msg": "范文生成成功",
  "data": {
    "zuowen_id": "u3EDmPW",
    "version_name": "fanwen_v1",
    "status": 1,
    "analysis": {
      "requirements": "围绕「不错过」展开，体裁不限……",
      "angles": [
        "以海棠树新生为线索，借景抒怀",
        "以一次错过的考试机会为切入，反思成长",
        "..."
      ],
      "materials": "可用情境：清晨庭院、第一次比赛、雨后校园……"
    },
    "essays": [
      {
        "angle": "以海棠树新生为线索，借景抒怀",
        "title": "不错过生命之树",
        "outline": "开头：风雨夜的烦躁；中间：庭院里的萧败与新芽；结尾：从新生中获得力量。",
        "content": "大雨从天上倒灌而下……",
        "words_count": 612
      },
      "...（共 count 篇）"
    ]
  }
}

3. 范文任务详情查询

请求说明

HTTP 方法：get
请求地址：

1	https://api.21days.cloud/opi/p/c012/fanwen/detail?zuowen_id=u3EDmPW

Header：accessToken 鉴权
Query：
- zuowen_id (string，必填)：范文任务 ID

响应

{
  "code": 1,
  "data": {
    "zuowen_id": "u3EDmPW",
    "version_name": "fanwen_v1",
    "status": 1,
    "analysis": { "...": "见回调结构" },
    "essays": [ "...": "见回调结构" ]
  }
}

详情接口附带 30 秒缓存，用于高频轮询。

4. 计费

每成功创建一次范文任务扣费 0.2 元/次（普通版价位，与语文标准版 V1 一致）。
范文 1~9 篇统一定价，不按篇数累加。
任务失败、回调失败均不补扣费。

5. 注意事项与最佳实践

title 与 topic_content 至少提供一个；强烈建议同时给出题目和详细的写作要求，AI 解析与角度发散的质量会显著更高。
count 越大，AI 输出 token 越多，任务耗时越长；建议默认 9 篇即可覆盖常见课堂讲评需求。
words_count 决定每篇范文的目标字数；若仍偏短，系统会自动追加一次扩写兜底（不阻塞主流程）。
回调请求需在 3 秒内返回 HTTP 200；非 200 状态会按约 3 秒一次的频率最多重试 10 次。
与作文批改回调共用 callback_url 公司维度配置；如需区分到不同业务地址，可在请求中传入独立的 callback_url。

辅助接口-系列：

生成范文

接口描述

1. 创建范文任务

请求说明

响应说明

2. 范文任务回调

顶层结构

data 字段结构

analysis 对象结构

essays 数组元素结构

回调示例

3. 范文任务详情查询

请求说明

响应

4. 计费

5. 注意事项与最佳实践