To solve CaptchaFox in Python, call solver.captchafox() from the capskip package with the sitekey and the page URL, put the token it returns in the cf-captcha-response form field, and send that request with the user agent that came back beside the token. The last step is where Python code usually goes wrong. requests and httpx both identify themselves in the User-Agent header by default, and a site that expects the token from the browser that minted it turns that request down, so a solve that worked perfectly can still fail on submit. CapSkip added CaptchaFox in version 1.4.0. This guide covers the key, the call, the submit, retries and running solves side by side.<\/p>\n
# Quoted, so cmd.exe does not read >= as a redirect\npip install "capskip>=1.3.0" requests httpx<\/pre>\n<\/div>\nStep 1: read the sitekey and the widget source<\/h2>\n
The sitekey is public, the same for every visitor, and conventionally starts with sk_. Most pages carry it on the widget’s container, a div with the class captchafox and a data-sitekey attribute. A page that builds the widget from its own script passes the key to a captchafox.render call instead, and when neither shows up in the HTML you fetched, the key is in the Network tab: it is the path segment after \/captcha\/ in the request to api.captchafox.com.<\/p>\n
While you are reading the page, check which script loads the widget. Most sites load it from cdn.captchafox.com and get a plain token. Some platforms embed a package from s.uicdn.com\/mampkg\/ instead, and those sites expect a token that starts with MAM_. Solving for the wrong one still returns a token, in a format the site then refuses, so this check saves a confusing afternoon. On MAM pages the key may sit in the script’s own src, after ?key=, and the same CDN serves unrelated packages too, so match the captchafox package path rather than the host.<\/p>\n
\nimport re\n\nimport requests\n\nPAGE_URL = "https:\/\/example.com\/signup"\nsession = requests.Session()\nhtml = session.get(PAGE_URL, timeout=30).text\n\n# The container: <div class="captchafox" data-sitekey="sk_...">\ntag = re.search(r'<[^>]*class="(?:[^"]*\\s)?captchafox(?:\\s[^"]*)?"[^>]*>', html)\nkey = tag and re.search(r'data-sitekey="([^"]+)"', tag.group(0))\n# MAM pages may carry the key in the script src instead.\nkey = key or re.search(r'captchafox[^"]*\/api\\.js\\?key=([^"&]+)', html)\nsitekey = key.group(1) if key else None\n\n# The MAM build expects a MAM_ token; everything else is the default.\nuses_mam = "mampkg\/@mamdev\/core.frontend.libs.captchafox" in html\nprint(sitekey, uses_mam)<\/pre>\n<\/div>\nThe class pattern is bounded by whitespace, so a wrapper element with a class such as captchafox-container does not match by accident. It expects double quotes around attribute values, which is how CaptchaFox’s own snippet writes them.<\/p>\n
Step 2: the captchafox() call<\/h2>\n
To solve CaptchaFox in Python you need one method, which takes the sitekey and the page URL plus optional keyword arguments. For the standard widget, those two are all it needs.<\/p>\n
\n# pip install "capskip>=1.3.0"\nfrom capskip import CapSkip\n\nsolver = CapSkip(host="127.0.0.1", port=8080)\n\nresult = solver.captchafox("YOUR_SITEKEY", "https:\/\/example.com\/signup")\n\nprint(result["token"]) # goes in cf-captcha-response\nprint(result.get("userAgent")) # send this as the User-Agent<\/pre>\n<\/div>\nThe result is a plain dict. token and code hold the same string, and token is named for the field it fills. userAgent is the identity of the browser that minted the token, which is CapSkip’s own browser and not anything you sent. The key is only present when the solve reported one, so read it with result.get() and not with square brackets, or the rare solve without it raises a KeyError on the line that should have submitted the form.<\/p>\n
The page URL has to be the page the widget really runs on. CaptchaFox registers every key against a list of allowed domains and checks the host before it issues anything, so a key sent with the wrong page is refused every time, never intermittently. A redirect, a shortened link or a search result will not do.<\/p>\n
Options the method accepts<\/h3>\n
For a page that loads the MAM package, pass the package path from its script tag as api_server. The SDK drops any keyword argument whose value is None before the request goes out, so you can pass the option on every call and let the Step 1 check decide it.<\/p>\n
\n# Copied from the script tag on MAM pages.\nMAM_PACKAGE = "https:\/\/s.uicdn.com\/mampkg\/@mamdev\/core.frontend.libs.captchafox\/"\n\nresult = solver.captchafox(\n sitekey,\n PAGE_URL,\n # None is dropped, so the standard widget sends nothing extra.\n api_server=MAM_PACKAGE if uses_mam else None,\n)<\/pre>\n<\/div>\nBesides api_server, captchafox() takes proxy, proxytype and useragent, plus a per-call timeout and polling_interval in seconds. The useragent option is accepted for compatibility with other services and deliberately not applied, because CapSkip solves in a real browser with that browser’s own consistent identity. Any other keyword, an empty sitekey or URL, a proxy dict without type and uri, or a proxy type other than HTTP, HTTPS, SOCKS5 or SOCKS5H raises a ValidationException before a request is sent.<\/p>\n
Step 3: submit under the user agent that minted the token<\/h2>\n
When you solve CaptchaFox in Python, this is the step that decides whether the site accepts the token. Out of the box, requests sends a User-Agent of python-requests followed by its version number, and httpx sends python-httpx followed by its own. Neither is the browser that produced the token. Copy the returned value onto the request that carries it.<\/p>\n
\n# session is the one Step 1 fetched the page with, so it carries its cookies.\nua = result.get("userAgent")\nresp = session.post(\n PAGE_URL, # or wherever the form's action attribute points\n data={"email": "YOUR_EMAIL", "cf-captcha-response": result["token"]},\n # Per request, not on session.headers: the next token may differ.\n headers={"User-Agent": ua} if ua else {},\n timeout=30,\n)\nprint(resp.status_code)<\/pre>\n<\/div>\nA header passed to post() is merged over the session’s defaults for that one request, so the session keeps its cookies and every later request goes out as before. Setting session.headers instead would stamp one solve’s user agent on every request that follows, including the next token’s submit. With httpx, fetch the page and submit through one httpx.Client so the cookies carry over, and pass data, headers and timeout to its post() in the same way.<\/p>\n
Two more rules come from how CaptchaFox checks the token on the site’s side. Each token can be verified once, and only within a short time<\/a>, so solve when you are ready to submit and submit straight away. And treat the token as opaque: do not strip, re-encode or reformat it. Some sites send it in a JSON body rather than a form post, so submit the form once by hand with DevTools open and mirror exactly what the page sends.<\/p>\n
Step 4: retries, challenge types and timeouts<\/h2>\n
You do not choose which challenge CaptchaFox draws. Most solves draw nothing at all, because the browser evidence clears on its own, and when a slide puzzle appears, CapSkip usually completes it. Image-select and audio challenges are rare and are not solved: they come back as an ApiException whose message contains ERROR_CAPTCHA_UNSOLVABLE, within seconds rather than at the end of the timeout. A fresh attempt usually draws something else, so you have two ways to retry.<\/p>\n
\n
- In CapSkip.<\/strong> The CaptchaFox section of the settings has Retries (0-3), at 0 by default. Raised, it redraws unsupported challenges, attempts that run out of time and browser errors on its own, and it never retries a key the site refuses. Each extra retry can add up to one Row Timeout, 150 seconds by default, to a single call, so pass a longer timeout to captchafox() when you raise it.<\/li>\n
- In your code.<\/strong> Catch the exception and call again, as below. The one catch is that a refused key also reads as unsolvable through the API, so a key used on the wrong domain gets retried too. It fails within seconds on every attempt and never once succeeds, which is the tell.<\/li>\n<\/ul>\n
\nfrom capskip.exceptions import ApiException\n\n\ndef solve_captchafox(sitekey, url, attempts=3, **options):\n for attempt in range(1, attempts + 1):\n try:\n return solver.captchafox(sitekey, url, **options)\n except ApiException as exc:\n # Select, audio and unreadable slide draws come back\n # unsolvable; redraw. Anything else, such as a wrong\n # API key, is final.\n if "UNSOLVABLE" not in str(exc) or attempt == attempts:\n raise<\/pre>\n<\/div>\ncaptchafox() polls on the client’s recaptchaTimeout, 300 seconds by default, because it is a real browser session. CapSkip runs its own clock as well. A task can wait up to 250 seconds (Wait Timeout) for one of the 10 CaptchaFox threads (Max. Threads), and a single attempt gets 150 seconds (Row Timeout). With Retries at 0 and a thread free, a failed attempt reaches you as an ApiException from CapSkip well before the SDK’s 300 seconds are up; if the task queues for a long time, the SDK can reach its limit first and raise a TimeoutException instead.<\/p>\n
Solving several tokens at once<\/h2>\n
AsyncCapSkip is a genuine asyncio client in Python, not an alias, so asyncio.gather runs several solves side by side. Pair it with httpx’s async client, and keep every token together with its own user agent until it is submitted.<\/p>\n
\nimport asyncio\n\nimport httpx\nfrom capskip import AsyncCapSkip\n\nsolver = AsyncCapSkip(host="127.0.0.1", port=8080)\n\n\nasync def solve_and_submit(client, sitekey, url, form):\n await client.get(url) # the form's cookies land in client\n result = await solver.captchafox(sitekey, url)\n ua = result.get("userAgent")\n return await client.post(\n url,\n data={**form, "cf-captcha-response": result["token"]},\n headers={"User-Agent": ua} if ua else {},\n )\n\n\nasync def main(jobs):\n async with httpx.AsyncClient(timeout=30) as client:\n return await asyncio.gather(\n *(solve_and_submit(client, *job) for job in jobs),\n return_exceptions=True,\n )<\/pre>\n<\/div>\nTwo limits apply. CapSkip runs 10 CaptchaFox solves at a time by default, and the rest wait for a free thread for up to the 250 second Wait Timeout, so a gather over fifty jobs is fine at normal solve times; for bigger batches, raise Max. Threads or gather in smaller groups. And CaptchaFox scores the network as well as the browser, so many solves from one address raise the challenge rate. Configure proxies in CapSkip’s CaptchaFox section, or pass a proxy dict with a type and a uri on each call, and send the submit through the same exit. More on asyncio patterns is in the guide to solving CAPTCHAs in parallel in Python<\/a>.<\/p>\n
Running the solver on another machine<\/h2>\n
127.0.0.1 is right while the script and CapSkip share a Windows PC. When the Python code moves to a VPS, a container, a CI runner or a hosted notebook, loopback points at the wrong machine and the first solve raises a NetworkException. Switch CapSkip to Server mode and it listens on your network address or public IP, so any of those can call it over the same API. Use a static public IP when the route crosses the internet, turn on API key validation, and limit the port to the addresses you expect with a Windows Firewall rule. The solver is still your own Windows machine, and solves are still unmetered.<\/p>\n
The SDK does not read environment variables by itself. Read CAPSKIP_HOST, CAPSKIP_PORT and CAPSKIP_API_KEY in your code and pass them to the constructor, as the full example does, so the same script runs at your desk and on a server.<\/p>\n
Full working example<\/h2>\n
\n# pip install "capskip>=1.3.0" requests\nimport os\nimport re\n\nimport requests\nfrom capskip import CapSkip\nfrom capskip.exceptions import (ApiException, CapSkipError,\n TimeoutException, ValidationException)\n\nPAGE_URL = "https:\/\/example.com\/signup"\n# Copied from the script tag on MAM pages.\nMAM_PACKAGE = "https:\/\/s.uicdn.com\/mampkg\/@mamdev\/core.frontend.libs.captchafox\/"\n\nsolver = CapSkip(\n apiKey=os.getenv("CAPSKIP_API_KEY", "capskip"),\n host=os.getenv("CAPSKIP_HOST", "127.0.0.1"),\n port=int(os.getenv("CAPSKIP_PORT", "8080")),\n)\nsession = requests.Session()\n\nhtml = session.get(PAGE_URL, timeout=30).text\ntag = re.search(r'<[^>]*class="(?:[^"]*\\s)?captchafox(?:\\s[^"]*)?"[^>]*>', html)\nkey = tag and re.search(r'data-sitekey="([^"]+)"', tag.group(0))\nkey = key or re.search(r'captchafox[^"]*\/api\\.js\\?key=([^"&]+)', html)\nif not key:\n raise SystemExit("No sitekey in the HTML; find it in DevTools.")\napi_server = MAM_PACKAGE if "mampkg\/@mamdev\/core.frontend.libs.captchafox" in html else None\n\ntry:\n for attempt in range(1, 4):\n try:\n result = solver.captchafox(key.group(1), PAGE_URL,\n api_server=api_server)\n break\n except ApiException as exc:\n # Select, audio and unreadable slide draws come back unsolvable.\n if "UNSOLVABLE" not in str(exc) or attempt == 3:\n raise\n print(f"attempt {attempt}: {exc}")\nexcept ValidationException as exc:\n raise SystemExit(f"not sent: {exc}")\nexcept TimeoutException:\n raise SystemExit("gave up waiting; recaptchaTimeout is 300 seconds")\nexcept CapSkipError as exc:\n # A third unsolvable draw, a refused key, or CapSkip unreachable.\n raise SystemExit(f"solve failed: {exc!r}")\n\nua = result.get("userAgent")\nresp = session.post(\n PAGE_URL, # or wherever the form's action attribute points\n data={"email": "YOUR_EMAIL", "cf-captcha-response": result["token"]},\n headers={"User-Agent": ua} if ua else {},\n timeout=30,\n)\nprint(resp.status_code, "UA sent:", bool(ua))<\/pre>\n<\/div>\nIf the solve fails instantly on every run, check the page URL before anything else, because a key used outside its registered domains fails the same way each time. When the regex finds nothing, the page builds the widget from script, and the key is in the render call or the Network tab as described in Step 1. The raw endpoint behind this method is documented in the CaptchaFox API reference<\/a>.<\/p>\n
Common errors and what they mean<\/h2>\n
\n\n
\n \nWhat you see<\/th>\n Cause<\/th>\n Fix<\/th>\n<\/tr>\n<\/thead>\n \n The site rejects a token CapSkip returned as solved<\/td>\n The submit went out as python-requests or python-httpx, not as the browser that minted the token<\/td>\n Send result.get("userAgent") as the User-Agent header on that request<\/td>\n<\/tr>\n \n Rejected although the user agent matches<\/td>\n The page loads the MAM package and the solve used the default widget, or the reverse<\/td>\n Read the script tag and set api_server to match it<\/td>\n<\/tr>\n \n A KeyError on userAgent<\/td>\n The solve reported no user agent, and the key is only present when it did<\/td>\n Read it with result.get() and send the header only when there is a value<\/td>\n<\/tr>\n \n An ApiException straight away, every time, for one key<\/td>\n The page URL is outside the domains the key is registered for, or the key itself is wrong<\/td>\n Send the page the widget runs on, not a redirect or a search result, and recheck the key<\/td>\n<\/tr>\n \n An occasional ApiException containing ERROR_CAPTCHA_UNSOLVABLE<\/td>\n CaptchaFox drew an image-select or audio challenge, or a slide variant CapSkip could not read<\/td>\n Retry in code, or raise Retries in CapSkip’s CaptchaFox settings<\/td>\n<\/tr>\n \n A token that worked once fails the second time<\/td>\n Each token verifies once and expires quickly<\/td>\n Solve a fresh token for every submit, and submit straight away<\/td>\n<\/tr>\n \n More challenges, then refusals, as a run goes on<\/td>\n Every solve comes from one address, and CaptchaFox scores the network<\/td>\n Spread solves across a proxy pool, and submit through the same exit<\/td>\n<\/tr>\n \n ValidationException before anything is sent<\/td>\n An empty sitekey or URL, a keyword argument the method does not take, or a proxy type CapSkip does not accept<\/td>\n Check the sitekey was found, and fix or drop the argument the message names<\/td>\n<\/tr>\n \n NetworkException on the first call<\/td>\n CapSkip is not running, or the host and port are wrong<\/td>\n Start CapSkip, then check whether it should be in Local mode or Server mode<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n FAQ<\/h2>\n
\n\n
Is result["code"] different from result["token"]?<\/h3>\n<\/summary>\n
No, for CaptchaFox they are the same string. code is the field every CapSkip method fills, which keeps older code working unchanged, and token is the name that matches what the form expects. Use token in new code so it reads like the field it fills.<\/p>\n<\/details>\n
\n\n
Can I use the token in a Playwright or Selenium session?<\/h3>\n<\/summary>\n
Yes, as long as the submit goes out under the user agent CapSkip returned. Playwright fixes the user agent when a context is created, so solve first, open the context with browser.new_context(user_agent=ua), load the form, write the token into the cf-captcha-response field and submit. In Selenium with Chrome, add the user-agent switch with that value to the Chrome options before the driver starts, or switch a running session with driver.execute_cdp_cmd("Network.setUserAgentOverride", {"userAgent": ua}). If your automation does not need a browser for anything else, the requests route above is simpler.<\/p>\n<\/details>\n
\n\n
Can a Python script on a hosted platform reach the solver?<\/h3>\n<\/summary>\n
Yes. Put CapSkip in Server mode under connection settings so it listens on a network address instead of loopback, read that address from CAPSKIP_HOST in your script, and pass it to CapSkip(). A VPS, a container host, a CI runner and a hosted notebook all connect over the same HTTP API. Use a static public IP and a firewall rule when the route crosses the internet. The solver stays on hardware you own, so nothing changes about how solves are counted.<\/p>\n<\/details>\n
\n\n
How is this different from the C# version?<\/h3>\n<\/summary>\n
The call and the rules are the same; the traps are different. In C#, HttpClient sends no User-Agent at all unless you add one. In Python, both common clients send their own name instead, python-requests or python-httpx, which a site can refuse just as easily. The .NET side is covered in the C# CaptchaFox guide<\/a>.<\/p>\n<\/details>\n
The short version<\/h2>\n
To solve CaptchaFox in Python, read the sitekey from the captchafox container, the render call or the Network tab, and note whether the page loads the MAM package. Call solver.captchafox() with the sitekey and the real page URL, adding api_server only for MAM pages. Post result["token"] in cf-captcha-response with result.get("userAgent") as the User-Agent header, once and straight away. Retry unsolvable draws, add proxies as volume grows, and switch to Server mode when the script leaves the solver’s machine.<\/p>\n