1. How CapMonster Cloud works as a captcha reader
CapMonster Cloud acts as a cloud-based captcha solver: you send a description of the captcha task (site URL, keys, and options), the service solves it on its side, then returns a token or text answer you can submit to the target site. The platform supports common captcha types such as Google reCAPTCHA v2 and v3 (including Enterprise versions), as well as generic image-based tasks via ImageToTextTask and other task types documented in the API.
Every request you send defines a task object that describes the captcha to solve and a solution object that you receive later, such as a gRecaptchaResponse token. For reCAPTCHA v3 specifically, the task types RecaptchaV3TaskProxyless and RecaptchaV3EnterpriseTask uses CapMonster Cloud’s own proxy infrastructure, so you don’t need to manage proxies yourself when you integrate this captcha solver into your flows.
Key roles CapMonster Cloud can play in your stack include:
As a captcha solution backend for your scraping tools and test harnesses.
As a captcha remover step inside automation flows (e.g., login or form submission).
As a reusable captcha service module shared across multiple microservices.
2. Core CapMonster Cloud API workflow
CapMonster Cloud’s HTTP API is organized around a simple pattern: create a task and then poll for its result. All requests use JSON POST and include your clientKey, the unique API key from your CapMonster Cloud account.
At a high level, a typical captcha solve flow looks like this:
Prepare a task object with the right type and captcha parameters (for example, RecaptchaV3TaskProxyless plus websiteURL, websiteKey, minScore, and pageAction).
Call the createTask method at https://api.capmonster.cloud/createTask with your clientKey and the task object.
- Poll https://api.capmonster.cloud/getTaskResult with the returned taskId until the status becomes ready, then read the solution (e.g., gRecaptchaResponse).
3. Getting started: account, keys, sandbox and captcha demo
To use CapMonster Cloud as a captcha reader, you first obtain a clientKey (API key) from your account, which you then pass in every API call as the clientKey field.
For safe development and testing, the CapMonster provides dedicated demo pages, such as https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta for the reCAPTCHA v3 or https://capmonster.cloud/en/demo/recaptcha-v2 for the reCAPTCHA v2. These demo endpoints act as a sandbox where you can integrate and debug your captcha online solving logic without touching production systems, making it an ideal captcha demo target.
A recommended setup pattern is:
- Use local development or staging environments wired against the lessons.zennolab.com test page to verify your captcha solution flow.
- Once stable, swap websiteURL and websiteKey to match your real application pages while keeping the same CapMonster Cloud API integration patterns.
This approach lets you integrate your captcha reader safely before moving to production traffic.
4. Captcha solution via reCAPTCHA v3 API (demo)
The reCAPTCHA v3 task type RecaptchaV3TaskProxyless is a good example of turning CapMonster Cloud into a production-ready captcha reader for invisible challenges. The docs explain that reCAPTCHA v3 runs in the background, evaluates user behavior, and returns a score from 0.1 to 0.9; your captcha bot or app needs to set minScore and pageAction appropriately when creating tasks.
4.1. Create a RecaptchaV3TaskProxyless task
For the reCAPTCHA v3, the createTask request for a demo page looks like this:
{
"clientKey": "API_KEY",
"task": {
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta",
"websiteKey": "6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob",
"minScore": 0.3,
"pageAction": "myverify"
}
}
Here
websiteURL points to the sandbox reCAPTCHA v3 page at lessons.zennolab.com.
websiteKey is the public ReCaptcha site key extracted from the page’s scripts.
minScore specifies the minimum acceptable trust score for the solution, from 0.1 to 0.9.
pageAction mirrors the action string passed to grecaptcha.execute, such as 'login_test' or the "myverify" used in this example.
Your backend or captcha service wrapper would send this JSON via POST to https://api.capmonster.cloud/createTask, then read the returned taskId if errorId is 0.
4.2. Poll getTaskResult for the captcha solution
Once the task is created, you retrieve the captcha solution using the getTaskResult method.
Request
{
"clientKey":"API_KEY",
"taskId": 407533072
}
Response
{
"errorId":0,
"status":"ready",
"solution": {
"gRecaptchaResponse":"3AHJ_VuvYIBNBW5yyv0zRYJ75VkOKvhKj9_xGBJKnQimF72rfoq3Iy-DyGHMwLAo6a3"
}
}
The `solution.gRecaptchaResponse` field is a token string that should be inserted into the reCAPTCHA v3 form field `<textarea ></textarea>`. The docs note that this is the value returned when solving the captcha and is what turns your API call into a complete captcha solve in the browser or HTTP client.
In a browser-based automation scenario, your captcha bot could:
- Call createTask and then getTaskResult from your backend service.
- Inject gRecaptchaResponse into the hidden textarea on the target page.
- Submit the form, effectively using CapMonster Cloud as a captcha remover step between page rendering and form submission.
Together, these steps implement a full captcha solution pipeline for reCAPTCHA v3.
5. Building a captcha app or captcha bot with SDKs
CapMonster Cloud provides official SDK libraries that wrap the HTTP API and make it easier to build a captcha app, internal captcha service, or larger captcha bot without hand-crafting every JSON request. The reCAPTCHA v3 documentation page includes ready-to-use examples for JavaScript, Python, and .NET.
5.1. JavaScript SDK example
// https://github.com/CapMonsterCloud/capmonstercloud-client-js
import { CapMonsterCloudClientFactory, ClientOptions, RecaptchaV3ProxylessRequest } from '@zennolab_com/capmonstercloud-client';
const API_KEY = "YOUR_API_KEY"; // Specify your CapMonster Cloud API key
async function solveRecaptchaV3() {
const cmcClient = CapMonsterCloudClientFactory.Create(
new ClientOptions({ clientKey: API_KEY })
);
// Optionally, you can check the balance
const balance = await cmcClient.getBalance();
console.log("Balance:", balance);
const recaptchaV3Request = new RecaptchaV3ProxylessRequest({
websiteURL: "https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta", // URL of your page with captcha
websiteKey: "6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob",
minScore: 0.6,
pageAction: "myverify",
});
const solution = await cmcClient.Solve(recaptchaV3Request);
console.log("Solution:", solution);
}
solveRecaptchaV3().catch(console.error);
This example shows how to:
- Initialize the client with clientKey.
- Optionally call getBalance() to check account funds.
- Construct a RecaptchaV3ProxylessRequest with the demo site URL and key.
- Call Solve to perform a captcha solve and log the solution.
You can adapt this pattern inside browser extensions, Node.js scripts, or web automation controllers when building your captcha reader.
5.2. Python SDK example
# 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") # Specify your CapMonster Cloud API key
cap_monster_client = CapMonsterClient(options=client_options)
# Optionally, you can check the balance
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 of your page with captcha
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)
This snippet demonstrates an asynchronous solve_captcha call with the same demo websiteUrl and websiteKey that you saw in the raw JSON example, giving you a complete captcha solve via a simple method call.
5.3. .NET SDK example
// 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" // Specify your CapMonster Cloud API key
};
var cmCloudClient = CapMonsterCloudClientFactory.Create(clientOptions);
// Optionally, you can check the balance
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 of your page with captcha
WebsiteKey = "6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob",
MinScore = 0.6,
PageAction = "myverify"
};
var recaptchaV3Result = await cmCloudClient.SolveAsync(recaptchaV3Request);
Console.WriteLine("Solution: " + recaptchaV3Result.Solution.Value);
}
}
Here, SolveAsync hides the low-level createTask and getTaskResult calls, returning a typed result object with the solution value ready to be injected into the target page or HTTP request. You can embed this into a console tool, microservice, or larger captcha app that centralizes captcha solve logic for multiple systems.
6. Error handling, bad tokens, and token acceptance
The createTask documentation describes the standard error model you’ll integrate into your captcha reader or captcha service wrapper. Each response includes an errorId, where 0 means success and a non-zero value indicates an error with an accompanying errorCode and errorDescription.
The createTask API method includes this example of an error response:
{
"errorId": 1,
"errorCode": "ERROR_KEY_DOES_NOT_EXIST",
"errorDescription": "Account authorization key not found in the system or has incorrect format",
"taskId": 0
}
A robust captcha solve implementation should:
- Check errorId after every createTask call and handle cases such as invalid API keys or malformed tasks.
- Handle network timeouts or temporary service issues by retrying with backoff where appropriate.
- When polling getTaskResult, continue until you receive a final status (ready or an error) and log rejected tokens or unusual patterns for later analysis.
Treat any rejection of the gRecaptchaResponse by the target site as a signal to log context (URL, action, score, response body) so you can tune minScore, verify that your websiteKey and pageAction are correct, or re-check that you are using the right captcha type for that endpoint.
