快速开始

Capcat 是托管人机验证服务：你不需要部署或维护任何服务端，在控制台创建站点获得密钥，页面里放入前端组件，业务后端调一个校验接口即可。整个接入过程大约 5 分钟。

先看在线体验 →

1. 创建站点，获取密钥

打开 console.capcat.ai，用邮箱和密码注册并登录，点「新建站点」。你会得到两把密钥：

• site key —— 公开值，写在页面代码里；
• secret —— 保密值，只在创建时展示一次，供你的后端调用校验接口。

建好站点后建议顺手绑定域名，防止别人盗用你的 site key。

2. 页面加入组件

组件是一个独立的 Web Component，通过一个 <script> 引入：

<script src="https://capcat.ai/widget/cap.js" defer></script>

放进 <form> 里时无需写任何 JavaScript，组件会自动注入隐藏的 cap-token 字段并随表单提交：

<form action="/submit" method="POST">
  <!-- 你的表单字段 -->
  <cap-widget data-cap-api-endpoint="https://api.capcat.ai/<site-key>/"></cap-widget>
  <button type="submit">提交</button>
</form>

把 <site-key> 换成控制台里的 site key 即可。SPA 或自定义流程见前端组件。

3. 服务端校验 token

信任任何提交之前，先把 token 发到 /siteverify 校验：

curl "https://api.capcat.ai/<site-key>/siteverify" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "secret": "<secret>", "response": "<captcha_token>" }'

校验通过返回：

{ "success": true }

token 一次性有效，校验一次后即失效。更多语言示例见服务端验证 API。

注意

secret 绝不能出现在前端代码里——它只属于你的服务器。丢失后可在控制台轮换（旧 secret 有 1 小时宽限期）。

4. 端到端确认

1. 打开页面，复选框应自动打勾，表单里出现 cap-token 字段；
2. 把 token 发给 /siteverify，应返回 { "success": true }；
3. 用同一个 token 再发一次，应当失败——说明一次性机制正常。

接口与迁移

/siteverify 与 reCAPTCHA / hCaptcha 的接口兼容：从它们迁移时，服务端通常只需要改一个 URL，前端把组件换成 <cap-widget> 即可。Capcat 基于开源项目 Cap（Apache 2.0）构建。