GeeTest v4 Solver API: seccode Fields via REST

Solve GeeTest v4 slide challenges with the SolveHub API and receive the five seccode fields to submit to the site, including full risk_type passthrough.

For authorized QA automation and browser integration. Use only on websites and workflows you have permission to test.

For GeeTest v4 slide challenges, returning the five seccode fields that must be submitted to the site. Only slide challenges whose riskType starts with slide are supported; continue through the same proxy exit after a solve.

Request fields

The outer type and task are required; the task.* paths below live inside the task object. Field names are case-sensitive. Length limits are in UTF-8 bytes.

Field	Type	Required	Limits	Description
`type`	string	yes	fixed `geetest_v4`	Platform task type.
`task`	JSON object	yes	≤ 7 MiB	Task parameters for this type.
`task.type`	string	no	must be `geetest_v4` when present	Legacy request format; omit in new integrations.
`task.captchaId`	string	yes	32 hex characters	The `captcha_id` from the page configuration.
`task.riskType`	non-empty string	no	≤ 512 bytes	The site's `risk_type` passed verbatim (including any `
`task.sessionId`	non-empty string	no	≤ 256 bytes	Passed as `user_info.session_id` to GeeTest `/load`; required by some sites.
`task.lang`	non-empty string	no	≤ 16 bytes	Widget language for `/load`, defaults to `eng`.
`task.websiteURL`	HTTP(S) URL	no	≤ 2048 bytes	Page URL, informational only.
`task.proxyType`	string	yes	`http` / `https` / `socks5`	Proxy scheme.
`task.proxyAddress`	non-empty string	yes	≤ 256 bytes	Proxy address.
`task.proxyPort`	string	yes	1–5 bytes, value 1–65535	Proxy port as a quoted numeric string.
`task.proxyLogin`	non-empty string	no	≤ 256 bytes	Proxy username.
`task.proxyPassword`	non-empty string	no	≤ 256 bytes	Proxy password.

Create request example

{
  "type": "geetest_v4",
  "task": {
    "captchaId": "e392e1d7fd421dc63325744d5a2b9c73",
    "riskType": "slide",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080"
  }
}

cURL call

Replace the Key, site and proxy values in the example with your own; keep the same Idempotency-Key when retrying the same business request.

curl -sS -X POST 'https://www.tiam.codes/v1/tasks' \
  -H 'Authorization: Bearer sh_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-geetest-v4-0001' \
  --data-binary @- <<'JSON'
{
  "type": "geetest_v4",
  "task": {
    "captchaId": "e392e1d7fd421dc63325744d5a2b9c73",
    "riskType": "slide",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080"
  }
}
JSON

Create response and polling

A successful creation returns HTTP 202 with status usually queued. Save the taskId and poll GET /v1/tasks/{taskId} every 2–3 seconds. The soft processing window for this type is 120 seconds; beyond it a task may become uncertain, and results of accepted tasks can still be checked — do not create a replacement task with a new idempotency key.

Result fields

Read solution only when status=completed; the table lists common fields and the actual response is authoritative.

Field	Type	How to read
`solution.captcha_id`	string	The site `captcha_id`, echoed back.
`solution.lot_number`	string	The `lot_number` verify parameter.
`solution.pass_token`	string	The `pass_token` verify parameter.
`solution.gen_time`	string	The `gen_time` verify parameter.
`solution.captcha_output`	string	The `captcha_output` verify parameter.
`solution.userAgent`	string	Use the same User-Agent when submitting the verify parameters.

Submit the five seccode fields to the site verbatim; pass a riskType with its | suffix complete, because truncation causes ERROR_BAD_PARAMETERS.

Failures and troubleshooting

Only slide challenges whose riskType starts with slide are supported; success depends on proxy IP reputation. A truncated riskType, a captchaId that is not 32 hex characters, or an unreachable proxy fails the task.

Common creation errors are 400 INVALID_TASK, 402 INSUFFICIENT_BALANCE, 429 TASK_LIMIT_EXCEEDED and 503 TYPE_UNAVAILABLE. Failed created tasks expose TASK_FAILED or TASK_TIMEOUT; uncertain maps to TASK_UNCERTAIN. See the platform API reference.

The processing window starts when the task is created; the platform abandons unfinished tasks after about 90 seconds without charging.

GeeTest v4 Slide Solver API