To detect CAPTCHA type on a page, read the page’s HTML for the widget’s script and container, pull the sitekey out of them, and map the family to the CapSkip method that solves it. A reCAPTCHA v2 box, a v3 script and a Turnstile widget need three different calls with different options, and a wrong guess wastes a whole solve and gives you a token you cannot use. This guide builds a detector of about 175 lines in Python that returns the type, the method and the arguments, or says plainly that it cannot tell. CapSkip runs on your own Windows PC with no per-solve fee, so a script that checks a hundred pages costs nothing extra.<\/p>\n
How this was tested: the detector ran against 66 saved pages and every page returned the expected result. Of those, 59 were built by hand (about 40 follow the vendors’ documentation, the rest are edge cases I made up) and 7 are snapshots of public pages taken on 29 October 2026. The solves ran through the real capskip package against a mock CapSkip that copies the app’s input checks. The real app was not running, so no number below is a solve time.<\/p>\n
CapSkip has a different method for each family: recaptcha, turnstile, geetest, altcha, capy, captchafox, friendly_captcha and normal for images in the SDK, plus hcaptcha on the HTTP API, which the SDK does not wrap yet. Within reCAPTCHA the options matter too. Invisible, Enterprise and v3 are flags on the same call. Send the wrong ones and the best case is a failed job, the worst a token the site rejects with no hint why. I could not check which one the real app does for a wrong reCAPTCHA version. Either way the solve is spent.<\/p>\n
Other mistakes fail fast and loudly. Reading the sitekey from a page that renders reCAPTCHA explicitly gives the word explicit, and CapSkip refuses it with ERROR_GOOGLEKEY. The ERROR_GOOGLEKEY and ERROR_PAGEURL guide<\/a> covers that error from the other side. To detect CAPTCHA type reliably, a detector has to check the signals in a fixed order, and that order avoids both kinds of mistake. A detector is also the first thing to build before a scraper that meets more than one site. If you want the background on what each type is, what a CAPTCHA is<\/a> explains the families without code.<\/p>\n Create a virtual environment in an empty folder and install the two packages. The commands call the environment’s own Python by path, so you do not need to activate it.<\/p>\n To detect CAPTCHA type from text, the detector needs only two inputs: the page’s HTML and its address. Fetch the page with a requests Session and keep that Session, because the image CAPTCHA step later downloads the picture with the same cookies. A plain requests fetch shows what the server sends before any JavaScript runs. Google’s reCAPTCHA demo pages, Cloudflare’s Turnstile demo and the hCaptcha demo all carry their widget in that HTML. Pages that add the widget with JavaScript do not, and the section “When the HTML says nothing” covers that case.<\/p>\n Save everything from here to Step 9 in one file called detect.py, one block after another. The first block imports what is needed and writes four small readers. Each returns None when nothing matches, so a missing attribute never raises.<\/p>\n The grab function returns the first capture group that matched. The tag function finds an opening tag by CSS class and refuses a class that only contains the name inside a longer one, so a class called cf-turnstile-response is not a Turnstile widget. The attr function reads an attribute written with either quote style and unescapes HTML entities, which matters for a challenge held in an attribute. Unquoted attributes are not read.<\/p>\n The second block turns a page into something the checks can share. It strips comments and style blocks, so a CSS rule that mentions a widget class cannot match, and it collects the script addresses and the inline JavaScript separately. The last two helpers build the two possible answers: a hit, or a needs_browser answer.<\/p>\n Start with the pages where the right answer is no. CapSkip does not solve FunCaptcha or Arkose, and GeeTest v4 is outside the GeeTest method, which is for v3. If the detector skipped those, a page with an Arkose box would fall through to the next check and might come back as something it is not. So this check runs first and returns a result with no method.<\/p>\n The same block handles the Cloudflare full-page check, the “Just a moment” interstitial. That page is not a Turnstile widget. The turnstile method needs two values from it, data and pagedata, and a plain fetch does not hold them. The detector looks for the page’s inline challenge options and answers needs_browser. The cf_clearance guide<\/a> covers what comes after a challenge page is passed.<\/p>\n hCaptcha comes next, before reCAPTCHA. CapSkip solves it, whether the widget is a checkbox, invisible or Enterprise, but a site that moved from reCAPTCHA to hCaptcha often keeps the g-recaptcha class on its widget, and only the hCaptcha script tells the two apart. The check reads the sitekey from the widget or from an hcaptcha.render call, and adds invisible when the widget has data-size set to invisible. An Enterprise page that hands the widget an rqdata value through hcaptcha.setData gets needs_browser instead, because that value is issued for one challenge and expires quickly.<\/p>\n reCAPTCHA needs the most care because several CapSkip variants share two script names. The order of questions is what keeps them apart. First the script name: enterprise.js means the Enterprise flag, api.js does not. Then the render parameter in the script address. A key after render= means v3, but the word explicit after render= means a v2 page that renders its widget from code, and it must never be used as a key. Then the markup. A button with the g-recaptcha class and a data-action attribute is Google’s v3 button binding. A button without data-action, or any element with data-size set to invisible, is the invisible v2 widget. Anything else with the class is the checkbox.<\/p>\n Each outcome maps to a call you already know. A checkbox is solver.recaptcha with a sitekey and the page URL. Invisible adds invisible=1, Enterprise adds enterprise=1, and v3 adds version="v3" and the action. The action name comes from the data-action attribute or from the page’s execute call; if neither is in the HTML, the argument is left out and CapSkip uses its default of verify. See the reCAPTCHA solver page<\/a> for every variant it handles.<\/p>\n A Turnstile widget needs two things on the page: Cloudflare’s api.js and a sitekey. The key sits in a data-sitekey attribute on a div with the cf-turnstile class, or in a turnstile.render call. The check requires the script, so a stray class name on an unrelated page cannot trigger it. It also reads data-action and data-cdata when they are present and passes them on. The Turnstile solver page<\/a> lists the options.<\/p>\n GeeTest v3 gives you two values, and one of them is a trap. The gt value is fixed for the site and can sit in the page. The challenge value is single-use, and sites fetch it from a register endpoint at run time. If the page carries both, the detector returns them. If it carries only the initGeetest call, it answers needs_browser, because a challenge found in old HTML would already be dead.<\/p>\n ALTCHA changed its attribute names between generations. Versions 1 and 2 use challengeurl, or challengejson for an inline challenge. Version 3 and later use one attribute called challenge, which takes either a URL or the challenge data. The check reads all three and joins a relative URL to the page address.<\/p>\n These three are easy to find and easy to get slightly wrong. Capy needs no widget div for this check. Its key starts with PUZZLE_ and sits in the k parameter of the widget script’s address, and a host other than the default is passed as api_server. CaptchaFox comes in two builds. The plain one loads from cdn.captchafox.com. The other is bundled by a hosting platform under a shared CDN path, so the detector looks for the CaptchaFox package name in that path and not for the path alone, which other widgets also use.<\/p>\n Friendly Captcha is the trickiest. Version 1 and version 2 use the same div and the same sitekey namespace, but different protocols, and a token for the wrong one is accepted by CapSkip and rejected by the site. The scripts tell them apart: version 2 loads the @friendlycaptcha\/sdk package, version 1 loads friendly-challenge. When the page gives no sign, the detector refuses to guess and says needs_browser.<\/p>\n Each of these has its own solver page with the options the method takes:<\/p>\n An image CAPTCHA has no vendor script to find, so this check is a guess and runs only when nothing else matched. The check wants an image whose tag says captcha, and a text box elsewhere on the page whose tag says captcha or security code. It missed in every case where the markup did not use those words, and a drawn canvas is invisible to it. Treat a hit as likely, not certain.<\/p>\n The last block lists the checks in order and exposes detect and solve, with detect_all as a helper. The order is the logic: unsupported vendors first, then the Cloudflare page, then hCaptcha, then each other family, and the image guess only when the list found nothing. The detect function returns the first result and adds an also list when the page carries more than one family, for example a v3 script plus a Turnstile box. The list names families, not a second reCAPTCHA widget with another key. The solve function dispatches the result to the right CapSkip method. It refuses anything unsupported or marked needs_browser with a RuntimeError, and it downloads an image through your own Session so the cookies match.<\/p>\n The SDK has no hCaptcha call yet, so an hCaptcha result goes to solve_hcaptcha instead. It posts the sitekey and the page address to in.php with method=hcaptcha, then polls res.php every 5 seconds until the token is ready, as the hCaptcha section of the API docs<\/a> describes. Pass the solver’s address as api, and your API key as key if API key validation is switched on. The result carries the token in code and the User-Agent it was earned with in userAgent.<\/p>\n Save this as use.py next to detect.py and run it with the environment’s own Python, as in .\\.venv\\Scripts\\python.exe use.py. The port 8080 is the default; use the port shown in CapSkip’s connection settings if yours differs. The script fetches your page, prints what the detector found, and only calls CapSkip when there is a method to call and nothing is missing.<\/p>\n On a page with a reCAPTCHA v2 checkbox the first print shows the type, the method and the arguments, and the second shows the result with the token in its code field. In the mock run it looked like this:<\/p>\nStep 1: install and fetch the page<\/h2>\n
py -m venv .venv\n.\\.venv\\Scripts\\python.exe -m pip install capskip requests<\/pre>\n<\/div>\n
Step 2: write the helpers<\/h2>\n
import base64, html as htmllib, re, time\nfrom types import SimpleNamespace as NS\nfrom urllib.parse import urljoin\nimport requests\n\nSITEKEY_JS = r"sitekey['\\"]?\\s*:\\s*['\\"]([^'\\"]+)" # sitekey: '...' inside a render() call\n\n\ndef grab(pattern, text): # first capture group that matched, or None\n m = re.search(pattern, text or "", re.I | re.S)\n return next(g for g in m.groups() if g is not None) if m else None\n\ndef tag(cls, h): # opening tag with CSS class cls (and not g-recaptcha-response)\n pat = r'(<\\w+[^>]*\\sclass\\s*=\\s*["\\'][^"\\']*(?<![\\w-])%s(?![\\w-])[^"\\']*["\\'][^>]*>)'\n return grab(pat % cls, h)\n\ndef attr(t, name): # attribute value from a tag string, either quote style, HTML-unescaped\n v = grab(r'\\s%s\\s*=\\s*(?:"([^"]*)"|\\'([^\\']*)\\')' % name, t)\n return None if v is None else htmllib.unescape(v)\n\ndef render_opts(call, js): # first 400 characters of the options in call(el, {...})\n return grab(call + r"\\([^,]+,\\s*\\{(.{0,400})", js)<\/pre>\n<\/div>\ndef parse(html, url):\n h = re.sub(r"<!--.*?-->|<style\\b.*?<\/style>", "", html, flags=re.S | re.I)\n srcs = " ".join(re.findall(r'<script\\b[^>]*?\\ssrc\\s*=\\s*["\\']([^"\\']+)', h, re.I))\n js = "\\n".join(re.findall(r"<script\\b[^>]*>(.*?)<\/script>", h, re.S | re.I))\n return NS(h=h, srcs=htmllib.unescape(srcs), js=js, url=url)\n\ndef hit(kind, method, **args):\n return {"type": kind, "method": method, "args": args}\n\ndef browser(kind, method, p, why): # the static HTML is not enough, so do not guess\n return {"type": kind, "method": method, "args": {"url": p.url}, "needs_browser": why}<\/pre>\n<\/div>\nStep 3: hCaptcha, and what CapSkip cannot solve<\/h2>\n
UNSUPPORTED = {"arkose": r"arkoselabs\\.com\/v2\/|funcaptcha\\.com\/fc\/", "geetest_v4": r"gt4\\.js|initGeetest4"}\n\ndef unsupported(p): # CapSkip cannot solve these: say so instead of misleading the reader\n for kind, pat in UNSUPPORTED.items():\n if re.search(pat, p.srcs + " " + p.js):\n return {"type": kind, "method": None, "args": {}, "unsupported": True}\n\ndef cf_challenge(p): # the full-page "Just a moment..." interstitial, not a widget\n if re.search(r"_cf_chl_opt\\s*=\\s*\\{", p.js):\n why = "data and pagedata (Cloudflare calls them cData and chlPageData) only exist at run time"\n return browser("turnstile_challenge", "turnstile", p, why)\n\ndef hcaptcha(p): # before reCAPTCHA: a site that moved to hCaptcha may keep the g-recaptcha class\n if not re.search(r"hcaptcha\\.com\/1\/api\\.js", p.srcs + " " + p.js):\n return None\n if re.search(r"\\.setData\\s*\\(|rqdata", p.js): # Enterprise rqdata is issued per challenge\n return browser("hcaptcha_enterprise", "hcaptcha", p, "rqdata is issued for one challenge at run time")\n w = tag("h-captcha", p.h) or tag("g-recaptcha", p.h)\n key = attr(w, "data-sitekey") or grab(SITEKEY_JS, render_opts(r"hcaptcha\\.render", p.js))\n if not key:\n return browser("hcaptcha", "hcaptcha", p, "no sitekey in the static HTML")\n args = {"sitekey": key, "url": p.url}\n if attr(w, "data-size") == "invisible":\n args["invisible"] = 1\n return hit("hcaptcha", "hcaptcha", **args)<\/pre>\n<\/div>\nStep 4: reCAPTCHA, in the right order<\/h2>\n
def recaptcha(p): # Enterprise flag first, then v3 (render=KEY), then v2\n m = re.search(r"\/recaptcha\/(api|enterprise)\\.js(\\?\\S*)?", p.srcs)\n if not m:\n return None\n ent = {"enterprise": 1} if m.group(1) == "enterprise" else {}\n render = grab(r"[?&]render=([^&\\s]+)", m.group(2)) # a v3 sitekey, or "explicit" (a v2 page)\n t, o = tag("g-recaptcha", p.h), render_opts(r"\\.render", p.js)\n button, action = (t or "").lower().startswith("<button"), attr(t, "data-action")\n v3 = bool(render and render != "explicit") or bool(button and action)\n key = render if render != "explicit" else None\n key = key or attr(t, "data-sitekey") or grab(SITEKEY_JS, o)\n if not key:\n return browser("recaptcha", "recaptcha", p, "no sitekey in the static HTML (set by JavaScript)")\n small = attr(t, "data-size") == "invisible" or grab(r"size['\\"]?\\s*:\\s*['\\"](invisible)", o)\n invisible = not v3 and bool(button or small)\n action = action or grab(r"execute\\(\\s*[^,)]+,\\s*\\{\\s*['\\"]?action['\\"]?\\s*:\\s*['\\"]([^'\\"]+)", p.js)\n args = {"sitekey": key, "url": p.url, **ent}\n if v3:\n args.update(version="v3", **({"action": action} if action else {}))\n if invisible:\n args["invisible"] = 1\n kind = "recaptcha_" + ("v3" if v3 else "v2_invisible" if invisible else "v2")\n return hit(kind + ("_enterprise" if ent else ""), "recaptcha", **args)<\/pre>\n<\/div>\nStep 5: Turnstile<\/h2>\n
def turnstile(p): # widget only: implicit (div.cf-turnstile) or explicit (turnstile.render)\n if "challenges.cloudflare.com\/turnstile\/v0\/api.js" not in p.srcs:\n return None\n t, o = tag("cf-turnstile", p.h), render_opts(r"turnstile\\.render", p.js)\n key = attr(t, "data-sitekey") or grab(SITEKEY_JS, o)\n if not key:\n return browser("turnstile", "turnstile", p, "no sitekey in the static HTML")\n action = attr(t, "data-action") or grab(r"\\baction['\\"]?\\s*:\\s*['\\"]([^'\\"]+)", o)\n cdata = attr(t, "data-cdata") or grab(r"\\bcData['\\"]?\\s*:\\s*['\\"]([^'\\"]+)", o)\n extra = {k: v for k, v in (("action", action), ("data", cdata)) if v}\n return hit("turnstile", "turnstile", sitekey=key, url=p.url, **extra)<\/pre>\n<\/div>\nStep 6: GeeTest and ALTCHA<\/h2>\n
def geetest(p): # v3 only: gt is static, challenge comes from the register endpoint\n if not (re.search(r"initGeetest\\s*\\(", p.js) or re.search(r"\/gt(\\.[\\d.]+)?\\.js", p.srcs)):\n return None\n gt = grab(r"\\bgt['\\"]?\\s*:\\s*['\\"]([0-9a-f]{32})", p.js)\n challenge = grab(r"\\bchallenge['\\"]?\\s*:\\s*['\\"]([0-9a-f]{32,34})", p.js)\n if not (gt and challenge):\n return browser("geetest", "geetest", p, "gt and challenge come from the register endpoint")\n return hit("geetest", "geetest", gt=gt, challenge=challenge, url=p.url)\n\ndef altcha(p): # challengeurl \/ challengejson (v1, v2) or challenge (v3+)\n t = grab(r"(<altcha-widget\\b[^>]*>)", p.h)\n if not t:\n return None\n c = attr(t, "challenge")\n as_json = attr(t, "challengejson") or (c if (c or "").lstrip().startswith("{") else None)\n as_url = attr(t, "challengeurl") or (None if as_json else c)\n if as_json:\n return hit("altcha", "altcha", url=p.url, challenge_json=as_json)\n if as_url:\n return hit("altcha", "altcha", url=p.url, challenge_url=urljoin(p.url, as_url))\n return browser("altcha", "altcha", p, "no challenge attribute")<\/pre>\n<\/div>\nStep 7: Capy, CaptchaFox and Friendly Captcha<\/h2>\n
def capy(p): # the widget script is ...\/puzzle\/get_js\/?k=PUZZLE_...\n m = re.search(r"((?:https?:)?\/\/[^\\s\\"']+?)\/puzzle\/get_js\/\\S*?(PUZZLE_[\\w-]+)", p.srcs)\n if m:\n host = m.group(1) if m.group(1).startswith("http") else "https:" + m.group(1)\n more = {} if host == "https:\/\/jp.api.capy.me" else {"api_server": host}\n return hit("capy", "capy", sitekey=m.group(2), url=p.url, **more)\n\nMAM = "mampkg\/@mamdev\/core.frontend.libs.captchafox"\n\ndef captchafox(p): # plain build from cdn.captchafox.com, or the bundled build from s.uicdn.com\n t, key = tag("captchafox", p.h), grab(r"captchafox[^\\"']*\/api\\.js\\?key=([^\\"'&]+)", p.srcs)\n if t or key:\n more = {"api_server": "https:\/\/s.uicdn.com\/" + MAM + "\/"} if MAM in p.srcs else {}\n sitekey = attr(t, "data-sitekey") or key\n if not sitekey:\n return browser("captchafox", "captchafox", p, "no sitekey in the static HTML")\n return hit("captchafox", "captchafox", sitekey=sitekey, url=p.url, **more)\n\ndef friendly(p): # v2 loads @friendlycaptcha\/sdk (site.min.js), v1 loads friendly-challenge\n t = tag("frc-captcha", p.h)\n if not t:\n return None\n v2_end, v1_end = attr(t, "data-api-endpoint"), attr(t, "data-puzzle-endpoint")\n server = v2_end or v1_end\n v2 = v2_end is not None or re.search(r"friendlycaptcha\/sdk|site(\\.compat)?\\.min\\.js", p.srcs)\n v1 = v1_end is not None or re.search(r"friendly-challenge|widget(\\.module)?\\.min\\.js", p.srcs)\n if bool(v2) == bool(v1):\n return browser("friendly_captcha", "friendly_captcha", p, "cannot tell v1 from v2 in the HTML")\n if not attr(t, "data-sitekey"):\n return browser("friendly_captcha", "friendly_captcha", p, "no sitekey in the static HTML")\n more = {"api_server": server} if server else {}\n return hit("friendly_captcha_" + ("v2" if v2 else "v1"), "friendly_captcha",\n sitekey=attr(t, "data-sitekey"), url=p.url, version="v2" if v2 else "v1", **more)<\/pre>\n<\/div>\n\n
Step 8: the image CAPTCHA, a guess<\/h2>\n
def image(p): # a guess: an <img> that says captcha, next to a text box that says captcha\n box = r"<input\\b(?![^>]*type\\s*=\\s*[\\"']?(?:hidden|checkbox|submit))[^>]*(?:captcha|security.?code)"\n for img in re.findall(r"<img\\b[^>]*>", p.h, re.I):\n if re.search(box, p.h, re.I) and re.search(r"captcha", img, re.I) and attr(img, "src"):\n return hit("image", "normal", image=urljoin(p.url, attr(img, "src")))<\/pre>\n<\/div>\nStep 9: the checks, detect and solve<\/h2>\n
CHECKS = [unsupported, cf_challenge, hcaptcha, recaptcha, turnstile, geetest, altcha, capy, captchafox, friendly]\n\ndef detect_all(html, page_url):\n p = parse(html, page_url)\n return [r for r in (check(p) for check in CHECKS) if r] or [r for r in [image(p)] if r]\n\ndef detect(html, page_url):\n found = detect_all(html, page_url)\n if len(found) > 1:\n found[0]["also"] = [r["type"] for r in found[1:]]\n return found[0] if found else None\n\ndef solve_hcaptcha(args, api, key=None): # no SDK call yet: post to in.php, poll res.php\n form = {"method": "hcaptcha", "sitekey": args["sitekey"], "pageurl": args["url"],\n "invisible": args.get("invisible", 0), "data": args.get("data"), "key": key, "json": 1}\n job = requests.post(api + "\/in.php", data=form, timeout=30).json()\n if job["status"] != 1:\n raise RuntimeError(job["request"])\n for _ in range(36): # a solve takes 10 to 30 seconds, so give up after 3 minutes\n time.sleep(5)\n q = {"key": key, "action": "get", "id": job["request"], "json": 1}\n r = requests.get(api + "\/res.php", params=q, timeout=30).json()\n if r["request"] != "CAPCHA_NOT_READY":\n if r["status"] != 1:\n raise RuntimeError(r["request"])\n return {"code": r["request"], "userAgent": r.get("useragent")}\n raise TimeoutError("hCaptcha was not solved within 3 minutes")\n\ndef solve(info, solver, session=None, api="http:\/\/127.0.0.1:8080", key=None):\n if info.get("unsupported") or info.get("needs_browser"):\n raise RuntimeError(info.get("needs_browser") or info["type"] + " is not supported by CapSkip")\n args = dict(info["args"])\n if info["method"] == "hcaptcha":\n return solve_hcaptcha(args, api, key)\n if info["method"] == "normal": # fetch the image with YOUR session so the cookie matches it\n src = args.pop("image")\n if not src.startswith("data:"):\n r = (session or requests).get(src, timeout=30)\n r.raise_for_status()\n src = "data:image\/png;base64," + base64.b64encode(r.content).decode()\n args["file"] = src\n return getattr(solver, info["method"])(**args)<\/pre>\n<\/div>\nRun it<\/h2>\n
import requests\nfrom capskip import CapSkip\nfrom detect import detect, solve\n\nURL = "https:\/\/example.com\/login" # a page of yours with a CAPTCHA\nHOST, PORT = "127.0.0.1", 8080 # from CapSkip's connection settings\nsession = requests.Session()\nhtml = session.get(URL, timeout=30).text\n\ninfo = detect(html, URL)\nprint(info)\n\nif info and info["method"] and not info.get("needs_browser"):\n solver = CapSkip(host=HOST, port=PORT)\n result = solve(info, solver, session, api=f"http:\/\/{HOST}:{PORT}")\n print(result)<\/pre>\n<\/div>\n