Skip to main content
Are you experiencing issues obtaining the token?
Contact support

GeeTestTask

This type of task is for solving GeeTest captcha using your proxies. Your application should send the site address, public domain key (gt), key (challenge) and proxy.

The result of solving the problem is three or five tokens for submitting the form.

Attention!

Proxies with IP authorization are not yet supported.

info
  • The gt, challenge and geetestApiServerSubdomain parameters are most often found inside the initGeetest JavaScript function.
  • Also you can see in the HTML code of the page. You can find it in the <sсript> block, which appears after the page is fully loaded in the browser.

V3

V4 (captcha_id = gt)


GeeTest V3

Possible captcha variants

Request parameters

type<string>required

GeeTestTask


websiteURL<string>required

Address of the page on which the captcha is solved. The correct Url is always passed to Referer on the request https://api-na.geetest.com/gettype.php? For example: We are at https://example.com#login, but we see that the captcha is not actually initialised there, but at https://example.com.


gt<string>required

The GeeTest identifier key gt for the domain. Static value, rarely updated.


challenge<string>required only for V3

A dynamic key.
Each time our API is called, we need to get a new key value. If the captcha is loaded on the page, then the challenge value is no longer valid and you will get the error ERROR_TOKEN_EXPIRED.
You will be charged for tasks with ERROR_TOKEN_EXPIRED error. It is necessary to examine the requests and find the one in which this value is returned and, before each creation of the recognition task, execute this request and parse the challenge from it.


version<integer>required only for V4

3


geetestApiServerSubdomain<string>optional

Geetest API subdomain server (must be different from api.geetest.com).
Optional parameter. May be required for some sites.


geetestGetLib<string>optional

Path to the captcha script to display it on the page.
Optional parameter. May be required for some sites.
Send JSON as a string.


proxyType<string>optional

http - regular http/https proxy;
https - try this option only if "http" doesn't work (required for some custom proxies);
socks4 - socks4 proxy;
socks5 - socks5 proxy.


proxyAddress<string>optional

IPv4/IPv6 proxy IP address. Not allowed:

  • using of hostnames;
  • using transparent proxies (where you can see the client's IP);
  • using proxies on local machines.


proxyPort<integer>optional

Proxy port.


proxyLogin<string>optional

Proxy-server login.


proxyPassword<string>optional

Proxy-server password.


userAgent<string>optional

Browser User-Agent used to recognize captcha.

Create task

POST
https://api.capmonster.cloud/createTask

Request

{
"clientKey":"YOUR_CAPMONSTER_CLOUD_API_KEY",
"task":
{
"type":"GeeTestTask",
"websiteURL":"https://www.geetest.com/en/demo",
"gt":"022397c99c9f646f6477822485f30404",
"challenge":"7f044f48bc951ecfbfc03842b5e1fe59",
"geetestApiServerSubdomain":"api-na.geetest.com"

}
}

Response

{
"errorId":0,
"taskId":407533072
}

Use the getTaskResult method to get the result of GeeTest recognition. Depending on the system load, you will receive a response after a time in the range from 10 s to 30 s.

Get task result

POST
https://api.capmonster.cloud/getTaskResult

Request

{
"clientKey":"API_KEY",
"taskId": 407533072
}

Response

{
"errorId":0,
"status":"ready",
"solution": {
"challenge":"0f759dd1ea6c4wc76cedc2991039ca4f23",
"validate":"6275e26419211d1f526e674d97110e15",
"seccode":"510cd9735583edcb158601067195a5eb|jordan"
}
}

PropertyTypeDescription
challengeStringAll three parameters are required when submitting the form on the target site.
validateString
seccodeString

How to Find All Required Parameters for Task Creation

Manually

  1. Open your website where the captcha appears in the browser.
  2. Right-click on the captcha element and select Inspect.

All parameters can be found in init-params among the requests:

paramsv3

Automatically

A convenient way to automate the search for all necessary parameters. Some parameters are regenerated every time the page loads, so you'll need to extract them through a browser — either regular or headless (e.g., using Playwright). Since the values of dynamic parameters are short-lived, the captcha must be solved immediately after retrieving them.

Important!

The code snippets provided are basic examples for familiarization with extracting the required parameters. The exact implementation will depend on your captcha page, its structure, and the HTML elements/selectors it uses.

Show code (in browser)
(function detectGeeTestV3Browser() {
const t = Date.now();
const url = `https://example.com/api/v1/captcha/gee-test/init-params?t=${t}`;

fetch(url)
.then(res => res.json())
.then(data => {
const { gt, challenge } = data;
if (gt && challenge) {
console.log("GeeTest v3 detected:");
console.log({ gt, challenge });
} else {
console.log("Failed to find gt/challenge parameters");
}
})
.catch(err => console.error("Request error:", err));
})();
Show code (Node.js)
async function detectGeeTestV3() {
const result = {
version: null,
data: {},
};

const t = Date.now(); // Get current timestamp
try {
const response = await fetch(
`https://example.com/api/v1/captcha/gee-test/init-params?t=${t}`
);

if (response.ok) {
const data = await response.json();
const challenge = data.challenge;
const gt = data.gt;

if (gt && challenge) {
result.version = "v3";
result.data = { gt, challenge };
console.log(result.data);
} else {
console.log("Error: Missing gt or challenge");
}
} else {
console.log("Error: Invalid response status", response.status);
}
} catch (error) {
console.error("Request failed", error);
}

return result;
}

detectGeeTestV3();

Use SDK Library

// https://github.com/ZennoLab/capmonstercloud-client-js

import { CapMonsterCloudClientFactory, ClientOptions, GeeTestRequest, /*GeeTestRequest*/ } from '@zennolab_com/capmonstercloud-client';

document.addEventListener('DOMContentLoaded', async () => {
const cmcClient = CapMonsterCloudClientFactory.Create(new ClientOptions({ clientKey: '<your capmonster.cloud API key>' }));
console.log(await cmcClient.getBalance());

const geetestV3Request = new GeeTestRequest({
websiteURL: 'https://example.com/geetest.php',
gt: '81dc9bdb52d04dc20036dbd8313ed055',
challenge: 'd93591bdf7860e1e4ee2fca799911215',
});

// const geetestV3Request = new GeeTestRequest({
// websiteURL: 'https://example.com/geetest.php',
// gt: '81dc9bdb52d04dc20036dbd8313ed055',
// challenge: 'd93591bdf7860e1e4ee2fca799911215',
// userAgent: 'userAgentPlaceholder',
// proxyType: 'https',
// proxyAddress: 'https://proxy.com',
// proxyPort: 6045,
// proxyLogin: 'login',
// proxyPassword: 'password',
// });

console.log(await cmcClient.Solve(geetestV3Request));
});

GeeTest V4

Possible captcha variant

Request parameters

type<string>required

GeeTestTask


websiteURL<string>required

Address of the page on which the captcha is solved.


gt<string>required

The GeeTest identifier key for the domain - the captcha_id parameter.


version<integer>required only for V4

4


geetestApiServerSubdomain<string>optional

Geetest API subdomain server (must be different from api.geetest.com).
Optional parameter. May be required for some sites.


geetestGetLib<string>optional

Path to the captcha script to display it on the page.
Optional parameter. May be required for some sites.
Send JSON as a string.


initParameters<object>optional

Additional parameters for version 4, used together with “riskType” (captcha type/characteristics of its verification).


proxyType<string>optional

http - regular http/https proxy;
https - try this option only if "http" doesn't work (required for some custom proxies);
socks4 - socks4 proxy;
socks5 - socks5 proxy.


proxyAddress<string>optional

IPv4/IPv6 proxy IP address. Not allowed:

  • using of hostnames;
  • using transparent proxies (where you can see the client's IP);
  • using proxies on local machines.


proxyPort<integer>optional

Proxy port.


proxyLogin<string>optional

Proxy-server login.


proxyPassword<string>optional

Proxy-server password.


userAgent<string>optional

Browser User-Agent used to recognize captcha.

Create task method

POST
https://api.capmonster.cloud/createTask

Request

{
"clientKey":"YOUR_CAPMONSTER_CLOUD_API_KEY",
"task":
{
"type":"GeeTestTask",
"websiteURL":"https://gt4.geetest.com/",
"gt":"54088bb07d2df3c46b79f80300b0abbe",
"version": 4,
"initParameters": {
"riskType": "slide"

}
}
}

Response

{
"errorId":0,
"taskId":407533072
}

Use the getTaskResult to get the result of GeeTest recognition. Depending on the system load, you will receive a response after a time in the range from 10 s to 30 s.

Get task result method

POST
https://api.capmonster.cloud/getTaskResult

Request

{
"clientKey":"API_KEY",
"taskId": 407533072
}

Response

{
"errorId":0,
"status":"ready",
"solution": {
"captcha_id":"f5c2ad5a8a3cf37192d8b9c039950f79",
"lot_number":"bcb2c6ce2f8e4e9da74f2c1fa63bd713",
"pass_token":"edc7a17716535a5ae624ef4707cb6e7e478dc557608b068d202682c8297695cf",
"gen_time":"1683794919",
"captcha_output":"XwmTZEJCJEnRIJBlvtEAZ662T...[cut]...SQ3fX-MyoYOVDMDXWSRQig56"
}
}

PropertyTypeDescription
captcha_idStringAll five parameters are required when submitting the form on the target site.
input[name=captcha_id]
input[name=lot_number]
input[name=pass_token]
input[name=gen_time]
input[name=captcha_output]
lot_numberString
pass_tokenString
gen_timeString
captcha_outputString

How to Find All Required Parameters for Task Creation

Manually

  1. Open your website where the captcha appears in the browser.
  2. Right-click on the captcha element and select Inspect.

Parameters may load in load?callback:

paramsv4

Automatically

A convenient way to automate the search for all necessary parameters. Some parameters are regenerated every time the page loads, so you'll need to extract them through a browser — either regular or headless (e.g., using Playwright). Since the values of dynamic parameters are short-lived, the captcha must be solved immediately after retrieving them.

Important!

The code snippets provided are basic examples for familiarization with extracting the required parameters. The exact implementation will depend on your captcha page, its structure, and the HTML elements/selectors it uses.

Show code (in browser)
(function() {
function getQueryParams(url) {
const params = new URLSearchParams(new URL(url).search);
const captchaId = params.get('captcha_id');
const challenge = params.get('challenge');
const riskType = params.get('risk_type');
return { captchaId, challenge, riskType };
}

const observer = new PerformanceObserver((list) => {
const entries = list.getEntriesByType('resource');
entries.forEach((entry) => {
if (entry.name.includes('https://gcaptcha4.geetest.com/load?')) {
const { captchaId, challenge, riskType } = getQueryParams(entry.name);
if (captchaId && challenge) {
console.log('GeeTest v4 detected (via PerformanceObserver):');
console.log({ captchaId, challenge, riskType });
}
}
});
});

observer.observe({ type: 'resource', buffered: true });
})();
Show code (Node.js)
import { chromium } from "playwright";

async function detectGeeTestV4(pageUrl) {
const result = { version: null, data: {} };

const browser = await chromium.launch({ headless: false });
const context = await browser.newContext();
const page = await context.newPage();

page.on("response", async (response) => {
const url = response.url();
if (url.includes("https://gcaptcha4.geetest.com/load?")) {
const urlParams = new URLSearchParams(url.split("?")[1]);
const captchaId = urlParams.get("captcha_id");
const challenge = urlParams.get("challenge");
const riskType = urlParams.get("risk_type");

if (captchaId && challenge && !result.version) {
result.version = "v4";
result.data = {
captchaId: captchaId,
challenge: challenge,
riskType: riskType,
};
console.log("GeeTest v4 detected:");
console.log(result.data);
}
}
});

await page.goto(pageUrl, { waitUntil: "networkidle" });
await page.waitForTimeout(20000);

if (!result.version) {
console.log("error");
}

await browser.close();
return result;
}

detectGeeTestV4("https://example.com").then((result) => {
console.log(result);
});

Use SDK Library

// https://github.com/ZennoLab/capmonstercloud-client-js

import { CapMonsterCloudClientFactory, ClientOptions, GeeTestRequest, /*GeeTestRequest*/ } from '@zennolab_com/capmonstercloud-client';

document.addEventListener('DOMContentLoaded', async () => {
const cmcClient = CapMonsterCloudClientFactory.Create(new ClientOptions({ clientKey: '<your capmonster.cloud API key>' }));
console.log(await cmcClient.getBalance());

const geetestV4Request = new GeeTestRequest({
websiteURL: 'https://example.com/geetest.php',
gt: '81dc9bdb52d04dc20036dbd8313ed055',
challenge: 'd93591bdf7860e1e4ee2fca799911215',
version: '4',
initParameters: {
riskType: 'slide',
},
});

// const geetestV4Request = new GeeTestRequest({
// websiteURL: 'https://example.com/geetest.php',
// gt: '81dc9bdb52d04dc20036dbd8313ed055',
// challenge: 'd93591bdf7860e1e4ee2fca799911215',
// version: '4',
// initParameters: {
// riskType: 'slide',
// },
// userAgent: 'userAgentPlaceholder',
// proxyType: 'https',
// proxyAddress: 'https://proxy.com',
// proxyPort: 6045,
// proxyLogin: 'login',
// proxyPassword: 'p@ssword',
// })

console.log(await cmcClient.Solve(geetestV4Request));
});