服务端验证 API

前端拿到的 token 必须在服务端校验后才可信任。接口与 reCAPTCHA / hCaptcha 的 siteverify 兼容（请求体 JSON 与表单编码都接受），从它们迁移时服务端通常只需改一个 URL——对照步骤见迁移指南。

接口

POST https://api.capcat.ai/<site-key>/siteverify
Content-Type: application/json

{ "secret": "<secret_key>", "response": "<captcha_token>" }

• secret — 控制台创建站点时生成的 secret（仅创建/轮换时展示一次）；
• response — 前端组件产出的 token（表单里的 cap-token 字段，或 solve 事件的 e.detail.token）。

校验通过返回：

{ "success": true }

token 一次性有效：校验成功一次后立即失效，重放会返回失败。

多语言示例

curl

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

Node.js

const { success } = await (
  await fetch("https://api.capcat.ai/<site-key>/siteverify", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ secret: "<secret_key>", response: "<captcha_token>" }),
  })
).json();

if (!success) throw new Error("人机验证未通过");

Python

import requests

success = requests.post(
    "https://api.capcat.ai/<site-key>/siteverify",
    json={"secret": "<secret_key>", "response": "<captcha_token>"},
).json().get("success")

PHP

<?php
$ctx = stream_context_create([
  "http" => [
    "method" => "POST",
    "header" => "Content-Type: application/json",
    "content" => json_encode([
      "secret" => "<secret_key>",
      "response" => "<captcha_token>",
    ]),
  ],
]);
$data = json_decode(file_get_contents(
  "https://api.capcat.ai/<site-key>/siteverify", false, $ctx
), true);
var_dump($data["success"] ?? false);