What is GeeTest v3/v4?
GeeTest is a popular captcha used by many Chinese and international sites. It offers multiple challenge types: slider puzzles (drag to complete the image), click-in-order (click words/icons in sequence), and icon selection. GeeTest v3 uses a 'gt' key + server-generated 'challenge' value. GeeTest v4 uses a simpler 'captchaId' format.
How it works
Send Task
POST your GeeTestTaskProxyLess with the target URL and sitekey to our API. We'll queue it instantly.
We Solve
Capzy's proprietary solver handles slider and click variants and returns the validation token plus session cookies needed to submit the form.
Get Token
Poll getTaskResult — when status is 'ready', the solution contains the token to inject into the target page.
Quick integration
import requests, time
API = "https://api.capzy.ai"
KEY = "capzy_your_key_here"
# Step 1: Create task
task = requests.post(f"{API}/createTask", json={
"clientKey": KEY,
"task": {
"type": "GeeTestTaskProxyLess",
"captchaId": "647f5ed2ed8acb4be36784e01556bb71",
"websiteURL": "https://example.com"
}
}).json()
task_id = task["taskId"]
print(f"Task created: {task_id}")
# Step 2: Poll for result
while True:
result = requests.post(f"{API}/getTaskResult", json={
"clientKey": KEY,
"taskId": task_id
}).json()
if result["status"] == "ready":
print("Solved!", result["solution"])
break
elif result["status"] == "failed":
print("Failed:", result.get("errorDescription"))
break
time.sleep(1)
# Step 3: Yidun — submit validate token to your backend
validate = result["solution"]["validate"]
requests.post("https://target.example.com/verify", data={"validate": validate})Using your own proxy
Use GeeTestTask instead of GeeTestTaskProxyLess to route the solve through your own proxy. This is useful when the target site checks the IP that solved the captcha matches the IP submitting the form.
import requests, time
API = "https://api.capzy.ai"
KEY = "capzy_your_key_here"
# Step 1: Create task
task = requests.post(f"{API}/createTask", json={
"clientKey": KEY,
"task": {
"type": "GeeTestTask",
"captchaId": "647f5ed2ed8acb4be36784e01556bb71",
"proxyPort": "8080",
"proxyType": "http",
"proxyLogin": "user",
"websiteURL": "https://example.com",
"proxyAddress": "123.45.67.89",
"proxyPassword": "pass"
}
}).json()
task_id = task["taskId"]
print(f"Task created: {task_id}")
# Step 2: Poll for result
while True:
result = requests.post(f"{API}/getTaskResult", json={
"clientKey": KEY,
"taskId": task_id
}).json()
if result["status"] == "ready":
print("Solved!", result["solution"])
break
elif result["status"] == "failed":
print("Failed:", result.get("errorDescription"))
break
time.sleep(1)
# Step 3: Yidun — submit validate token to your backend
validate = result["solution"]["validate"]
requests.post("https://target.example.com/verify", data={"validate": validate})additional proxy parameters
proxyTypetypestringreqyesProxy protocol: http or httpsproxyAddresstypestringreqyesProxy IP address or hostnameproxyPorttypenumberreqyesProxy port numberproxyLogintypestringreqnoProxy username (if auth required)proxyPasswordtypestringreqnoProxy password (if auth required)userAgenttypestringreqnoUser-Agent string to use. Must match the UA you use when submitting the tokenTask parameters
typetypestringreqyesGeeTestTaskProxyLess or GeeTestTaskwebsiteURLtypestringreqyesThe page URLcaptchaIdtypestringreqnoGeeTest v4 captcha ID (use this OR gt+challenge)gttypestringreqnoGeeTest v3 'gt' parameterchallengetypestringreqnoGeeTest v3 'challenge' parameter (server-generated, single-use)Solution response
tokentypestringThe combined token to submit (varies by GeeTest version).challengetypestring[v3 only] The challenge identifier returned by GeeTest's API.validatetypestring[v3 only] The validation token — drop into the `geetest_validate` form field.seccodetypestring[v3 only] The seccode response value — drop into the `geetest_seccode` form field. Format `{validate}|jordan`.captcha_idtypestring[v4 only] GeeTest v4 captcha ID for this session.lot_numbertypestring[v4 only] GeeTest v4 lot number — uniquely identifies the challenge attempt.pass_tokentypestring[v4 only] GeeTest v4 pass token — the actual cleared signal.gen_timetypestring[v4 only] Unix timestamp string when the pass token was generated.captcha_outputtypestring[v4 only] Encoded output blob — submit as `captcha_output` to the protected endpoint.Example response
Full getTaskResult response shape. The fields in the table above describe what's inside solution — the outer envelope (errorId, status) is identical for every captcha type.
{
"errorId": 0,
"status": "ready",
"solution": {
"token": "9b6c8...",
"gen_time": "1715299200",
"captcha_id": "fcd636b4514741bcb0c1f7c4b2c4...",
"lot_number": "abc1234567890abcdef1234567890",
"pass_token": "pass_token_value_here",
"captcha_output": "encoded_output_blob_to_submit"
}
}Error response
Failures use the same envelope with errorId: 1 plus errorCode + errorDescription. See the error-code reference for the full list.
{
"errorId": 1,
"errorCode": "ERROR_CAPTCHA_UNSOLVABLE",
"errorDescription": "Solver gave up — automatically refunded."
}Pending response
While the solver is still working, getTaskResult returns status: "processing". Poll every 1–2 seconds until ready or failed.
{
"errorId": 0,
"status": "processing"
}Features
task types
proxyless: GeeTestTaskProxyLess
with proxy: GeeTestTask