Geetest v4 Captcha Solver | CaptchaSonic Docs

Solve GeeTest v4 challenges using the GeetestImage task type. Set gtv: 4 and provide the v4 captchaId. The question field determines the challenge mode.

Supported Modes

Mode	`question`	Input	Response
Slide	`slide`	Background + slider (2 images)	`[x, y]` coordinates
Icon	`icon`	Main image + examples	Click coordinates
Nine-Grid	`nine`	9 grid images	Matching cell indices
Winlinze	`winlinze`	25 grid images	Cell indices

Create Task — Slide

POST/createTask

Hostapi.captchasonic.com

Content-Typeapplication/json

{
    "apiKey": "YOUR_API_KEY",
    "task": {
        "type": "GeetestImage",
        "gtv": 4,
        "question": "slide",
        "queries": ["BASE64_BACKGROUND", "BASE64_SLIDER"],
        "captchaId": "e392e1d7fd421dc63325744d5a2b9c73"
    }
}

Response

{
    "code": 200,
    "msg": "",
    "answers": [142, 160]
}

Create Task — Icon Click

{
    "apiKey": "YOUR_API_KEY",
    "task": {
        "type": "GeetestImage",
        "gtv": 4,
        "question": "icon",
        "queries": ["BASE64_MAIN_IMAGE"],
        "examples": ["BASE64_TARGET_1", "BASE64_TARGET_2"],
        "captchaId": "e392e1d7fd421dc63325744d5a2b9c73"
    }
}

Task Parameters

Property	Type	Required	Description
`type`	`string`	✅	`GeetestImage` or `GeetestClassification`
`gtv`	`integer`	No	GeeTest version — `4` for v4
`question`	`string`	✅	`slide`, `icon`, `nine`, `match`, or `winlinze`
`queries`	`string[]`	✅	Base64-encoded images
`examples`	`string[]`	Icon only	Target reference images
`captchaId`	`string`	✅	GeeTest v4 `captcha_id`
`proxy`	`string`	No	Proxy URL if needed

API Playground

POSTapi.captchasonic.com

Payload

{
  "apiKey": "YOUR_API_KEY",
  "task": {
    "type": "GeetestImage",
    "gtv": 4,
    "question": "slide",
    "queries": [
      "BASE64_BACKGROUND",
      "BASE64_SLIDER"
    ],
    "captchaId": "e392e1d7fd421dc63325744d5a2b9c73"
  }
}

{
  "apiKey": "YOUR_API_KEY",
  "task": {
    "type": "GeetestImage",
    "gtv": 4,
    "question": "slide",
    "queries": [
      "BASE64_BACKGROUND",
      "BASE64_SLIDER"
    ],
    "captchaId": "e392e1d7fd421dc63325744d5a2b9c73"
  }
}

Response

Hit Send to see response

⌘ + Enter

Parameters

apiKeystringYOUR_API_KEY

taskobject{...}

└ typestringGeetestImage

└ gtvnumber4

└ questionstringslide

└ queriesarray[2 items]

└ captchaIdstringe392e1d7fd421dc63325744d5a2b9c…

Error Codes

1KEY_DOES_NOT_EXIST— API key is invalid or not found.

2NO_SLOT_AVAILABLE— All solver slots are occupied.

3ZERO_BALANCE— Account balance is zero.

10ERROR_BAD_PARAMETERS— Invalid or missing request fields.

12ERROR_CAPTCHA_UNSOLVABLE— Captcha could not be solved.

14PLAN_EXPIRED— Your plan has expired.

16RATE_LIMITED— Too many requests. Slow down.

17DAILY_LIMIT_EXCEEDED— Daily usage limit reached.

18QUOTA_LIMIT_EXCEEDED— Plan quota exhausted.

21SERVICE_UNAVAILABLE— Backend is temporarily unavailable.

Code

terminal