Cap-For-Vercel - Cap 验证码服务

在线演示与集成

体验 Cap-For-Vercel 验证码的实际效果，只需几行代码即可轻松集成到您的应用中。

交互式演示

快速集成

	<script src="/cap.min.js"></script>
	
	
	<cap-widget 
	  id="cap" 
	  data-cap-api-endpoint="/api/">
	</cap-widget>

const widget = document.querySelector("#cap");

	widget.addEventListener("solve", async function (e) {
	  const token = e.detail.token;
	  
	  // 处理验证码 token
	  console.log("验证码通过，token：", token);
	  
	  // 服务端验证 token
	  const result = await fetch('/api/validate', {
	    method: 'POST',
	    headers: { 'Content-Type': 'application/json' },
	    body: JSON.stringify({ 
	      token: token, 
	      keepToken: false 
	    })
	  });
	  
	  const validation = await result.json();
	  console.log("验证结果：", validation);
	});

// 服务端验证示例（Node.js）
	app.post('/api/submit-comment', async (req, res) => {
	  const { captchaToken } = req.body;
	  
	  try {
	    const validation = await fetch('https://你的域名/api/validate', {
	      method: 'POST',
	      headers: { 'Content-Type': 'application/json' },
	      body: JSON.stringify({ 
	        token: captchaToken,
	        keepToken: false
	      })
	    });
	    
	    const result = await validation.json();
	    
	    if (result.success) {
	      // 验证通过，执行受保护操作
	      res.json({ message: '验证通过' });
	    } else {
	      res.status(400).json({ error: '验证码验证失败' });
	    }
	  } catch (error) {
	    res.status(500).json({ error: '验证错误' });
	  }
	});

⚡ 5 分钟接入

🛡️ Twikoo 开箱即用

🌍 全球 CDN

🔐 隐私安全

服务概述

Cap-For-Vercel 提供企业级的机器人防护能力，基于 Vercel 边缘基础设施构建，毫秒级响应。特别针对 Twikoo 评论系统 v1.7.14+ 进行了适配，支持 Cap 官方验证接口规范。

超高性能

全球 250+ 城市边缘部署，响应时间低于 100ms，支持自动扩缩容

Twikoo 兼容

新增 /api/siteverify 端点，完全兼容 Cap 官方验证规范，Twikoo 1.7.14+ 开箱即用

安全加密

CAP_SECRET_KEY 通过 Vercel 环境变量加密存储，不会泄露在代码仓库中

API 参考

完整的 API 文档，包含示例和最佳实践。所有端点支持 JSON 格式并返回结构化响应。

POST /api/challenge 生成挑战

创建新的验证码挑战，返回加密安全的 token 和挑战数据供客户端渲染。

请求示例：

fetch('/api/challenge', {
	  method: 'POST',
	  headers: {
	    'Content-Type': 'application/json'
	  }
	})

响应示例：

{
	  "token": "785975238a3c4f0c1b0c39ed75e6e4cc152436cc0d94363de6",
	  "challenge": "{ \"c\": 50, \"s\": 32, \"d\": 4 }",
	  "expires": 1753924498818
	}

POST /api/redeem 验证解答

验证用户提交的验证码解答，成功时返回可用的验证 token。

请求参数：

token (string, 必填) - 从 /api/challenge 获取的挑战 token

solutions (number[], 必填) - 用户选择的解答索引数组

请求示例：

fetch('/api/redeem', {
	  method: 'POST',
	  headers: {
	    'Content-Type': 'application/json'
	  },
	  body: JSON.stringify({
	    token: 'c6bd7fd0bea728b5405f0e3637dca6d1b88aaf33589809a103',
	    solutions: [1, 3, 7]
	  })
	})

响应示例：

{
	  "success": true,
	  "token": "785975238a3c4f0c1b0c39:ed75e6e4cc152436cc0d94363de6"
	}

POST /api/validate Token 验证

验证已颁发的 token 有效性，可选择是否消耗该 token（一次性使用）。

请求参数：

token (string, 必填) - 需要验证的 token

keepToken (boolean, 可选) - 是否保留 token 供重复使用（默认：false）

请求示例：

fetch('/api/validate', {
	  method: 'POST',
	  headers: {
	    'Content-Type': 'application/json'
	  },
	  body: JSON.stringify({
	    token: '785975238a3c4f0c1b0c39:ed75e6e4cc152436cc0d94363de6',
	    keepToken: false
	  })
	})

响应示例：

{
	  "success": true
	}

POST /api/siteverify ✨ Twikoo 兼容

本项目新增端点，完全兼容官方 Cap 的 siteverify 验证规范，供 Twikoo 后端调用以验证前端提交的验证码 token。

请求参数：

secret (string, 必填) - 与 Vercel 环境变量中设置的 CAP_SECRET_KEY 一致

response (string, 必填) - 前端提交的 capToken 验证令牌

请求示例：

fetch('/api/siteverify', {
	  method: 'POST',
	  headers: {
	    'Content-Type': 'application/json'
	  },
	  body: JSON.stringify({
	    secret: '你的CAP_SECRET_KEY',
	    response: '前端提交的capToken'
	  })
	})

响应示例：

{
	  "success": true
	}

集成指南

生成挑战：前端 widget 自动调用 /api/challenge 获取验证码挑战
用户交互：用户在界面上完成 PoW 工作量证明（计算挑战）
提交解答：widget 自动将解答提交至 /api/redeem 验证
获取令牌：验证通过后获得 token，随表单一起提交至后端
服务端验证：后端（如 Twikoo）调用 /api/siteverify 最终确认 token 有效

Twikoo 配置

登录 Twikoo 管理面板 → 评论管理 → 配置，添加以下三个环境变量：

配置项	值	说明
CAPTCHA_PROVIDER	Cap	启用 Cap 验证码
CAP_API_ENDPOINT	https://your-diamond/api/	服务地址（带 /api/ 后缀）
CAP_SECRET_KEY	与 Vercel 环境变量一致	用于服务端验证的密钥

错误处理

API 遵循 REST 规范，返回详细的错误信息和适当的 HTTP 状态码：

400 Bad Request：请求格式错误或缺少必要参数
403 Forbidden：siteverify 中 secret 密钥不匹配
404 Not Found：请求的资源或端点不存在
410 Gone：Token 已过期或被消耗
429 Too Many Requests：请求频率过高，请稍后重试
500 Internal Server Error：服务器临时问题，可安全重试