开放 API 接入文档

将词元成章接入自己的软件、脚本或工作流中，实现自动提交和获取优化结果。API 与网站共用同一个账户的标准优化额度。

快速开始

登录词元成章后，进入「头像 → 账户设置 → API 接口」，点击「创建 API Key」。

在请求头中携带 X-API-Key 或 Authorization: Bearer wf_xxx 进行鉴权。

调用下方接口，额度自动从当前账户的标准优化字数/深度重构次数中扣除。

无需单独购买 API 额度，直接使用账户现有额度。高级会员账户长期有效，套餐卡在有效期内均可使用。

鉴权方式

两种携带方式任选其一，推荐 X-API-Key 方式：

// 方式一：请求头
X-API-Key: wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

// 方式二：Authorization Bearer
Authorization: Bearer wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

// 方式三：URL 参数或表单（不推荐生产环境）
?token=wf_xxx

接口列表

POST/api/index.php?act=rewrite

标准优化（AI 二创 / 改写）。支持 1~5 级优化强度，强度越高改写力度越大。

请求参数

参数	类型	必填	说明
text	string	必填	待改写文本，最少 10 字；轻度/标准上限 1500 字，深度重构上限 3000 字
level	string/int	可选	优化强度：`1`/`2`=轻度改写，`3`=标准改写，`4`/`5`=深度重构；或直接用 `light`/`normal`/`deep`，默认 `normal`
use_style	string	可选	传 `1` 时注入已保存的文风画像，仅 AI 路径生效
idempotency_key	string	可选	幂等键（6~64 位字母数字-_），重复请求直接返回首次结果，不重复扣费

header 中可用 X-Idempotency-Key 代替 idempotency_key 参数。

请求示例

POST /api/index.php?act=rewrite HTTP/1.1
X-API-Key: wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "text": "这是一段需要改写的文章...",
  "level": "3",
  "idempotency_key": "req-20241005-001"
}

成功响应

{
  "ok": true,
  "text": "改写后的文本...",
  "engine": "openai",
  "strength": 3,
  "ai_prob": 0.12,
  "human_prob": 0.88,
  "pass": true,
  "balance": { "words": 154800, "deep": 12 },
  "byok": false,
  "fallback": false
}

POST/api/index.php?act=detect

AI 内容检测。分析文本被判定为 AI 生成的概率，返回值已标准化为 0~1。

请求参数

参数	类型	必填	说明
text	string	必填	待检测文本，最少 10 字，上限 1 万字

成功响应

{
  "ok": true,
  "engine": "zhuque",
  "ai_prob": 0.32,
  "human_prob": 0.68,
  "level": "low",
  "pass": true,
  "details": { ... }
}

检测接口完全免费，不消耗任何额度，需携带 API Key 鉴权调用。未配置真实检测引擎时返回本地参考分析。

POST/api/index.php?act=format

一键排版。将 Markdown 文稿排版为微信公众号格式，需携带 API Key 鉴权调用，不消耗额度。

请求参数

参数	类型	必填	说明
text	string	必填	Markdown 正文

成功响应

{
  "ok": true,
  "html": "排版后的 HTML 片段...",
  "plain": "纯文本版本..."
}

幂等保护

为避免网络重试导致重复扣费与重复改写，改写接口支持幂等请求：

在请求头添加 X-Idempotency-Key: your-unique-key，或使用请求参数 idempotency_key。
同一 Key 在 7 天内重复调用，直接返回首次成功结果，不重复执行、不重复扣费。
请求失败（如额度不足、AI 异常）时不会缓存，可放心重试。
建议生成规则：业务 ID + 时间戳 + 随机串，如 article-9527-20241005-abc123。

错误码与处理

HTTP	msg	含义
200	ok=true	成功
401	API Key 无效或账号已停用	鉴权失败，检查 Key 是否正确或是否被删除
403	API Key 仅可调用标准优化、检测与排版接口	当前 Key 无权访问该接口
403	额度不足...	标准优化字数或深度重构次数不足，需充值
429	操作太频繁	触发了频控限制，请稍后再试
500	AI 调用失败	已自动退费，可重试
502	BYOK 接口异常	用户自配 API 返回错误，检查 BYOK 配置

额度说明

改写接口（rewrite）：轻度/标准改写按处理字数扣标准优化额度；深度重构按次扣深度重构次数。
检测接口（detect）：完全免费，不消耗任何额度。
排版接口（format）：完全免费，不消耗任何额度。
API 与网站操作共用同一个账户额度：在网站创作工具中使用也会扣除相应额度。
支持 BYOK（Bring Your Own Key）：在「账户设置 → API 配置」接入自己的大模型后，改写不消耗站点额度，且优先于站点配置。

额度查询

POST/api/index.php?act=profile

查询当前账户的剩余额度、会员状态等信息。

{
  "ok": true,
  "user": {
    "words": 154800,
    "deep": 12,
    "premium": false,
    "pack_active": true,
    "pack_expire": "2026-10-15 23:59:59"
  }
}

如有接入问题，请在联系我们页面获取支持。