开放平台说明

题小小作文开放平台提供作文批改等相关接口，供教育厂商、机构在自有产品中调用。

发版与变更记录见 开放平台发版说明。
接口清单见 接口总览索引。

一句话说明

开通账号、拿到 accessToken 后，在你的服务端调用接口；统一用 JSON 返回，异步批改通过回调推送结果。

开通准备

请发送邮件至 public@21days.cloud 开通接口权限，并在邮件中提供：

  • 公司名称
  • 联系人姓名
  • 电话
  • 邮箱

开通后将获得 accessToken，并可协助配置生产 / 开发回调地址。

鉴权规则

项 说明
Header 字段 accessToken（必填）
获取方式 邮件申请：public@21days.cloud
调用限制 仅限服务端调用；勿在前端或公开仓库中存放 token
泄露处理 若疑似泄露，请立即发邮件至 public@21days.cloud 申请更换

接口返回规则

开放平台接口默认返回 JSON。

  • 多数业务成功 / 失败场景返回 HTTP 200
  • 参数校验失败、accessToken 缺失或错误、权限不足等，可能直接返回 HTTP 4xx
字段 类型 说明
code Number 通常 1=成功，0=失败；少数历史接口可能出现 -1
msg String 提示信息
data object / array 业务数据
detail object / array / string 更详细的错误信息（参数错误时常为数组）

成功示例

1
2
3
4
5
6
7
{
  "code": 1,
  "msg": "提交成功",
  "data": {
    "id": "u3EDmPW"
  }
}

鉴权失败示例

1
2
3
4
5
6
7
8
{
  "code": 0,
  "msg": "accessToken错误或已过期",
  "detail": {
    "status_code": 403,
    "message": "accessToken错误或已过期"
  }
}

参数校验失败示例

1
2
3
4
5
6
7
8
9
10
11
{
  "code": 0,
  "msg": "您提交的数据不正确",
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "images"],
      "msg": "Field required"
    }
  ]
}

作文批改业务错误码

异步批改失败时，顶层 code=0，data 中可能带 error_code，便于区分能否重试：

error_code 场景 是否可重试 建议处理
1000 错别字占比过高，不予批改 否 上传更清晰稿件、裁剪合适范围后重新提交
1001 图片文字识别失败 / 有效文字过少 视情况 检查清晰度与裁剪（避免桌面、边框干扰）后重试
1002 作文含试图操纵批改的越权指令 视情况 检查学生原文，移除相关内容后重试；确认误判时可携带 skip_injection_check=1 重新提交

说明：

  • 上述错误码主要用于批改相关接口的异步回调失败通知，详见 发送作文批改结果
  • 查询接口更适合补拉结果与排查，不保证每次都原样保留回调中的 error_code
  • 其他开放接口通常只用通用的 code / msg / detail

账户与余额

账户余额、次数与金额字段说明见：查询账户。

创建批改等写操作会扣费；余额不足时创建接口会直接失败（常见 code=10001），不会进入批改。

关联文档

主题 文档
发版与变更 开放平台发版说明
接口清单 接口总览索引
查询账户 查询账户
创建批改 创建作文批改