Skip to content
On this page
Home
>Task(Token)
>HCaptcha

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, draw a box

and other question types

The task type types that we support:

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

hCaptcha SERVICE INSTABILITY ANNOUNCEMENT

We apologize for the recent instability of the hCaptcha service caused by image updates and other issues. We deeply regret any inconvenience caused. If you encounter new images that render the service unavailable, please wait for us to update them. For any other questions, feel free to contact us at any time.

Create Task

Create a task with the createTask to create a task.

Task Object Structure

PropertiesTypeRequiredDescription
typeStringRequiredHCaptchaTask
HCaptchaTaskProxyLess
websiteURLStringRequiredWeb address of the website using hcaptcha, generally it's fixed value. (Ex: https://google.com)
websiteKeyStringRequiredThe domain public key, rarely updated. (Ex: b989d9e8-0d14-41sda0-870f-97b5283ba67d)
isInvisibleBooleanOptionalSet true if it's a invisible captcha
proxyStringOptionalLearn Using proxies
enterprisePayloadObjectOptionalCustom 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
getCaptchaObjectOptionalif you get invalid response,you can try this param,you can learn by Solve HCaptcha
userAgentStringOptionalBrowser'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
    //Optional
    "getCaptcha": "fetch request base64 content",
    "userAgent": ""
  }
}

After you submit the task to us, you should receive in the response a 'Task id' 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

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",
})
go
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

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)
go
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"])
}