HCaptcha: solving HCaptcha

Create the task with the createTask method and get the result with

the getTaskResult method.

Now we have met the requirements of almost all high score websites, and also support invisible

ℹ️Please be sure to use the userAgent returned by our API.

If our token is not accepted, please contact us

The task type types that we support:

HCaptchaTask this task type require your own proxies
HCaptchaTaskProxyLess is using the server's built-in proxy

Create Task

Create a task with the createTask to create a task.

Task Object Structure

Properties	Type	Required	Description
type	String	Required	`HCaptchaTask` `HCaptchaTaskProxyLess`
websiteURL	String	Required	Web address of the website using hcaptcha, generally it's fixed value. (Ex: https://google.com)
websiteKey	String	Required	The domain public key, rarely updated. (Ex: `b989d9e8-0d14-41sda0-870f-97b5283ba67d`)
isInvisible	Boolean	Optional	Set `true` if it's a invisible captcha
proxy	String	Optional	Learn Using proxies
enterprisePayload	Object	Optional	Custom data that is used in some implementations of hCaptcha Enterprise. So you need to put true in the isEnterprise parameter. In most cases you see it as `rqdata` inside network requests. IMPORTANT: you MUST provide `userAgent` if you submit captcha with `data` parameter. The value should match the User-Agent you use when interacting with the target website,you can learn by how to get HCaptcha rqdata
userAgent	String	Optional	Browser's User-Agent which is used in emulation. It is required that you use a signature of a modern browser, otherwise Google will ask you to "update your browser".

Example Request

txt

POST https://api.capsolver.com/createTask
Host: api.capsolver.com
Content-Type: application/json

json

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    //Required. Can use HCaptchaTaskProxyless or HCaptchaTask
    "type": "HCaptchaTaskProxyLess",
    //Required
    "websiteURL": "",
    // Required
    "websiteKey": "00000000-0000-0000-0000-000000000000",
    // Optional
    "isInvisible": true,
    // Optional
    "enterprisePayload": {
      //Optional, required if the site have HCaptcha Enterprise
      "rqdata": ""
    },
    //Optional, this is required if you use HCaptchaTask
    "proxy": "http:ip:port:user:pass",
    // socks5:ip:port:user:pass
    "userAgent": ""
  }
}

After you submit the task to us, you should receive in the response a 'taskId' if it's successful. Please read errorCode: full list of errors if you didn't receive the task id.

Example Response

json

{
  "errorId": 0,
  "errorCode": "",
  "errorDescription": "",
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}

Getting Result

Use the getTaskResult method to get the recognition results

Depending on the system load, you will get the results within the interval of 1s to 10s

Example Request

json

POST https://api.capsolver.com/getTaskResult
Host: api.capsolver.com
Content-Type: application/json

{
  "clientKey": "YOUR_API_KEY",
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}

Example Response

json

{
  "errorId": 0,
  "errorCode": null,
  "errorDescription": null,
  "solution": {
    //userAgent used to solve the captcha
    "userAgent": "xxx",
    //expireTime of the token
    "expireTime": 1671615324290,
    "timestamp": 1671615024290,
    "captchaKey": "E0_xxx",
    //token of the captcha
    "gRecaptchaResponse": "3AHJ....."
  },
  "status": "ready"
}

Use SDK Request

pythongolang

python

# pip install --upgrade capsolver
# export CAPSOLVER_API_KEY='...'

import capsolver

# capsolver.api_key = "..."
solution = capsolver.solve({
    "type": "HCaptchaTaskProxyLess",
    "websiteURL": "",
    "websiteKey": "00000000-0000-0000-0000-000000000000",
})

package main

import (
	"fmt"
	capsolver_go "github.com/capsolver/capsolver-go"
	"log"
)

func main() {
	// first you need to install sdk
	//go get github.com/capsolver/capsolver-go

	capSolver := capsolver_go.CapSolver{ApiKey: "..."}
	solution, err := capSolver.Solve(map[string]any{
		"type":       "HCaptchaTaskProxyLess",
		"websiteURL": "https://www.yourwebsite.com",
		"websiteKey": "00000000-0000-0000-0000-000000000000",
	})
	if err != nil {
		log.Fatal(err)
		return
	}
	fmt.Println(solution)
}

Sample Code

pythongolangjavascriptjava

python

# pip install requests
import requests
import time

# TODO: set your config
api_key = "YOUR_API_KEY"  # your api key of capsolver
site_key = "00000000-0000-0000-0000-000000000000"  # site key of your target site
site_url = "https://www.yourwebsite.com"  # page url of your target site


def capsolver():
    payload = {
        "clientKey": api_key,
        "task": {
            "type": 'HCaptchaTaskProxyLess',
            "websiteKey": site_key,
            "websiteURL": site_url
        }
    }
    res = requests.post("https://api.capsolver.com/createTask", json=payload)
    resp = res.json()
    task_id = resp.get("taskId")
    if not task_id:
        print("Failed to create task:", res.text)
        return
    print(f"Got taskId: {task_id} / Getting result...")

    while True:
        time.sleep(1)  # delay
        payload = {"clientKey": api_key, "taskId": task_id}
        res = requests.post("https://api.capsolver.com/getTaskResult", json=payload)
        resp = res.json()
        status = resp.get("status")
        if status == "ready":
            return resp.get("solution", {}).get('gRecaptchaResponse')
        if status == "failed" or resp.get("errorId"):
            print("Solve failed! response:", res.text)
            return


token = capsolver()
print(token)

package main

import (
	"bytes"
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"net/http"
	"time"
)

type capSolverResponse struct {
	ErrorId          int32          `json:"errorId"`
	ErrorCode        string         `json:"errorCode"`
	ErrorDescription string         `json:"errorDescription"`
	TaskId           string         `json:"taskId"`
	Status           string         `json:"status"`
	Solution         map[string]any `json:"solution"`
}

func capSolver(ctx context.Context, apiKey string, taskData map[string]any) (*capSolverResponse, error) {
	uri := "https://api.capsolver.com/createTask"
	res, err := request(ctx, uri, map[string]any{
		"clientKey": apiKey,
		"task":      taskData,
	})
	if err != nil {
		return nil, err
	}
	if res.ErrorId == 1 {
		return nil, errors.New(res.ErrorDescription)
	}

	uri = "https://api.capsolver.com/getTaskResult"
	for {
		select {
		case <-ctx.Done():
			return res, errors.New("solve timeout")
		case <-time.After(time.Second):
			break
		}
		res, err = request(ctx, uri, map[string]any{
			"clientKey": apiKey,
			"taskId":    res.TaskId,
		})
		if err != nil {
			return nil, err
		}
		if res.ErrorId == 1 {
			return nil, errors.New(res.ErrorDescription)
		}
		if res.Status == "ready" {
			return res, err
		}
	}
}

func request(ctx context.Context, uri string, payload interface{}) (*capSolverResponse, error) {
	payloadBytes, err := json.Marshal(payload)
	if err != nil {
		return nil, err
	}
	req, err := http.NewRequestWithContext(ctx, "POST", uri, bytes.NewReader(payloadBytes))
	if err != nil {
		return nil, err
	}
	req.Header.Set("Content-Type", "application/json")
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	responseData, err := io.ReadAll(resp.Body)
	if err != nil {
		return nil, err
	}
	capResponse := &capSolverResponse{}
	err = json.Unmarshal(responseData, capResponse)
	if err != nil {
		return nil, err
	}
	return capResponse, nil
}

func main() {
	apikey := "YOUR_API_KEY"
	ctx, cancel := context.WithTimeout(context.Background(), time.Second*120)
	defer cancel()

	res, err := capSolver(ctx, apikey, map[string]any{
		"type":       "HCaptchaTaskProxyLess",
		"websiteURL": "https://www.yourwebsite.com",
		"websiteKey": "00000000-0000-0000-0000-000000000000",
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(res.Solution["gRecaptchaResponse"])
}

javascript

// npm install axios
const axios = require('axios');

const api_key = "YOUR_API_KEY";
const site_key = "00000000-0000-0000-0000-000000000000";
const site_url = "https://www.yourwebsite.com";

async function capsolver() {
  const payload = {
    clientKey: api_key,
    task: {
      type: 'HCaptchaTaskProxyLess',
      websiteKey: site_key,
      websiteURL: site_url
    }
  };

  try {
    const res = await axios.post("https://api.capsolver.com/createTask", payload);
    const task_id = res.data.taskId;
    if (!task_id) {
      console.log("Failed to create task:", res.data);
      return;
    }
    console.log("Got taskId:", task_id);

    while (true) {
      await new Promise(resolve => setTimeout(resolve, 1000)); // Delay for 1 second

      const getResultPayload = {clientKey: api_key, taskId: task_id};
      const resp = await axios.post("https://api.capsolver.com/getTaskResult", getResultPayload);
      const status = resp.data.status;

      if (status === "ready") {
        return resp.data.solution.gRecaptchaResponse;
      }
      if (status === "failed" || resp.data.errorId) {
        console.log("Solve failed! response:", resp.data);
        return;
      }
    }
  } catch (error) {
    console.error("Error:", error);
  }
}

capsolver().then(token => {
  console.log(token);
});

java

package org.example.capsolver;
import org.json.JSONObject;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.HashMap;
import java.util.Map;
import java.util.Objects;

public class HCaptcha {
    public static String API_KEY = "YOUR_API_KEY"; 
    public static String SITE_URL = "https://www.yourwebsite.com";
    public static String SITE_KEY = "00000000-0000-0000-0000-000000000000";  // site key of your target site

    public static void capsolver() throws IOException, InterruptedException {
        JSONObject param = new JSONObject();
        Map<String, Object> task = new HashMap<>();
        task.put("type", "HCaptchaTaskProxyLess");
        task.put("websiteURL", SITE_URL);
        task.put("websiteKey", SITE_KEY);
        param.put("clientKey", API_KEY);
        param.put("task", task);
        String taskId = createTask(param);

        if (Objects.equals(taskId, "")) {
            System.out.println("Failed to create task");
            return;
        }
        System.out.println("Got taskId: "+taskId+" / Getting result...");
        while (true){
            Thread.sleep(1000);
            String token = getTaskResult(taskId);
            if (Objects.equals(token, null)) {
                continue;
            }
            System.out.println(token);
            break;
        }
    }

    public static String requestPost(String url, JSONObject param) throws IOException {
        URL ipapi = new URL(url);
        HttpURLConnection c = (HttpURLConnection) ipapi.openConnection();
        c.setRequestMethod("POST");
        c.setDoOutput(true);

        OutputStream os = null;
        os = c.getOutputStream();
        os.write(param.toString().getBytes("UTF-8"));

        c.connect();
        BufferedReader reader = new BufferedReader(
            new InputStreamReader(c.getInputStream())
        );
        String line;
        StringBuilder sb = new StringBuilder();
        while ((line = reader.readLine()) != null)
        { sb.append(line); }

        return sb.toString();
    }

    public static String createTask(JSONObject param) throws IOException {
        String parsedJsonStr = requestPost("https://api.capsolver.com/createTask", param);
        JSONObject responseJson = new JSONObject(parsedJsonStr);
        return responseJson.get("taskId").toString();
    }

    public static String getTaskResult(String taskId) throws IOException {
        JSONObject param = new JSONObject();
        param.put("clientKey", API_KEY);
        param.put("taskId", taskId);
        String parsedJsonStr = requestPost("https://api.capsolver.com/getTaskResult", param);
        JSONObject responseJson = new JSONObject(parsedJsonStr);

        String status = responseJson.getString("status");
        if (status.equals("ready")) {
            JSONObject solution = responseJson.getJSONObject("solution");
            return solution.getString("gRecaptchaResponse");
        }
        if (status.equals("failed") || responseJson.getInt("errorId")!=0) {
            System.out.println("Solve failed! response: "+parsedJsonStr);
            return "error";
        }
        return null;
    }
}

HCaptcha: solving HCaptcha ​

Create Task ​

Task Object Structure ​

Example Request ​

Example Response ​

Getting Result ​

Example Request ​

Example Response ​

Use SDK Request ​

Sample Code ​

HCaptcha: solving HCaptcha

Create Task

Task Object Structure

Example Request

Example Response

Getting Result

Example Request

Example Response

Use SDK Request

Sample Code