降AI率API：Humanizer API v2 与 Detector API

Academic Humanizer 的 降AI率 API 为开发者和机构提供两个 REST 接口：POST /api/v2/external/humanize 返回经过人性化改写的文本及逐句改动；POST /api/v2/external/detector 对最多 100,000 字符的文本返回 AI 检测评估。两者都使用服务器端 API 密钥，并与你的账户共用同一积分余额。

本文介绍 API 适合哪些用户、认证与访问控制如何运作、各接口返回什么，以及积分如何计算。完整参考文档见 /docs。

AI humanizer API 适合谁

网页编辑器适合个人研究者。API 则适合需要大批量处理学术文本、或在自有界面内处理学术文本的产品和团队：

• 写作平台，希望在自己的编辑器内提供人性化改写步骤。
• LMS 和课件工具，需要把 AI 检测信号作为人工审核流程的一项输入，而不是自动判决。
• 编辑与校对服务，在编辑阅读之前，先用统一的流程对客户草稿做一遍初步处理。
• 科研管理部门，希望批量检查基金申请文本或报告。

如果你的使用场景涉及学生作业，请在设计上让人来做最终决定。检测器输出是需要审阅的证据，我们的文章质疑学生作者身份之前应考虑什么解释了原因。

认证、IP 白名单与速率限制

登录后在 /api 创建密钥。密钥只在创建时显示一次，Academic Humanizer 只存储其哈希值，所以请直接把它复制到你的密钥管理器或服务器环境变量中。切勿把它放进浏览器或移动端代码。

在 X-API-Key 请求头中发送密钥。这是文档推荐的请求头；服务器也接受在 Authorization 请求头中以 Bearer 令牌形式发送密钥。

每个请求在处理文本之前都要通过几项检查。

1. 密钥校验密钥必须存在且处于启用状态，其所属账户也必须处于有效状态。
2. IP 白名单在受限模式下，只接受来自你所列 IP 或 CIDR 范围的请求。
3. 速率限制超过该密钥每秒限额的请求会被拒绝，返回 HTTP 429。
4. 处理对文本进行人性化改写或分析，并核对积分余额。
5. 保存结果结果保存到你的账户，并以 JSON 形式返回。

IP 访问有两种模式：公开模式下，任何 IP 只要持有有效密钥都可以调用；受限模式下，只有列出的 IP 或 CIDR 地址段可以调用。对于任何拥有固定出口地址的生产服务器，都值得开启受限模式。默认速率限制为每秒 10 个请求。

Humanize 接口

请求体为 JSON，包含一个必填字段 originalContent 和一个可选字段 researchField。如果发送研究领域，必须是以下支持的名称之一：Arts and Humanities、Social Sciences、Business and Economics、Engineering、Natural Sciences 或 Medical and Health Sciences。不需要时可以省略，或发送 null。

curl -X POST https://academichumanizer.ai/api/v2/external/humanize   -H "Content-Type: application/json"   -H "X-API-Key: YOUR_API_KEY"   -d '{"originalContent": "Paste the paragraph or abstract to humanize here.", "researchField": "Natural Sciences"}'

调用成功时返回 HTTP 201，JSON 响应体包含：

• humanizedText：完整的改写文本。
• changedCount：被修改的句子数量。
• sentences：逐句条目数组，每个条目包含该句在原文中的起止偏移量、原句、改写句，以及一个 changed 标志。数组可能为空。

保存结果的 ID 通过 X-Humanizer-Id 响应头返回，方便你把自己系统中的请求与用户账户中保存的结果关联起来。注意，changed 表示句子是否被改写，并不是 AI 检测判定。如需检测判定，请使用 Detector 接口。

借助句子偏移量，可以很方便地在你自己的界面中渲染差异对比：高亮被改动的片段，让用户逐一接受或编辑。由于 AI 改写可能引入错误或改变原意，用户应在使用前审阅每一份输出。

Detector 接口

Detector 接口只有一个必填字段 text，最多 100,000 字符。它返回分析状态、字符数、耗时、整篇文档的总体评估、各检测器结果以及 creditUsed。此接口不使用研究领域。

常见做法是先调用 Detector，向用户展示哪些段落出现了信号，再只对用户选定的部分调用 Humanize。这样能把成本和改动都降到最低。

API 积分如何计算

两个接口都从密钥所属账户扣除积分，但计算方式不同。

Humanize 每 500 字符消耗 1 积分，每次请求向上取整，且只在完整结果保存后才扣费。Detector 每 5,000 字符消耗 1 积分，向上取整。如果余额不足，请求会以积分不足错误失败，而不会返回部分结果。套餐和积分包的说明见积分与价格说明，最新价格见 /pricing。

需要处理的错误

错误响应体包含一个简短的机器可读代码，请根据代码而不是消息文本进行分支处理。

常见问题

如何获取 API 密钥？

登录后打开 /api。创建密钥后立即复制（它只显示一次），并保存在你的服务器上。

可以限制哪些服务器使用我的密钥吗？

可以。把 IP 访问切换到受限模式，并列出允许调用 API 的 IP 或 CIDR 范围。来自其他任何地方的请求都会被拒绝，返回 HTTP 403。

API 有免费额度吗？

API 与网页应用使用同一积分。新账户一次性获得 10 个免费积分，足够用几段短文本测试 Humanize 接口。

输出会对照哪些检测器检验？

Academic Humanizer 以 Turnitin、GPTZero、ZeroGPT、Copyleaks、Sapling 和 Originality.ai 为验证基准。与任何工具一样，结果因检测器而异，不保证任何特定结果。

基于 Academic Humanizer 进行开发

如果你的产品已经在处理稿件、摘要或课程作业，借助 API 就可以加入人性化改写步骤或检测环节，而无需把用户引到别处。先用测试密钥，把几段真实文字分别跑一遍两个接口，上线生产环境之前请阅读 /docs 中的完整参考文档。