完整对接文档（含接口字段说明、可直接复制的示例代码、错误码表）需开通「人机验证服务」权益后查看。

接口概览：

• GET /api/captcha/v1/widget.js — 前端组件
• POST /api/captcha/v1/challenge — 获取挑战
• POST /api/captcha/v1/redeem — 提交解答，换取 response
• POST /api/captcha/v1/siteverify — 服务端核销（行业标准）

接口形态与字段命名对齐 reCAPTCHA / hCaptcha / Turnstile，已有对接代码可直接迁移。 整个流程只有两步：前端拿 response → 服务端核销 response。

1. 前端接入

把下面一行放进你的表单里，组件会自动渲染。用户通过验证后，脚本会把 response 写入一个隐藏字段，随表单一起提交给你的服务器。

也可以用 JS 主动获取（不依赖表单）：

2. 服务端核销

由你的服务器调用（不要放到浏览器里，secret 会泄露）。 支持 application/x-www-form-urlencoded 与 JSON 两种请求体。 本接口总是返回 HTTP 200，成功与否看响应体的 success 字段。

3. 响应字段

4. 错误码

注意：response 是一次性的，核销成功后立即失效。 不要把它缓存起来复用，也不要拿它做登录态的凭据。

5. 示例代码

Node.js（Express）：

PHP：

Python：

6. 常见问题

• 域名白名单：留空表示不限制；填了之后，来源域名不在名单内的请求会被拒。 支持 *.example.com 匹配所有子域。
• 验证失败但用户说自己是真人：先看是不是被浏览器环境检测拦了（environment-rejected）， 常见于无头浏览器、被改过 UA 的客户端、以及某些隐私插件。
• 能不能重复核销同一个 response：不能，一次性。
• Secret 泄露了怎么办：在控制台点「重置密钥」，旧 secret 立即失效。