MamaMia.By

[omo-servicePhymn]

How to Solve hCaptcha via API (Python)

If you are wondering how to solve hCaptcha in your automated QA suite, accessibility tooling, or authorized data-collection pipeline, the short answer is: read the page's sitekey and URL, send them to an hCaptcha solver API, poll for a token, and inject that token back into the page's h-captcha-response field. This tutorial walks through the full token flow with complete, copy-pasteable Python examples against the OMOCaptcha API V2.

What Is hCaptcha?

hCaptcha is a privacy-focused alternative to reCAPTCHA. It gained wide adoption when Cloudflare historically switched to it as a default challenge, and it is now common across e-commerce, SaaS logins, and enterprise sites. Instead of Google's tracking-heavy model, hCaptcha positions itself around user privacy and pays site owners for the human-labeling work behind the challenges.

For developers, the mechanics are similar to reCAPTCHA. A widget on the page carries a public sitekey. When solved, it produces a long token that the site's backend validates with hCaptcha's servers. hCaptcha also ships an Enterprise variant that can attach an extra rqdata payload; you must pass this through to the solver if it is present, otherwise the returned token will be rejected. A captcha solver handles that verification step for you, so your automation never has to click a checkbox itself. You can read the official widget details in the hCaptcha documentation (https://docs.hcaptcha.com/).

The Token Flow at a Glance

Solving hCaptcha automatically is a three-step loop:

1. Extract inputs grab the sitekey and the full page URL. For Enterprise, also capture rqdata.
2. Create a task POST /createTask with your clientKey and an hCaptcha token task, then receive a taskId.
3. Poll and inject POST /getTaskResult until status is ready, then place the returned token into textarea[name="h-captcha-response"] (and submit).

- Create (POST /createTask): send clientKey and task (sitekey + URL); receive taskId
- Poll (POST /getTaskResult): send clientKey and taskId; receive status and solution.gRecaptchaResponse

Every response returns HTTP 200. Success is decided by errorId (0 = success), following the standard two-step createTask/getTaskResult envelope. Tasks are also key-bound: only the API key that created a task can read its result, so a mismatched key returns ERROR_TASK_KEY_MISMATCH.

Note: the exact task type string for hCaptcha (shown below as HCaptchaTokenTask) should be confirmed in the OMOCaptcha API docs (https://omocaptcha.com/en?utm_source=blog&utm_medium=organic). The confirmed type values in this article are ImageToTextTask and RecaptchaV2TokenTask; the request/response shape for token captchas is identical.

Solve hCaptcha with Python

This example uses requests, polls politely with backoff, and always passes an HTTP timeout. Set your key in OMO_API_KEY.

import os
import time
from typing import Optional
import requests

API_BASE = "https://api.omocaptcha.com/v2"
CLIENT_KEY = os.environ["OMO_API_KEY"]

def create_task(sitekey: str, page_url: str, rqdata: Optional[str] = None) -> str:
task = dict(
type="HCaptchaTokenTask", # confirm exact type in the OMOCaptcha docs
websiteURL=page_url,
websiteKey=sitekey,
)
if rqdata: # Enterprise hCaptcha
task["enterprisePayload"] = dict(rqdata=rqdata)

resp = requests.post(
API_BASE + "/createTask",
json=dict(clientKey=CLIENT_KEY, task=task),
timeout=30,
)
data = resp.json()
if data.get("errorId") != 0:
raise RuntimeError("createTask failed: " + str(data.get("errorCode")) + " - " + str(data.get("errorDescription")))
return data["taskId"]

def get_result(task_id: str, max_wait: int = 120) -> str:
delay = 3 # start polite, then back off
waited = 0
while waited < max_wait:
resp = requests.post(
API_BASE + "/getTaskResult",
json=dict(clientKey=CLIENT_KEY, taskId=task_id),
timeout=30,
)
data = resp.json()
if data.get("errorId") != 0:
raise RuntimeError("getTaskResult error: " + str(data.get("errorCode")))

status = data.get("status")
if status == "ready":
return data["solution"]["gRecaptchaResponse"]
if status == "fail":
raise RuntimeError("Task failed to solve")

time.sleep(delay)
waited += delay
delay = min(delay + 2, 10) # gentle backoff, cap at 10s
raise TimeoutError("Timed out waiting for hCaptcha solution")

if __name__ == "__main__":
task_id = create_task(
sitekey="10000000-ffff-ffff-ffff-000000000001",
page_url="https://your-own-site.example/login",
)
token = get_result(task_id)
print("h-captcha-response token:", token[:40], "...")

Inject the token in your browser automation (Playwright/Selenium) like so:

document.querySelector('[name="h-captcha-response"]').value = TOKEN;

Solve hCaptcha with Python: alternative example (standard library only)

The same flow using only Python's standard library (urllib), no external dependencies needed.

import os
import json
import time
import urllib.request
from typing import Optional

API_BASE = "https://api.omocaptcha.com/v2"
CLIENT_KEY = os.environ["OMO_API_KEY"]

def post_json(path, body, timeout=30):
data = json.dumps(body).encode("utf-8")
headers = dict([("Content-Type", "application/json")])
req = urllib.request.Request(API_BASE + path, data=data, headers=headers, method="POST")
with urllib.request.urlopen(req, timeout=timeout) as resp:
return json.loads(resp.read().decode("utf-8"))

def create_task(sitekey: str, page_url: str, rqdata: Optional[str] = None) -> str:
task = dict(
type="HCaptchaTokenTask", # confirm exact type in the OMOCaptcha docs
websiteURL=page_url,
websiteKey=sitekey,
)
if rqdata: # Enterprise hCaptcha
task["enterprisePayload"] = dict(rqdata=rqdata)

data = post_json("/createTask", dict(clientKey=CLIENT_KEY, task=task))
if data.get("errorId") != 0:
raise RuntimeError("createTask: " + str(data.get("errorCode")))
return data["taskId"]

def get_result(task_id: str, max_wait: int = 120) -> str:
delay = 3
waited = 0
while waited < max_wait:
data = post_json("/getTaskResult", dict(clientKey=CLIENT_KEY, taskId=task_id))
if data.get("errorId") != 0:
raise RuntimeError("getTaskResult: " + str(data.get("errorCode")))
if data.get("status") == "ready":
return data["solution"]["gRecaptchaResponse"]
if data.get("status") == "fail":
raise RuntimeError("Task failed to solve")
time.sleep(delay)
waited += delay
delay = min(delay + 2, 10) # polite backoff
raise TimeoutError("Timed out waiting for hCaptcha solution")

if __name__ == "__main__":
task_id = create_task(
"10000000-ffff-ffff-ffff-000000000001",
"https://your-own-site.example/login",
)
token = get_result(task_id)
print("h-captcha-response token:", token[:40], "...")

Tips for Reliable hCaptcha Solving

- Keep the User-Agent consistent. Use the same UA when solving and when submitting the token. A mismatch is a common reason a valid-looking token gets rejected.
- Handle Enterprise rqdata. If the widget exposes rqdata, pass it through (enterprisePayload.rqdata). Skipping it produces tokens the backend will reject.
- Poll politely. Start at ~3 seconds and back off. OMOCaptcha averages a 0.42s solve time, so most tokens are ready in the first couple of polls; hammering the endpoint every 200ms only wastes both sides' resources.
- Match the page URL exactly. The websiteURL should be the real page hosting the widget.
- Respect the target. Only automate sites you own or are authorized to test, and honor robots.txt and rate limits.
- Route at scale through clean IPs. When your collection jobs run wide, send the requests through residential proxies (https://omoproxy.com/).

If you also work with other challenge systems, see our guides on how to solve reCAPTCHA (https://blog.omocaptcha.com/how-to-solve-recaptcha), the Cloudflare Turnstile solver (https://blog.omocaptcha.com/cloudflare-turnstile-solver), and the GeeTest solver (https://blog.omocaptcha.com/geetest-solver). For a broader survey, our best captcha solving service (https://blog.omocaptcha.com/best-captcha-solving-service-2026) roundup covers the full landscape.

Why OMOCaptcha Is a Reliable Captcha Solver for hCaptcha

OMOCaptcha is an AI-only service there is no human-farm queue to sit in with sub-second average solve time and up to 99% accuracy, trained across 14 captcha systems. One endpoint handles hCaptcha, reCAPTCHA, Turnstile, FunCaptcha, GeeTest and more, with SDKs for Python, JavaScript/Node.js, PHP, Java, .NET and Go. Traffic is end-to-end encrypted and captcha content is not stored.

- hCaptcha price: $0.60 per 1000 solves
- Headline pricing: from $0.27 per 1000
- Avg. solve time: 0.42s
- Accuracy: up to 99%
- Refund SLA: full refund if success drops below 95%

See full captcha solver API pricing (https://blog.omocaptcha.com/captcha-solver-api-pricing) or jump straight to the pricing page (https://omocaptcha.com/en#pricing). Compared with legacy hybrid providers, OMOCaptcha's AI-only pipeline skips the human-labeling queue entirely; see our best captcha solving service (https://blog.omocaptcha.com/best-captcha-solving-service-2026) breakdown.

FAQ

Is it legal to solve hCaptcha automatically?
Automating captcha solving is legitimate for use cases like QA and regression testing of your own forms, accessibility tooling, load testing, and authorized or contracted data collection. Always respect the target site's Terms of Service, robots.txt, and rate limits, and do not use it for fraud or fake-account creation.

What is the difference between an hCaptcha token and injecting it?
The solver API returns a token string. Solving is only half the job: you must place that token into the page's h-captcha-response field (and any callback the widget defines) so the form submission carries valid proof.

How do I handle hCaptcha Enterprise?
Enterprise widgets attach an extra rqdata payload. Capture it from the page and pass it in the task (enterprisePayload.rqdata). Without it, the returned token will fail backend validation.

Which task type string should I use for hCaptcha?
This guide uses HCaptchaTokenTask. Because confirmed types in the API are ImageToTextTask and RecaptchaV2TokenTask, verify the exact hCaptcha type string in the OMOCaptcha API docs; the create/poll flow is otherwise identical.

How fast is hCaptcha solving?
OMOCaptcha averages 0.42 seconds per solve, so with polite polling you typically get a ready token within the first one or two getTaskResult calls.

Get Started 1000 Free Solves

Ready to solve hCaptcha automatically in your own pipeline? Sign up at OMOCaptcha (https://omocaptcha.com/en?utm_source=blog&utm_medium=organic) and get 1000 free solves to test the token flow end to end. If the pipeline drives many isolated accounts, run each one through an antidetect browser (https://omobrowser.com/). Questions about integration or Enterprise rqdata? Email support@omocaptcha.com anytime, support is available 24/7. New here? Start with our captcha solver API quickstart (https://blog.omocaptcha.com/captcha-solver-api-quickstart).
_________________
Omo Service - AI captcha, antidetect browser & proxy solutions