1. CapMonster Cloud 作为验证码读取器的工作方式
CapMonster Cloud 充当云端验证码求解器:你发送一个描述验证码任务的对象(站点 URL、密钥和选项),服务端在自己的基础设施中完成求解,然后返回一个可提交给目标站点的 token 或文本答案。平台支持常见的验证码类型,例如 Google reCAPTCHA v2 和 v3(包括 Enterprise 版本),以及通过 ImageToTextTask 等任务类型处理的通用图像验证码,这些任务类型都在 API 文档 中有说明。
你发送的每个请求都会定义一个描述待求解验证码的 task 对象,以及稍后接收的 solution 对象,例如一个 gRecaptchaResponse token。对于 reCAPTCHA v3,任务类型 RecaptchaV3TaskProxyless 和 RecaptchaV3EnterpriseTask 会使用 CapMonster Cloud 自己的代理基础设施,因此在将该验证码求解器集成到你的流程中时,你无需自行管理代理。
CapMonster Cloud 在你的技术栈中可以扮演的关键角色包括:
2. CapMonster Cloud API 核心工作流
CapMonster Cloud 的 HTTP API 围绕一个简单的模式组织:先创建任务,然后轮询其结果。所有请求都使用 JSON POST,并包含你的 clientKey,也就是 CapMonster Cloud 账户中的唯一 API 密钥。
从高层来看,一个典型的验证码求解流程如下所示:
准备 一个具有正确 type 和验证码参数的 task 对象(例如 RecaptchaV3TaskProxyless,以及 websiteURL、websiteKey、minScore 和 pageAction)。
调用 createTask 方法,向 https://api.capmonster.cloud/createTask 发送包含你的 clientKey 和 task 对象的请求。
- 轮询 https://api.capmonster.cloud/getTaskResult,使用返回的 taskId,直到 status 变为 ready,然后读取 solution(例如 gRecaptchaResponse)。
3. 入门:账户、密钥、沙盒与验证码演示
要将 CapMonster Cloud 用作验证码读取器,你首先需要从账户中获取一个 clientKey (API 密钥),然后在每次 API 调用中通过 clientKey 字段传递它。
为了安全的开发和测试,CapMonster 提供了专用的演示页面,例如针对 reCAPTCHA v3 的 https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta,以及针对 reCAPTCHA v2 的 https://capmonster.cloud/en/demo/recaptcha-v2。这些演示端点充当沙盒,你可以在其中集成并调试自己的在线验证码求解逻辑,而无需触碰生产系统,因此非常适合作为验证码演示目标。
推荐的设置模式是:
- 在本地开发或预发布环境中,使用lessons.zennolab.com 的测试页面来验证你的验证码求解流程。
- 稳定后,将 websiteURL 和 websiteKey 替换为与你真实应用页面匹配的值,同时保持相同的 CapMonster Cloud API 集成模式。
这种方式可以让你在进入生产流量之前,安全地集成你的验证码读取器。
4. 通过 reCAPTCHA v3 API 求解验证码(演示)
reCAPTCHA v3 任务类型 RecaptchaV3TaskProxyless 是把 CapMonster Cloud 用作生产级验证码读取器,以处理不可见挑战的一个很好例子。文档解释了 reCAPTCHA v3 会在后台运行,评估用户行为并返回 0.1 到 0.9 的评分;你的验证码机器人或应用需要在创建任务时,适当地设置 minScore 和 pageAction 。
4.1. 创建 RecaptchaV3TaskProxyless 任务
对于 reCAPTCHA v3,指向演示页面的 createTask 请求 如下所示:
{
"clientKey": "API_KEY",
"task": {
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta",
"websiteKey": "6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob",
"minScore": 0.3,
"pageAction": "myverify"
}
}
其中:
websiteURL 指向 lessons.zennolab.com 上的 reCAPTCHA v3 沙盒页面。
websiteKey 是从页面脚本中提取的公共 reCAPTCHA 站点密钥。
minScore 指定可接受的最小可信评分,范围为 0.1 到 0.9。
pageAction 与传递给 grecaptcha.execute 的 action 字符串一致,例如 'login_test' 或此示例中使用的 "myverify"。
你的后端或验证码服务封装会通过 POST 将该 JSON 发送到 https://api.capmonster.cloud/createTask,如果 errorId 为 0,则读取返回的 taskId。
4.2. 轮询 getTaskResult 获取验证码解答
任务创建完成后,你可以使用 getTaskResult 方法来获取验证码解决结果。
请求
{
"clientKey":"API_KEY",
"taskId": 407533072
}
响应
{
"errorId":0,
"status":"ready",
"solution": {
"gRecaptchaResponse":"3AHJ_VuvYIBNBW5yyv0zRYJ75VkOKvhKj9_xGBJKnQimF72rfoq3Iy-DyGHMwLAo6a3"
}
}
solution.gRecaptchaResponse 字段是一个 token 字符串,应插入到 reCAPTCHA v3 表单字段 <textarea ></textarea> 中。文档指出,这是求解验证码时返回的值,它使你的 API 调用在浏览器或 HTTP 客户端中变成一次完整的验证码求解。 在基于浏览器的自动化场景中,你的验证码机器人可以:
- 从后端服务调用 createTask ,然后调用 getTaskResult。
- 将 gRecaptchaResponse 注入到目标页面的隐藏 textarea 中。
- 提交表单,从而在页面渲染和表单提交之间使用 CapMonster Cloud 作为验证码移除步骤。
这些步骤组合在一起,为 reCAPTCHA v3 实现了一个完整的验证码解决流水线。
5. 使用 SDK 构建验证码应用或验证码机器人
CapMonster Cloud 提供官方 SDK 库,对 HTTP API 做了封装,使你可以更轻松地构建验证码应用、内部验证码服务或更大的验证码机器人,而无需手工构造每一个 JSON 请求。reCAPTCHA v3 文档页面包含了 JavaScript、Python 和 .NET 的 现成示例。
5.1. JavaScript SDK 示例
// https://github.com/CapMonsterCloud/capmonstercloud-client-js
import { CapMonsterCloudClientFactory, ClientOptions, RecaptchaV3ProxylessRequest } from '@zennolab_com/capmonstercloud-client';
const API_KEY = "YOUR_API_KEY"; // 输入您的 CapMonster Cloud API 密钥
async function solveRecaptchaV3() {
const cmcClient = CapMonsterCloudClientFactory.Create(
new ClientOptions({ clientKey: API_KEY })
);
// 如有必要,可以检查余额
const balance = await cmcClient.getBalance();
console.log("Balance:", balance);
// 基本示例,无需代理
// CapMonster Cloud 会自动使用它们的代理
const recaptchaV3Request = new RecaptchaV3ProxylessRequest({
websiteURL: "https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta", // 您的验证码页面 URL
websiteKey: "6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob",
minScore: 0.6,
pageAction: "myverify",
});
const solution = await cmcClient.Solve(recaptchaV3Request);
console.log("Solution:", solution);
}
solveRecaptchaV3().catch(console.error);
该示例展示了如何:
- 使用 clientKey 初始化客户端。
- 可选调用 getBalance() 来检查账户余额。
- 使用演示站点 URL 和密钥构造一个 RecaptchaV3ProxylessRequest。
- 调用 Solve 来执行一次验证码求解并输出结果。
在构建验证码读取器时,你可以在浏览器扩展、Node.js 脚本或 Web 自动化控制器中复用这一模式。
5.2. Python SDK 示例
# https://github.com/CapMonsterCloud/capmonstercloud-client-python
import asyncio
from capmonstercloudclient import CapMonsterClient, ClientOptions
from capmonstercloudclient.requests import RecaptchaV3ProxylessRequest
client_options = ClientOptions(api_key="YOUR_API_KEY") # 输入您的 CapMonster Cloud API 密钥
cap_monster_client = CapMonsterClient(options=client_options)
# 如有必要,可以检查余额
balance = asyncio.run(cap_monster_client.get_balance())
print("Balance:", balance)
recaptcha_v3_request = RecaptchaV3ProxylessRequest(
websiteUrl="https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta", # 您的验证码页面 URL
websiteKey="6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob",
minScore=0.6,
pageAction="myverify"
)
async def solve_captcha():
return await cap_monster_client.solve_captcha(recaptcha_v3_request)
responses = asyncio.run(solve_captcha())
print(responses)
该代码片段展示了一个异步的 solve_captcha 调用,其使用与原始 JSON 示例中相同的演示 websiteUrl 和 websiteKey,通过一个简单的方法调用就完成了整次验证码求解。
5.3. .NET SDK 示例
// https://github.com/CapMonsterCloud/capmonstercloud-client-dotnet
using Zennolab.CapMonsterCloud.Requests;
using Zennolab.CapMonsterCloud;
class Program
{
static async Task Main(string[] args)
{
var clientOptions = new ClientOptions
{
ClientKey = "YOUR_API_KEY" // 输入您的 CapMonster Cloud API 密钥
};
var cmCloudClient = CapMonsterCloudClientFactory.Create(clientOptions);
// 如有必要,可以检查余额
var balance = await cmCloudClient.GetBalanceAsync();
Console.WriteLine("Balance: " + balance);
var recaptchaV3Request = new RecaptchaV3ProxylessRequest
{
WebsiteUrl = "https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta", // 您的验证码页面 URL
WebsiteKey = "6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob",
MinScore = 0.6,
PageAction = "myverify"
};
var recaptchaV3Result = await cmCloudClient.SolveAsync(recaptchaV3Request);
Console.WriteLine("Solution: " + recaptchaV3Result.Solution.Value);
}
}
在这里, SolveAsync 隐藏了底层的 createTask 和 getTaskResult 调用,返回的类型化结果对象包含已经可以直接注入到目标页面或 HTTP 请求中的解决值。你可以将它嵌入到命令行工具、微服务或更大的验证码应用中,在多个系统之间集中管理验证码求解逻辑。
6. 错误处理、坏 token 与 token 接受情况
createTask 的文档 描述了你在验证码读取器或验证码服务封装中需要集成的标准错误模型。每个响应都包含一个 errorId,0 表示成功,非零表示错误,并带有相应的 errorCode 和 errorDescription。
createTask API 方法包含如下错误响应示例:
{
"errorId": 1,
"errorCode": "ERROR_KEY_DOES_NOT_EXIST",
"errorDescription": "Account authorization key not found in the system or has incorrect format",
"taskId": 0
}
健壮的验证码求解实现应当:
- 在每次 createTask 调用后检查 errorId,处理 API 密钥无效或任务格式错误等情况。
- 在遇到网络超时或临时服务问题时,通过退避重试等方式进行处理。
- 在轮询 getTaskResult 时,一直等待直到获得最终状态(ready 或错误),并记录被拒绝的 token 或异常模式,以便后续分析。
如果目标站点拒绝了 gRecaptchaResponse,应将其视为记录上下文(URL、action、score、响应正文等)的信号,以便你调整 minScore,验证 websiteKey 和 pageAction 是否正确,或者再次确认你对该端点使用了正确的验证码类型。