当你需要在不破坏架构或用户体验的前提下，自动化由 Google reCAPTCHA、Cloudflare Turnstile/Challenge 等挑战保护的流程时，一个可靠的 验证码读取器（captcha reader） 至关重要。 CapMonster Cloud 提供由 AI 驱动的验证码求解服务，配有简洁的 HTTP API 和官方 SDK，允许你将验证码解决方案直接集成到自己的应用、机器人以及后端服务中。
本指南将以 Google reCAPTCHA v3 为例，演示如何将 CapMonster Cloud 用作 CAPTCHA 读取器：包括核心 API 工作流、演示/沙盒集成，以及直接取自 官方文档 的完整代码示例（涵盖 JSON 请求和 SDK 用法）。在阅读完成后，你就能知道如何把这个验证码服务接入到自己的验证码应用、验证码机器人或自动化技术栈中。
CapMonster Cloud 充当云端验证码求解器：你发送一个描述验证码任务的对象（站点 URL、密钥和选项），服务端在自己的基础设施中完成求解，然后返回一个可提交给目标站点的 token 或文本答案。平台支持常见的验证码类型，例如 Google reCAPTCHA v2 和 v3（包括 Enterprise 版本），以及通过 ImageToTextTask 等任务类型处理的通用图像验证码，这些任务类型都在 API 文档 中有说明。
你发送的每个请求都会定义一个描述待求解验证码的 task 对象，以及稍后接收的 solution 对象，例如一个 gRecaptchaResponse token。对于 reCAPTCHA v3，任务类型 RecaptchaV3TaskProxyless 和 RecaptchaV3EnterpriseTask 会使用 CapMonster Cloud 自己的代理基础设施，因此在将该验证码求解器集成到你的流程中时，你无需自行管理代理。
CapMonster Cloud 在你的技术栈中可以扮演的关键角色包括：
作为抓取工具和测试框架的验证码解决后端。
作为自动化流程中的验证码移除步骤（例如登录或表单提交）。
作为在多个微服务之间共享的可复用验证码服务模块。
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 对象的请求。
要将 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。这些演示端点充当沙盒，你可以在其中集成并调试自己的在线验证码求解逻辑，而无需触碰生产系统，因此非常适合作为验证码演示目标。
推荐的设置模式是：
这种方式可以让你在进入生产流量之前，安全地集成你的验证码读取器。
reCAPTCHA v3 任务类型 RecaptchaV3TaskProxyless 是把 CapMonster Cloud 用作生产级验证码读取器，以处理不可见挑战的一个很好例子。文档解释了 reCAPTCHA v3 会在后台运行，评估用户行为并返回 0.1 到 0.9 的评分；你的验证码机器人或应用需要在创建任务时，适当地设置 minScore 和 pageAction 。
对于 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。
任务创建完成后，你可以使用 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 客户端中变成一次完整的验证码求解。 在基于浏览器的自动化场景中，你的验证码机器人可以：
这些步骤组合在一起，为 reCAPTCHA v3 实现了一个完整的验证码解决流水线。
CapMonster Cloud 提供官方 SDK 库，对 HTTP API 做了封装，使你可以更轻松地构建验证码应用、内部验证码服务或更大的验证码机器人，而无需手工构造每一个 JSON 请求。reCAPTCHA v3 文档页面包含了 JavaScript、Python 和 .NET 的 现成示例。
// 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);该示例展示了如何：
在构建验证码读取器时，你可以在浏览器扩展、Node.js 脚本或 Web 自动化控制器中复用这一模式。
# 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，通过一个简单的方法调用就完成了整次验证码求解。
// 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 请求中的解决值。你可以将它嵌入到命令行工具、微服务或更大的验证码应用中，在多个系统之间集中管理验证码求解逻辑。
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
}健壮的验证码求解实现应当：
如果目标站点拒绝了 gRecaptchaResponse，应将其视为记录上下文（URL、action、score、响应正文等）的信号，以便你调整 minScore，验证 websiteKey 和 pageAction 是否正确，或者再次确认你对该端点使用了正确的验证码类型。
当你围绕 CapMonster Cloud 构建自己的验证码读取器、验证码扩展逻辑或验证码机器人时，下面的清单可以帮助你让实现与官方文档保持一致：
在 CapMonster Cloud 注册
并获取你的 clientKey。
识别验证码类型
确认 页面使用的是 reCAPTCHA v3 而不是其他变体（如 reCAPTCHA v2），并据此选择 RecaptchaV3TaskProxyless。
提取所需参数
从页面中获取 websiteKey，以及与 grecaptcha.execute 关联的 pageAction，具体方式可参考 reCAPTCHA v3 文档。
选择正确的任务类型
对于 reCAPTCHA v3 使用 RecaptchaV3TaskProxyless，对于 v2 示例使用 RecaptchaV2Task，在处理图片验证码时则使用 ImageToTextTask 等类型。
实现 createTask
向 https://api.capmonster.cloud/createTask 发送一个 JSON POST 请求，其中包含你的 clientKey 和正确填写的 task 对象。
实现 getTaskResult 轮询
定期调用 https://api.capmonster.cloud/getTaskResult，使用返回的 taskId，直到看到 status\":\"ready\"，然后读取 solution（例如 gRecaptchaResponse）。
注入验证码解答
对于 reCAPTCHA v3，在提交表单之前，将 solution.gRecaptchaResponse 放入 <textarea id=\\\"g-recaptcha-response\\\"></textarea> 中。
在沙盒/演示环境中验证
在针对你自己的网站或生产页面之前，先在演示页面 https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta 上测试完整流程。
监控并持续优化
记录错误和被拒绝的 token，必要时调整 minScore 和 pageAction，并使实现持续与最新的 CapMonster Cloud 文档保持一致。
此流程为你提供了一种结构化、可重复的方式来实现验证码求解步骤——无论你是在构建独立的验证码应用，将其集成到现有自动化中，还是在内部暴露一个共享的验证码服务。
CapMonster Cloud 提供了一个功能强大、由 AI 驱动的验证码读取器，你可以通过简洁的 HTTP API 调用或官方 SDK，将它集成到自己的网页抓取、自动化或测试工作流中。遵循文档中完善的 createTask 和 getTaskResult 模式，并使用提供的演示页面进行初始验证，你就可以在不重复造轮子的情况下构建可靠的验证码解决方案。
立即在CapMonster Cloud 创建账户，体验自动化验证码求解的简便性。访问docs.CapMonster.cloud 获取最新的 API 参考、任务类型和集成示例。
