GeeTest API Reference

Solve GeeTest v4 and v3 challenges and submit the result for site-owner verification.

The Captcha.fun GeeTest API accepts kind, url, siteKey and returns GeeTest v4 or v3 validate values. Send the API_KEY header, create a solve with POST /v1/request, then poll GET /v2/response/{id} until ready is true.

What you’ll need

Your API key
The URL of the page where the challenge appears
The site key from the page
Optional: geetestChallenge, geetestApiServer, geetestProduct, geetestLang, geetestNewCaptcha, geetestRiskType, geetestUserInfo
A proxy, if the result must come from your own IP (geetest_proxy)

Use kind

Good to Know

v4 (default): siteKey is the captchaId. Returns four fields for GeeTest’s validate endpoint.

v3: siteKey is the gt, and geetestChallenge is the challenge from your own register call. Returns geetest_challenge, geetest_validate, and geetest_seccode.

Optional: geetestApiServer for self-hosted v3, geetestRiskType for gated v4, and geetestUserInfo when v4 is bound to the site’s session.

Send the Challenge

Create Solve · POST /v1/request

Send the page details with your API key. You get a solve id back right away.

POSThttps://api.captcha.fun/v1/request

curl -X POST https://api.captcha.fun/v1/request \
  -H "API_KEY: CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "kind": "geetest",
  "url": "https://your-domain.example/login",
  "siteKey": "YOUR_GEETEST_CAPTCHA_ID"
}'

import requests

response = requests.post(
    "https://api.captcha.fun/v1/request",
    headers={
        "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={"kind": "geetest", "url": "https://your-domain.example/login", "siteKey": "YOUR_GEETEST_CAPTCHA_ID"},
)

print(response.status_code, response.json())

const response = await fetch("https://api.captcha.fun/v1/request", {
  method: "POST",
  headers: {
    "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
  "kind": "geetest",
  "url": "https://your-domain.example/login",
  "siteKey": "YOUR_GEETEST_CAPTCHA_ID"
})
});

console.log(response.status, await response.json());

Response

Returns the solve id. Use it to get the result.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Started Solving"
}

{
  "message": "invalid kind"
}

Request fields12 body fields · 3 required

Headers

Name	Type	Required	Description
API_KEY	string	Yes	Your API key
Content-Type	string	Yes	`application/json`
APP_ID	string	No	Optional app ID for request tracking

Body

Name	Type	Required	Description
kind	string	Yes	One of `geetest`, `geetest_proxy`
url	string	Yes	Page URL where the challenge appears
siteKey	string	Yes	Site key of the challenge
geetestChallenge	string	No	Required for v3. Challenge from your own register call; setting it switches the solve to v3. Challenges are single-use and short-lived — mint one fresh challenge per solve attempt and never retry a failed attempt with the same challenge
geetestApiServer	string	No	v3 only. Self-hosted API host. Omit for GeeTest’s servers
geetestProduct	string	No	Widget mode: `bind` (default), `popup`, or `float`
geetestLang	string	No	Widget language. Defaults to `eng` / `en`
geetestNewCaptcha	string	No	v3 only. `true` or `1` sends `new_captcha` on init
geetestRiskType	string	No	Gated v4 sites only. Site-issued risk token; without it `/load` fails with `illegal risk_type`
geetestUserInfo	string	No	v4 only. Site-issued `userInfo` JSON, e.g. `{"session_id":"..."}`, passed through as-is
proxy	string	No	For `_proxy` kinds: `host:port` or `host:port:username:password`
platform	string	No	Requested platform label: `windows` (default) or `mac`

Wait for the Result

Get Solve · GET /v2/response/{id}

Use the solve id to fetch the result.

GEThttps://api.captcha.fun/v2/response/{id}

Poll every second until ready is true.

GEThttps://api.captcha.fun/v1/response/{id}

Long polling: the request stays open until the solve finishes or times out. Send it once and wait.

Example

curl -X GET https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000 \
  -H "API_KEY: CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000",
    headers={
        "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "Accept": "application/json"
    }
)

print(response.status_code, response.json())

const response = await fetch(
  "https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000",
  {
    method: "GET",
    headers: {
      "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "Accept": "application/json"
    }
  }
);

const data = await response.json();
console.log(response.status, data);

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000", nil)
    req.Header.Set("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
    req.Header.Set("Accept", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(resp.StatusCode, result)
}

import java.net.http.*;
import java.net.URI;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000"))
            .header("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
            .header("Accept", "application/json")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

using System.Net.Http;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
client.DefaultRequestHeaders.Add("Accept", "application/json");

var response = await client.GetAsync("https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000");
var result = await response.Content.ReadAsStringAsync();

Console.WriteLine($"{(int)response.StatusCode} {result}");

Response

{
  "ready": true,
  "status": "SUCCESS",
  "success": true,
  "userAgent": "RETURNED_USER_AGENT",
  "secUa": "RETURNED_SEC_CH_UA",
  "token": "",
  "geetest": {
    "lot_number": "0241c2ef9dc0f0e5a3d0e1f5f2ad5c8d",
    "captcha_output": "5KAmMKVkldquKZ8DP5ehcG8LDv1brhRYgCbj9...",
    "pass_token": "8e035d781cd7f7c1d6c2f45ae2b0b8c8fb...",
    "gen_time": "1735689600"
  }
}

{
  "message": "API_KEY Header Missing"
}

Example

curl -X GET https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000 \
  -H "API_KEY: CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000",
    headers={
        "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "Accept": "application/json"
    }
)

print(response.status_code, response.json())

const response = await fetch(
  "https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000",
  {
    method: "GET",
    headers: {
      "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "Accept": "application/json"
    }
  }
);

const data = await response.json();
console.log(response.status, data);

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000", nil)
    req.Header.Set("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
    req.Header.Set("Accept", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(resp.StatusCode, result)
}

import java.net.http.*;
import java.net.URI;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000"))
            .header("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
            .header("Accept", "application/json")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

using System.Net.Http;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
client.DefaultRequestHeaders.Add("Accept", "application/json");

var response = await client.GetAsync("https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000");
var result = await response.Content.ReadAsStringAsync();

Console.WriteLine($"{(int)response.StatusCode} {result}");

Response

{
  "status": "SUCCESS",
  "success": true,
  "userAgent": "RETURNED_USER_AGENT",
  "secUa": "RETURNED_SEC_CH_UA",
  "token": "",
  "geetest": {
    "lot_number": "0241c2ef9dc0f0e5a3d0e1f5f2ad5c8d",
    "captcha_output": "5KAmMKVkldquKZ8DP5ehcG8LDv1brhRYgCbj9...",
    "pass_token": "8e035d781cd7f7c1d6c2f45ae2b0b8c8fb...",
    "gen_time": "1735689600"
  }
}

{
  "message": "API_KEY Header Missing"
}

Request and response fields13 response fields

Request

Name	Type	Required	Description
id	string (UUID)	Yes	Path parameter. The `id` from Create Solve
API_KEY	string	Yes	Header. Your API key

Response Fields

Name	Type	Required	Description
ready	boolean	—	`true` when the solve is finished (v2 only)
status	string	—	`PENDING` while solving, then `SUCCESS` or `FAILURE`
success	boolean	—	Whether the solve succeeded
userAgent	string	—	Value to send as `User-Agent` when using the result. Preserve it exactly
secUa	string	—	Value to send as `Sec-CH-UA` when using the result
geetest.lot_number	string	—	v4 lot number
geetest.captcha_output	string	—	v4 captcha output
geetest.pass_token	string	—	v4 pass token
geetest.gen_time	string	—	v4 generation time
geetest.geetest_challenge	string	—	v3 challenge
geetest.geetest_validate	string	—	v3 validate value
geetest.geetest_seccode	string	—	v3 seccode
message	string	—	Failure reason. Omitted on success

Submit the Token

GeeTest v4 or v3 validate values

v4: the site owner verifies lot_number, captcha_output, pass_token, and gen_time through GeeTest’s validate endpoint, using the HMAC-SHA256 sign_token.
v3: submit geetest_challenge, geetest_validate, and geetest_seccode to the site’s validate endpoint. The result is single-use, so use it right away.

When using a successful result, preserve the returned userAgent as User-Agent and secUa as Sec-CH-UA.

Wrong or rejected result? Report the failed solve.