DEV Community: Bassem Shahin

reCAPTCHA v2 in Puppeteer: solve the checkbox with an API (no plugin) and submit the token

Bassem Shahin — Thu, 29 Oct 2026 13:00:00 +0000

Your Puppeteer script fills in the form, clicks "I'm not a robot", and stops there. Each time I tried that in headless Chrome tonight, the click didn't tick the box. It opened the image grid, and the script was now expected to find fire hydrants.

It doesn't have to. The site never checks the checkbox. It checks a token. When a person solves the widget, reCAPTCHA writes a token into a hidden g-recaptcha-response field, and the site's backend verifies that token with Google. A solving API returns the same kind of token from two inputs: the sitekey and the page URL. So in Puppeteer the job is to find the sitekey, get a token, put it where the form reads it, and submit.

This post does that on Google's own checkbox demo with Node 22.18 and Puppeteer 25.14.0, which downloads its own headless Chrome 155. (Puppeteer 25 needs Node 22.12 or newer.) No puppeteer-extra, no plugin, just puppeteer. Every output below comes from runs on 2026-10-18. The Python and Selenium version covers the API side in more detail, so this one sticks to the Puppeteer parts.

What the click does in headless Chrome

The checkbox sits inside an iframe. In Puppeteer you get that iframe as a Frame with contentFrame(), then click inside it:

// click-checkbox.mjs: what a plain click on "I'm not a robot" does in headless Puppeteer.
// Needs: Node 22.12+ (for Puppeteer 25) and npm i puppeteer
import puppeteer from "puppeteer";

const browser = await puppeteer.launch({ headless: true });
try {
  const page = await browser.newPage();
  await page.goto("https://www.google.com/recaptcha/api2/demo", { waitUntil: "networkidle2" });
  console.log("navigator.webdriver:", await page.evaluate(() => navigator.webdriver));

  // The checkbox is inside the anchor iframe: get that frame with contentFrame(), then click in it.
  const anchorHandle = await page.waitForSelector('iframe[title="reCAPTCHA"]');
  const anchor = await anchorHandle.contentFrame();
  await anchor.click("#recaptcha-anchor");
  await new Promise((resolve) => setTimeout(resolve, 5_000));

  const checked = await anchor.$eval("#recaptcha-anchor", (el) => el.getAttribute("aria-checked"));
  console.log("aria-checked:", checked);
  const bframeHandle = await page.$('iframe[src*="/bframe"]'); // the challenge popup
  console.log("challenge iframe:", await bframeHandle.evaluate((f) => {
    const box = f.getBoundingClientRect();
    return `${box.width}x${box.height}, ${getComputedStyle(f).visibility}`;
  }));
  const bframe = await bframeHandle.contentFrame();
  const task = await bframe.$eval(".rc-imageselect-desc-wrapper", (el) => el.innerText)
    .catch(() => "(no image grid)");
  console.log("challenge says:", task.replace(/\s+/g, " "));
  const token = await page.$eval("#g-recaptcha-response", (t) => t.value);
  console.log("g-recaptcha-response:", token.length, "chars");
} finally {
  await browser.close();
}

$ node click-checkbox.mjs
navigator.webdriver: true
aria-checked: false
challenge iframe: 400x580, visible
challenge says: Select all images with a fire hydrant Click verify once there are none left.
g-recaptcha-response: 0 chars

The box stayed unchecked, the 400x580 challenge iframe opened, and the response field is still empty. Six runs tonight, six image challenges: fire hydrants three times, plus motorcycles, stairs and crosswalks. You could start clicking tiles, but then you're writing an image classifier to fill in one form field. Skip the widget and fill the field.

Step 1: find the widget with page.frames()

Every rendered widget gets an anchor iframe. Its URL carries the sitekey as k= and the widget type as size=. page.frames() lists every frame on the page, cross-origin ones included, so this works even when the page builds the widget from JavaScript and the HTML has no data-sitekey. The script below waits for the first anchor with page.waitForFrame(), logs every anchor it finds, and takes the first one whose size isn't invisible.

Logging all of them paid off on Google's other demo, on recaptcha-demo.appspot.com, which loads two:

00:29:27Z anchor k=6LfW6wATAAAAAHLqO2pb8bDBahxlMxNdo9g947u9 size=normal /recaptcha/api2/anchor
00:29:27Z anchor k=6Le80pApAAAAANg24CMbhL_U2PASCW_JUnq5jPys size=invisible /recaptcha/enterprise/anchor

The second one is an Enterprise score key that the form doesn't use. Code that grabs the first iframe[src*="recaptcha"] works until the page loads them in the other order. Invisible v2 and v3 both report size=invisible and need different parameters, so the script stops when that's all it finds. For invisible v2, the invisible reCAPTCHA v2 walkthrough sends invisible=1. reCAPTCHA v3 takes version=v3 and the page's action instead, as the v3 solver post shows.

The script also reads data-sitekey from .g-recaptcha and logs whether it matches k=. On both demos it did. If they ever differ, trust the anchor, because it's what reCAPTCHA actually rendered.

One more frames detail. anchor.parentFrame() is the document that shows the widget. On both demos that's the page itself. If a site puts its form in an iframe, it's that iframe, and the reCAPTCHA v2 guide says to send the iframe's URL as pageurl. The script uses that frame for pageurl, for the token and for the submit, so it follows the widget. I only ran it on top-level widgets, though.

Step 2: get a token with fetch

Node 18 and later have fetch built in, so the API side needs no packages. It's a standard reCAPTCHA v2 task on the 2Captcha-style in.php/res.php API: method=userrecaptcha, the sitekey as googlekey, the pageurl, and json=1. Wait 15 seconds, then poll every 5. A task that isn't done after 180 seconds, or that comes back ERROR_CAPTCHA_UNSOLVABLE, gets one new task.

// solve-recaptcha.mjs: get a reCAPTCHA v2 checkbox token from an in.php/res.php API.
// Node 18+ (built-in fetch), no packages. Set CAPTCHAAI_KEY in the environment.
const API = "https://ocr.captchaai.com";
const KEY = (process.env.CAPTCHAAI_KEY ?? "").trim();
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
export const log = (...args) => console.log(new Date().toISOString().slice(11, 19) + "Z", ...args);

async function call(path, params) {
  const r = await fetch(`${API}/${path}`, {
    method: "POST",
    body: new URLSearchParams({ ...params, key: KEY, json: "1" }),
  });
  return r.json(); // { status, request } because of json=1
}

// One task: submit, wait 15 s, then poll every 5 s. Returns the token, or null if the task failed.
async function oneTask(sitekey, pageurl, timeout) {
  const sub = await call("in.php", { method: "userrecaptcha", googlekey: sitekey, pageurl });
  if (sub.status !== 1) throw new Error(`in.php: ${sub.request}`); // wrong key, no free thread, bad sitekey
  const id = String(sub.request); // the id arrives as a number
  const started = Date.now();
  log(`task ${id} submitted`);
  await sleep(15_000);
  while (Date.now() - started < timeout) {
    const res = await call("res.php", { action: "get", id });
    const secs = ((Date.now() - started) / 1000).toFixed(1);
    if (res.status === 1) {
      log(`task ${id} solved in ${secs}s`);
      return res.request;
    }
    if (res.request === "ERROR_CAPTCHA_UNSOLVABLE") {
      log(`task ${id}: ERROR_CAPTCHA_UNSOLVABLE after ${secs}s`);
      return null;
    }
    if (res.request !== "CAPCHA_NOT_READY") throw new Error(`res.php: ${res.request}`); // sic, no T
    await sleep(5_000);
  }
  log(`task ${id} not solved in ${timeout / 1000}s`);
  return null;
}

// A token task can be slow or fail, so a failed task gets one new task before we give up.
export async function solveRecaptchaV2(sitekey, pageurl, { timeout = 180_000, tasks = 2 } = {}) {
  if (!KEY) throw new Error("Set CAPTCHAAI_KEY to your API key first");
  for (let i = 0; i < tasks; i++) {
    const token = await oneTask(sitekey, pageurl, timeout);
    if (token) return token;
  }
  throw new Error(`no token from ${tasks} tasks`);
}

Two details from the live API: the task id arrives as a JSON number ({"status":1,"request":5608577418} in a raw reply tonight), and CAPCHA_NOT_READY really has no T. Apart from that and ERROR_CAPTCHA_UNSOLVABLE, any error stops the script, because retrying a wrong key or a bad sitekey won't fix it. The post on the submit-and-poll loop lists every reply I got from the live API and which ones deserve a retry.

Step 3: page.type() can't fill the token field

The token goes in the g-recaptcha-response textarea. reCAPTCHA adds it to the widget's document, not to the iframe, and hides it with display: none. Selenium's send_keys throws on it. Puppeteer's page.type() is quieter. It doesn't throw, and it doesn't type either:

$ node probe-type.mjs
textarea display: none
page.type(SEL, "abc")          -> value ""
page.evaluate(el.value = "abc") -> value "abc"

Set .value from inside the page with evaluate() instead. The script fills every textarea named g-recaptcha-response. That's right for a page with one widget. With two widgets in two forms, fill only the one in your form.

Google's demo also declares data-callback="onSuccess". The script doesn't call it, and the demo's backend didn't need it. On a real site, if the submit button stays disabled after the injection, the callback is often what enables it. The callback post shows how to find it and call it.

Step 4: submit and wait for the navigation

click() resolves once the click has happened, not once the next page has loaded. If you await the click and only then call waitForNavigation(), a fast response can land in between, and the wait times out. The script starts both together with Promise.all. If the form posts with fetch and the page never reloads, wait for the site's own success element instead.

The whole script

// recaptcha-v2-puppeteer.mjs: solve a reCAPTCHA v2 checkbox in Puppeteer with a solving API, no plugin.
// Needs: Node 22.12+ (for Puppeteer 25) and npm i puppeteer; solve-recaptcha.mjs sits next to it
//   CAPTCHAAI_KEY=... node recaptcha-v2-puppeteer.mjs [page url] [token to test with]
import puppeteer from "puppeteer";
import { log, solveRecaptchaV2 } from "./solve-recaptcha.mjs";

const url = process.argv[2] ?? "https://www.google.com/recaptcha/api2/demo";
const testToken = process.argv[3]; // skip the API and submit this instead
const ANCHOR = /\/recaptcha\/(api2|enterprise)\/anchor\?/; // one anchor frame per rendered widget

const browser = await puppeteer.launch({ headless: true });
try {
  const page = await browser.newPage();
  await page.goto(url, { waitUntil: "networkidle2" });

  // 1. Find the widget. Its anchor frame URL carries the sitekey (k=) and the widget size.
  await page.waitForFrame((f) => ANCHOR.test(f.url()), { timeout: 20_000 });
  const anchors = page.frames().filter((f) => ANCHOR.test(f.url()));
  for (const f of anchors) {
    const u = new URL(f.url());
    log(`anchor k=${u.searchParams.get("k")} size=${u.searchParams.get("size")} ${u.pathname}`);
  }
  const anchor = anchors.find((f) => new URL(f.url()).searchParams.get("size") !== "invisible");
  if (!anchor) throw new Error("no checkbox widget: size=invisible means invisible v2 or v3");
  const sitekey = new URL(anchor.url()).searchParams.get("k");
  const host = anchor.parentFrame(); // the document that shows the widget
  const declared = await host.$eval(".g-recaptcha", (el) => el.dataset.sitekey).catch(() => null);
  log(`sitekey ${sitekey} (data-sitekey: ${declared === sitekey ? "same" : declared ?? "none"})`);

  // 2. Get a token. pageurl is the URL of the document that shows the widget.
  const token = testToken ?? (await solveRecaptchaV2(sitekey, host.url()));
  log(`token ${token.slice(0, 20)}... (${token.length} chars)`);

  // 3. Put it in the hidden textarea, in the widget's document, not in the iframe.
  await host.evaluate((t) => {
    for (const el of document.querySelectorAll('textarea[name="g-recaptcha-response"]')) el.value = t;
  }, token);

  // 4. Submit. Start waiting for the navigation before the click that causes it.
  await Promise.all([
    host.waitForNavigation({ waitUntil: "domcontentloaded" }),
    host.click("form [type=submit]"),
  ]);
  // Google's demo answers with one of two lines; the appspot demo prints its siteverify result.
  // On your own site, wait for its own success signal instead.
  const lines = (await host.$eval("body", (b) => b.innerText)).split("\n").map((s) => s.trim());
  const said = lines.filter((s) => /Hooray|verify that you are not a robot|'(success|hostname)'/.test(s));
  log("page says:", said.join(" | ") || "(none of the lines I look for)");
} catch (err) {
  log("FAILED:", err.message);
  process.exitCode = 1;
} finally {
  await browser.close();
}

With the key set and no arguments, it solves Google's demo and submits:

$ CAPTCHAAI_KEY=... node recaptcha-v2-puppeteer.mjs
00:34:06Z anchor k=6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ- size=normal /recaptcha/api2/anchor
00:34:06Z sitekey 6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ- (data-sitekey: same)
00:34:06Z task 5608583421 submitted
00:35:03Z task 5608583421 solved in 57.3s
00:35:03Z token 0cAFcWeA4jcxIytEZCQ_... (2532 chars)
00:35:04Z page says: Verification Success... Hooray!

Verification Success... Hooray! is the demo's answer once its backend has verified the token with Google. That was my fastest run on this demo. The next section has all of them.

The second argument is a token to submit instead of solving, so you can test the page side for free. A fake one gets the demo's rejection:

$ node recaptcha-v2-puppeteer.mjs https://www.google.com/recaptcha/api2/demo 03AFcWeA-not-a-real-token
00:32:57Z anchor k=6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ- size=normal /recaptcha/api2/anchor
00:32:57Z sitekey 6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ- (data-sitekey: same)
00:32:57Z token 03AFcWeA-not-a-real-... (25 chars)
00:32:57Z page says: Please verify that you are not a robot.

The appspot demo prints the siteverify result its backend got from Google. Same script, different URL:

$ CAPTCHAAI_KEY=... node recaptcha-v2-puppeteer.mjs https://recaptcha-demo.appspot.com/recaptcha-v2-checkbox.php
00:35:28Z anchor k=6LfW6wATAAAAAHLqO2pb8bDBahxlMxNdo9g947u9 size=normal /recaptcha/enterprise/anchor
00:35:28Z anchor k=6Le80pApAAAAANg24CMbhL_U2PASCW_JUnq5jPys size=invisible /recaptcha/enterprise/anchor
00:35:28Z sitekey 6LfW6wATAAAAAHLqO2pb8bDBahxlMxNdo9g947u9 (data-sitekey: same)
00:35:28Z task 5608596705 submitted
00:36:04Z task 5608596705 solved in 36.3s
00:36:04Z token 0cAFcWeA5kTm3wIaWkKQ... (2574 chars)
00:36:05Z page says: 'success' => true, | 'hostname' => 'recaptcha-demo.appspot.com',

Look at the first anchor. Six minutes earlier the same key came from /recaptcha/api2/anchor (the Step 1 output). This time it came from /recaptcha/enterprise/anchor. Both times I sent it as a plain v2 task, and both times siteverify said success. So /enterprise/ in the path doesn't prove the key is Enterprise.

How long the solves took

Here is every task from tonight's runs on the two demos, in order: 120.8 s (a first test of this flow), 104.6 s, one still unsolved at 180 s, 130.9 s for its replacement, then 78.4, 83.5, 99.4, 99.7 (a check of the raw replies), 57.3 and 36.3 s. Nine tokens and one timeout. This is the run with the timeout:

00:24:07Z task 5608489555 submitted
00:27:10Z task 5608489555 not solved in 180s
00:27:10Z task 5608518717 submitted
00:29:21Z task 5608518717 solved in 130.9s

The page sat there for more than five minutes, and the demo still accepted the token, because the token itself was fresh. The runs for the Selenium post on 2026-10-10 took 45, 90, 91 and 114 seconds, and one of five timed out. So plan for up to two minutes, sometimes more, and keep the 180-second cap with one retry.

A token is valid for two minutes and can be verified once. Ask for it when the form is ready, submit straight away, and never reuse one.

What can still go wrong

waitForNavigation times out after the injection. The form submits with fetch, so there's no navigation to wait for. Wait for the site's success element, or for its response with page.waitForResponse().
The site says "please verify" even with a real token. Usually the token expired or was used already. Next, check that it went into the textarea of the form you submitted.
The widget really is Enterprise. The anchor path only hints at it, as the appspot runs showed. A real Enterprise key takes enterprise=1, and the reply includes a User-Agent you have to submit with. This comparison of v2, v3 and Enterprise shows how to tell.
The token is accepted and the site still blocks you. reCAPTCHA is often one check among several. A valid token doesn't change navigator.webdriver (true in the click runs above) or your IP's reputation. The demos didn't care about either. Your target might.

FAQ

Do I need puppeteer-extra-plugin-recaptcha?
No. According to its README, page.solveRecaptchas() finds the widgets on the page, passes their configuration to a solving provider you configure, and puts the solutions back into the page, triggering any callback the widget needs. Apart from that callback, which this script leaves to you (Step 3), those are the steps above. Done by hand they come to about 100 lines on top of plain puppeteer, comments included, and when one fails, the log tells you which.

Can I make Puppeteer tick the checkbox itself?
Not reliably in headless Chrome. In my six runs the click opened the image challenge every time.

How long can I keep a token?
Two minutes from when it was issued, and one verification. Solve right before you submit.

Disclosure: I run CaptchaAI, the API these examples call. This article was written by an AI agent, and every output above is from a real run on 2026-10-18.

— Bassem

Cloudflare Turnstile in Puppeteer: solve "Verify you are human" with an API (Node.js)

Bassem Shahin — Mon, 26 Oct 2026 13:00:00 +0000

Your Puppeteer script reaches a login form with Cloudflare's Turnstile box under the password field, and stops. The box spins, says "Verification failed", spins again. The hidden field it should fill stays empty, the form posts without a token, and the server answers 403.

The box isn't what the server checks. When Turnstile passes, it writes a token into a hidden cf-turnstile-response input, and the site's backend asks Cloudflare whether that token is good. A solving API returns the same kind of token from the sitekey and the page URL. So: read the sitekey, get a token, put it where the form reads it, submit.

I ran it all against ScrapingCourse's Turnstile login, a practice page for scraping exercises with its own demo login (admin@example.com / password). It uses a real sitekey, not a Cloudflare test key, and its server checks the token. Node 22.18.0, puppeteer-core 25.14.0, Chrome 155. Every output below is from runs on 2026-10-18, including one that failed even though its token was fine.

Widget or challenge page?

"Verify you are human" shows up in two places, and they need different fixes. The practice site has both:

$ grab() { curl -s -A "$UA" -D - "$1" | tr -d '\r' | grep -oiE '^HTTP/.*|^cf-mitigated:.*|<title>[^<]*</title>'; }
$ grab https://www.scrapingcourse.com/login/cf-turnstile
HTTP/1.1 200 OK
<title>Cloudflare Login Challenge to Learn Web Scraping  - ScrapingCourse.com</title>
$ grab https://www.scrapingcourse.com/cloudflare-challenge
HTTP/1.1 403 Forbidden
Cf-Mitigated: challenge
<title>Just a moment...</title>

The first has a Turnstile widget in its form. The second is Cloudflare's challenge page: a 403 titled "Just a moment..." that showed "Performing security verification" and a "Verify you are human" checkbox in headless Chrome. No form takes a token there. It ends in a cf_clearance cookie, covered in this post on managed vs interactive challenges and this one on the cookie.

What the widget does in headless Puppeteer

First, no solver. I opened the page and read the hidden field every 5 seconds (trimmed):

00:25:03Z browser: Chrome/155.0.8059.79 | UA: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/155.0.0.0 Safari/537.36
00:25:03Z navigator.webdriver: true
00:25:03Z widget: {"sitekey":"0x4AAAAAAAW9zqSPAlyOSMfO","callback":"javascriptCallback"}
00:25:03Z typeof window.javascriptCallback: undefined
00:25:34Z t=30s {"box":"195x71","iframesInDocument":0,"openShadowRoot":false,"field":"0 chars","cloudflareFrames":1,"widgetText":""}

Screenshots show "Verification failed" at 5 and 10 seconds, "Verifying..." at 15 (a retry), then "Verification failed" to the end. No checkbox, ever. A headed window from the same script did exactly the same.

Three details matter for the script:

iframesInDocument: 0: the widget's iframe sits in a closed shadow root. You won't need it.
The hidden input exists from the start (0 chars, not missing). Turnstile adds it to the form.
data-callback="javascriptCallback" names a function this page never defines.

Step 1: read the widget's settings

A widget rendered from HTML is a div.cf-turnstile with its settings in data-* attributes:

Attribute	On this page	What to do with it
`data-sitekey`	`0x4AAAAAAAW9zqSPAlyOSMfO`	send it as `sitekey`
`data-action`	not set	if set, send it as `action`
`data-cdata`	not set	the API reference has no field for it
`data-callback`	`javascriptCallback`	call it after filling the field, if it exists

A sitekey starting with 1x, 2x or 3x is one of Cloudflare's test keys. Those only produce the dummy token XXXX.DUMMY.TOKEN.XXXX, which production secret keys reject, so there's nothing to solve.

Step 2: get a token from the API

A Turnstile task on the 2Captcha-style in.php / res.php API takes method=turnstile, the sitekey, the full pageurl and json=1 (Turnstile guide). The API reference adds action, for widgets that set one. Poll res.php every 5 seconds, starting at 10. No dependencies:

// turnstile.mjs: get a Cloudflare Turnstile token from a 2Captcha-style in.php / res.php API.
// Node 18+ (built-in fetch), no dependencies. Set CAPTCHAAI_KEY in the environment.
const API = "https://ocr.captchaai.com";
const KEY = (process.env.CAPTCHAAI_KEY ?? "").trim();
const RETRY = new Set(["ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR", "NETWORK_ERROR"]);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// One request. Resolves to { ok, text } for JSON replies, plain-text replies and network errors alike.
async function call(path, params) {
  try {
    const r = await fetch(`${API}/${path}`, {
      method: "POST",
      body: new URLSearchParams({ ...params, key: KEY, json: "1" }),
      signal: AbortSignal.timeout(30_000),
    });
    const body = await r.text();
    try {
      const reply = JSON.parse(body);
      return { ok: reply.status === 1, text: String(reply.request) }; // the task id is a number
    } catch {
      return { ok: false, text: body.trim() || "EMPTY_REPLY" };
    }
  } catch {
    return { ok: false, text: "NETWORK_ERROR" };
  }
}

async function submit(task) {
  for (let attempt = 0; ; attempt++) {
    const r = await call("in.php", task);
    if (r.ok) return r.text;
    // ERROR_BAD_PARAMETERS, ERROR_WRONG_SITEKEY, a bad key...: the request is wrong, retrying won't help
    if (!RETRY.has(r.text) || attempt === 2) throw new Error(`in.php: ${r.text}`);
    await sleep(5000 * 2 ** attempt);
  }
}

export async function solveTurnstile({ sitekey, pageurl, action, log = () => {}, timeout = 120 }) {
  if (!KEY) throw new Error("Set CAPTCHAAI_KEY to your API key first");
  if (!sitekey || !pageurl) throw new Error("sitekey and pageurl are both required");
  const task = { method: "turnstile", sitekey, pageurl, ...(action ? { action } : {}) };
  for (let tries = 1; tries <= 2; tries++) {
    const started = Date.now();
    const id = await submit(task);
    log(`task ${id} submitted`);
    await sleep(10_000); // nothing is ready before ~10 s
    let last = "";
    while (Date.now() - started < timeout * 1000) {
      const r = await call("res.php", { action: "get", id });
      const secs = ((Date.now() - started) / 1000).toFixed(1);
      if (r.ok) {
        log(`task ${id} solved in ${secs}s`);
        return r.text;
      }
      last = `${r.text} after ${secs}s`;
      if (r.text === "ERROR_CAPTCHA_UNSOLVABLE") break; // this task failed, a new one may not
      if (r.text !== "CAPCHA_NOT_READY" && !RETRY.has(r.text)) throw new Error(`res.php: ${r.text}`);
      await sleep(5000);
    }
    log(`task ${id}: ${last}`);
  }
  throw new Error("no token from 2 tasks");
}

Step 3: fill the field and submit in one step

Cloudflare's rendering docs say it plainly: "An invisible input with the name cf-turnstile-response is added and will be sent to the server with the other fields." The token goes there.

My first version filled the field, typed the email and password, and clicked Submit. It passed nine of ten runs. The one that failed got a 403 with a real token:

00:45:31Z task 5608680262 solved in 47.7s
00:45:31Z token: 1.F9jwQW7KDG... (709 chars)
00:45:31Z injected: {"created":false,"callback":"javascriptCallback is undefined"}
00:45:32Z HTTP 403 https://www.scrapingcourse.com/login/cf-turnstile | Forbidden | 0 products

The token was fine. The field wasn't. The widget keeps retrying in the background, and each retry empties cf-turnstile-response. I put a marker in the field and refilled it whenever it changed: in two minutes the widget emptied it 17 times, in pairs about 13 seconds apart. Typing two fields and clicking takes about a second, so now and then a retry lands in that gap.

To check, I did it on purpose with one real token. A: fill the field, wait until the widget empties it, click. B: reload, then fill and submit in a single in-page call. A never sent the token, so B was its first use:

01:05:21Z task 5608863527 solved in 21.2s
01:05:21Z A: field filled, 709 chars
01:05:27Z A: 6.1s later the field holds 0 chars, clicking Submit
01:05:28Z A: HTTP 403 https://www.scrapingcourse.com/login/cf-turnstile | Forbidden
01:05:29Z B: HTTP 200 https://www.scrapingcourse.com/dashboard | Success Page - ScrapingCourse.com

So the final script types the credentials, then sets the field and submits inside one page.evaluate(). The widget can't run in the middle of that function.

The callback goes into the same call. On many sites it enables the submit button or sends the form, so call it when it exists. Here it's declared but never defined, so check typeof first.

The whole script

// login-puppeteer.mjs: solve the Turnstile widget on a practice login page and log in with Puppeteer.
// Needs: Node 22.12+, npm i puppeteer-core@25.14.0, Chrome installed, turnstile.mjs next to this file.
//   CAPTCHAAI_KEY=... node login-puppeteer.mjs            solve, fill, submit
//   node login-puppeteer.mjs <token>                      skip the solve, use this token
import puppeteer from "puppeteer-core";
import { solveTurnstile } from "./turnstile.mjs";

const PAGE = "https://www.scrapingcourse.com/login/cf-turnstile";
const log = (...a) => console.log(new Date().toISOString().slice(11, 19) + "Z", ...a);

const browser = await puppeteer.launch({ channel: "chrome", headless: true });
try {
  const page = await browser.newPage();
  await page.goto(PAGE, { waitUntil: "domcontentloaded" });

  // 1. The widget's settings, straight from its data-* attributes
  const widget = await page.$eval(".cf-turnstile", (el) => ({
    sitekey: el.dataset.sitekey,
    action: el.dataset.action ?? null,
    cdata: el.dataset.cdata ?? null, // read it to know it's there: the API reference has no field for it
    callback: el.dataset.callback ?? null,
  }));
  log("widget:", JSON.stringify(widget));

  // 2. A token for that sitekey on this URL (or the one from the command line)
  const token = process.argv[2] ??
    await solveTurnstile({ sitekey: widget.sitekey, pageurl: page.url(), action: widget.action, log });
  log(`token: ${token.slice(0, 12)}... (${token.length} chars)`);

  // 3. The demo credentials the page shows
  await page.type("#email", "admin@example.com");
  await page.type("#password", "password");

  // 4. Fill the hidden field and submit in one step: the widget keeps retrying in the
  //    background, and each retry empties that field
  await page.waitForSelector('input[name="cf-turnstile-response"]', { timeout: 15_000 }).catch(() => {});
  const [response, filled] = await Promise.all([
    page.waitForNavigation({ waitUntil: "domcontentloaded" }),
    page.evaluate((token, callback) => {
      const form = document.querySelector(".cf-turnstile").closest("form");
      let field = form.querySelector('input[name="cf-turnstile-response"]');
      const created = !field; // the widget never added its field, so add one
      if (created) {
        field = Object.assign(document.createElement("input"), { type: "hidden", name: "cf-turnstile-response" });
        form.append(field);
      }
      field.value = token;
      const fn = callback ? window[callback] : undefined;
      if (typeof fn === "function") fn(token); // only if the page really defines it
      form.requestSubmit();
      return { created, callback: callback ? `${callback} is ${typeof fn}` : "none" };
    }, token, widget.callback),
  ]);
  log("filled and submitted:", JSON.stringify(filled));

  const products = await page.$$eval(".product-item .product-name", (els) => els.map((e) => e.textContent));
  log(`HTTP ${response.status()} ${page.url()} | ${await page.title()} | ${products.length} products`,
    products.length ? `(first: ${products[0]})` : "");
} finally {
  await browser.close();
}

Install with npm i puppeteer-core@25.14.0 (Node 22.12 or newer). channel: "chrome" launches your installed Chrome. With the full puppeteer package you can drop it and use the browser it downloads. A run where the solve took 47.6 seconds, like the one that failed before:

$ CAPTCHAAI_KEY=... node login-puppeteer.mjs
00:53:47Z widget: {"sitekey":"0x4AAAAAAAW9zqSPAlyOSMfO","action":null,"cdata":null,"callback":"javascriptCallback"}
00:53:47Z task 5608761828 submitted
00:54:34Z task 5608761828 solved in 47.6s
00:54:34Z token: 1.CaI_ZUyVXs... (709 chars)
00:54:35Z filled and submitted: {"created":false,"callback":"javascriptCallback is undefined"}
00:54:36Z HTTP 200 https://www.scrapingcourse.com/dashboard | Success Page - ScrapingCourse.com | 12 products (first: Chaz Kangeroo Hoodie)

All five runs of this version logged in. The 25 solves in my logs took 16 to 48 seconds: 21 landed on the 16-, 21- or 26-second poll, one on 32 and three around 48, so keep the 120-second timeout. A token as the first argument skips the solve and tests the page side for free (not-a-real-token gets a 403). The Playwright version, in Python, is in this earlier post.

How long a token lasts, and how often it works

From Cloudflare's server-side validation docs: "Each token is valid for 300 seconds (5 minutes) after generation", and each one "can only be validated once". I tested both on this server, every login in a fresh session:

# one token, two logins
00:56:42Z first use: HTTP 200 https://www.scrapingcourse.com/dashboard | Success Page - ScrapingCourse.com | 12 products
00:56:43Z same token, new session: HTTP 200 https://www.scrapingcourse.com/dashboard | Success Page - ScrapingCourse.com | 12 products
# two tokens, each held before its only login
01:01:17Z used 240s after it arrived: HTTP 200 https://www.scrapingcourse.com/dashboard | Success Page - ScrapingCourse.com | 12 products
01:02:29Z used 310s after it arrived: HTTP 403 https://www.scrapingcourse.com/login/cf-turnstile | Forbidden | 0 products

The age limit held: 240 seconds passed, 310 didn't. Single use didn't: the same token logged in twice, in both runs. I don't know how this server validates, but a random 709-character string and the dummy token both got 403. A server that calls siteverify as Cloudflare documents refuses a second use (timeout-or-duplicate), so use one token per submit, within a few minutes of the solve. If a fresh token still gets refused, this post on Turnstile 403s covers the other causes.

This form doesn't need a browser

The same login works with Node's fetch alone: GET the page, keep its cookies, read _token and the sitekey from the HTML, solve, POST. It worked first time. fetch keeps no cookies, and the login redirects to a dashboard that checks the session cookie, so follow redirects yourself and send the cookies on each hop. The status code tells you which check failed. The same POST with a fake token:

00:38:56Z cookies + _token: HTTP 403 | Forbidden
00:38:56Z _token, no cookies: HTTP 419 | Page Expired
00:38:56Z cookies, no _token: HTTP 419 | Page Expired

419 means the session is wrong, and the Turnstile check never ran. 403 is the Turnstile check.

When the API says no: ERROR_WRONG_SITEKEY and ERROR_CAPTCHA_UNSOLVABLE

The docs list ERROR_WRONG_SITEKEY for a sitekey that is "blank or malformed". That's not quite what came back. Raw in.php replies, then how the accepted tasks ended (trimmed):

00:31:43Z empty sitekey: in.php -> {"status":0,"request":"ERROR_BAD_PARAMETERS"}
00:31:43Z sitekey 'abc': in.php -> {"status":1,"request":5608561322}
00:31:43Z no pageurl: in.php -> {"status":0,"request":"ERROR_BAD_PARAMETERS"}
00:31:44Z real sitekey, wrong page URL: in.php -> {"status":1,"request":5608561373}
00:32:54Z sitekey 'abc': task 5608561322 at 70.4s -> {"status":0,"request":"ERROR_CAPTCHA_UNSOLVABLE"}
00:33:05Z real sitekey, wrong page URL: task 5608561373 at 80.8s -> {"status":0,"request":"ERROR_CAPTCHA_UNSOLVABLE"}

A missing field fails at once. A bad sitekey, or the right one on the wrong page URL, gets a task id and fails later, here after 70 and 81 seconds. The URL matters because a sitekey only works on the hostnames its owner allowed (error 110200, "Domain not authorized", in Cloudflare's list).

ERROR_WRONG_SITEKEY did show up once, from res.php, for the sitekey "undefined". That's what URLSearchParams sends when the value is undefined, say on a page with no data-sitekey:

01:14:10Z form body: method=turnstile&sitekey=undefined&pageurl=...&json=1
01:14:11Z in.php -> {"status":1,"request":5608945475}
01:14:26Z task 5608945475 at 15.6s -> {"status":0,"request":"ERROR_WRONG_SITEKEY"}

On a second try the same input came back ERROR_CAPTCHA_UNSOLVABLE after 55 seconds. So the helper refuses a missing sitekey before sending anything, stops on ERROR_BAD_PARAMETERS or ERROR_WRONG_SITEKEY from either endpoint, and gives ERROR_CAPTCHA_UNSOLVABLE one more task. Fed a reCAPTCHA sitekey, it failed twice and threw after 105 seconds. When both tasks fail, check the sitekey and the URL first.

What can still go wrong

There's no data-sitekey. The site calls turnstile.render(el, { sitekey: ... }) from its own script. Find that call and take the sitekey, and any action, from there.
The widget isn't inside a form. The site reads the token with turnstile.getResponse() or in its callback and posts it with fetch, so filling an input does nothing. Call the callback with the token, or send the request the site's script would send.
The token is accepted and you're still blocked. The token is one check. It does nothing for your IP's reputation, request rate or the site's other bot checks.

FAQ

Can Puppeteer pass Turnstile without a solver?
Not in my runs. Headless and headed, the widget failed within 5 seconds and was still failing at 30.

How long is a token valid?
300 seconds, per Cloudflare. Here, 240 passed and 310 failed.

One thing I couldn't test: a widget with data-cdata. If you've seen one accept or reject a solved token, I'd like to hear which.

Disclosure: I run CaptchaAI, the API these examples call. This article was written by an AI agent, and every output above is from a real run on 2026-10-18.

— Bassem

Captcha solving API in Python: the submit-and-poll loop, and what CAPCHA_NOT_READY and the key errors actually mean

Bassem Shahin — Thu, 22 Oct 2026 13:00:00 +0000

Most captcha-solving APIs speak the protocol 2Captcha made popular. You POST the captcha to in.php and get a task id back. Then you ask res.php for the answer until it's ready. The happy path is ten lines of Python.

The trouble is everything around those ten lines. Code that checks for CAPTCHA_NOT_READY, with a T, never sees the reply it is waiting for. A loop that retries every error keeps calling the API with a wrong key until the IP gets banned. A loop that retries nothing gives up on a server hiccup that would have cleared in ten seconds.

I wanted the replies the live API actually sends, not the ones I expected, so I ran the loop for real: image captchas and reCAPTCHA v2 tasks end to end, then a batch of broken requests on purpose (fake keys, missing parameters, task ids that were never issued, garbage uploads). This post has those replies as they came back, what each one means, which ones are worth retrying, and a Python module of about 80 lines that handles all of them.

The loop in four lines

Two endpoints. With json=1 both answer with a small JSON object:

in.php   key, method, <captcha data>, json=1    -> {"status": 1, "request": <task id>}
res.php  key, action=get, id=<task id>, json=1  -> {"status": 0, "request": "CAPCHA_NOT_READY"}   wait, ask again
                                                -> {"status": 1, "request": "<the answer>"}       done
                                                -> {"status": 0, "request": "ERROR_..."}          failed

status tells you whether request holds a result or a message. Every reply in this post, errors included, came back as HTTP 200, so the HTTP status code tells you almost nothing. Two details in the raw replies trip up parsers:

The task id is a number. A submit came back as {"status":1,"request":5540198133}: an integer, while the answer is a string. Run the id through str() before you store or compare it.
Not every reply is JSON, and the Content-Type won't tell you which. The successful replies above were valid JSON labelled text/html. Some errors arrived as plain text, also text/html, and one was an empty body. Try r.json() and catch the failure instead.

Without json=1 you get the same information as plain text: OK|5540103145 from in.php, CAPCHA_NOT_READY while the task runs, and OK|u6kyr once it's solved. It works, but JSON is easier to keep apart from the error texts below.

CAPCHA_NOT_READY is not an error

The not-ready reply is spelled CAPCHA_NOT_READY, without the T. The spelling goes back to the original 2Captcha protocol, and compatible APIs keep it so old clients still work. Compare against that exact string. If your code checks for CAPTCHA_NOT_READY, the first poll lands in your error branch, and depending on how that branch is written you either fail every task or poll forever.

It comes with status: 0, like an error, but it only means "not yet". Here is a real reCAPTCHA v2 task on Google's checkbox demo, first poll at 15 seconds, then every 5:

+  0.6s in.php  -> 5540087475
+ 16.1s res.php -> CAPCHA_NOT_READY
+ 21.6s res.php -> CAPCHA_NOT_READY
+ 27.1s res.php -> CAPCHA_NOT_READY
+ 32.7s res.php -> CAPCHA_NOT_READY
+ 38.2s res.php -> 0cAFcWeA6nNiZNfNuoUvZYcr9gRCG61N...(2510 chars)

How long to wait, and when to stop

The right numbers depend on the captcha type, and the difference is large:

Image (text) captchas: across 14 polled tasks, the answer was there on the very first poll every time, even when I polled the moment in.php replied. I never saw CAPCHA_NOT_READY for an image.
reCAPTCHA v2 checkbox tokens: 38 seconds today. Earlier runs on two public demo pages took 45, 90, 91 and 114 seconds. Three tasks across today's and the earlier runs were still not ready at 180 seconds.

So use one loop with per-type settings, not one timeout for everything:

	First poll after	Then every	Give up after
Image captcha	2 s (the docs say 5)	5 s	60 s
Token (reCAPTCHA and similar)	15 s	5 s	180 s

The 5-second interval is what the API docs ask for. Polling faster doesn't make the solver faster. It only adds requests.

When you give up, the task doesn't stop on the server. Both of today's timed-out tasks kept running and then failed by themselves, about four minutes after they were submitted:

17:18:06  in.php  -> 5540125413
17:21:11  my loop gives up: TIMEOUT after 180 s (29 polls, all CAPCHA_NOT_READY)
17:21:27  res.php -> CAPCHA_NOT_READY
17:22:17  res.php -> ERROR_CAPTCHA_UNSOLVABLE

The other one went the same way: submitted at 17:10:36, ERROR_CAPTCHA_UNSOLVABLE by 17:14:29. A five-minute timeout would not have saved either of them. Give up at your limit and submit a new task.

Finished results don't stay around for long either. Polling a solved id again returned the same answer for a while, then ERROR_ID_NOT_EXIST. Some results were still there after nine minutes. But three tasks submitted minutes apart all turned into ERROR_ID_NOT_EXIST within the same 20 seconds, which looks like a periodic cleanup rather than a fixed lifetime per task, so a result can vanish sooner than you'd guess. Read the answer once and keep it yourself. res.php is not storage.

Every reply I got, and what to do with it

These are the replies from the live API, not from the docs. The fake keys were obviously fake strings, and I kept those calls to a handful, because the docs warn that repeated bad authorization gets an IP banned (IP_BANNED, wait about five minutes).

Reply	What triggered it	Retry?
`CAPCHA_NOT_READY`	polling a task that is still running	Yes: wait 5 s, ask again
`ERROR_SERVER_ERROR`	`in.php` with `method=base64` and no `body`, on all three tries	Docs: transient, retry after ~10 s. Here it was my bug, so cap the retries
`ERROR_WRONG_USER_KEY`	a 14-character fake key, a 32-character fake key, and my real key with a trailing newline	No
`ERROR_METHOD_ERROR`	`in.php` with no `method`	No: fix the request
`ERROR_INVALID_METHOD`	`method=nosuchmethod`	No
`ERROR_BAD_PARAMETERS`	a reCAPTCHA task without `pageurl`	No
`Sitekey length is invalid.`	`googlekey=abc`. A sentence, not an `ERROR_` code	No
`{"status":1,...}` with a task id	`body` that wasn't base64, and a 20-byte PNG fragment	Accepted, but see the next row
`CaptchaAI INTERNAL ERROR: PROBABLY, INCORRECT REQUEST`	the first poll of either of those tasks, as `text/html` despite `json=1`	No: fix the image
`{"status":0,"request":""}`	later polls of the same broken task	No
`ERROR_ID_NOT_EXIST`	polling id `1`, `99999999999`, `abc` or no id at all, and real ids after they expired	No: stop polling this id
`CaptchaAI**IN`	`in.php` with no `key` field at all	No
`ERROR_CAPTCHA_UNSOLVABLE`	the two reCAPTCHA tasks above, about four minutes in	Yes, as a new task
empty body	`res.php` with no `action`	No

The error-handling page in the docs uses a few different names for some of these. It lists ERROR_WRONG_CAPTCHA_ID and ERROR_WRONG_ID_FORMAT for bad ids, ERROR_EMPTY_ACTION for a missing action, and ERROR_PAGEURL for a missing page URL. The table above is what came back. The practical lesson: don't write a branch per error name, because you will meet names, sentences and empty strings you didn't plan for. Keep a short allow-list of replies worth retrying and treat everything else as fatal.

ERROR_KEY_DOES_NOT_EXIST, ERROR_WRONG_USER_KEY and "account authorization key not found in the system"

All three mean the same thing: the API doesn't know the key you sent.

ERROR_WRONG_USER_KEY: the docs define it as a key in the wrong format (it must be 32 characters). In my runs it was also the reply to a 32-character key that doesn't exist.
ERROR_KEY_DOES_NOT_EXIST: the docs define it as a well-formed key that no account has. I couldn't make the live API return it. The 32-character fake key got ERROR_WRONG_USER_KEY instead. Handle the two the same way.
"Account authorization key not found in the system" is how Anti-Captcha's documentation describes its ERROR_KEY_DOES_NOT_EXIST. Same meaning.

None of these is retryable, and retrying them is how you collect an IP_BANNED. Check these causes instead:

Whitespace. My real key with a \n on the end, as you get from reading a key file without .strip(), came back ERROR_WRONG_USER_KEY.
An unset variable. os.environ.get("KEY") gives None. An f-string turns that into the string "None", and requests leaves a None field out of the form entirely, so the API sees no key at all (the CaptchaAI**IN row above).
The key of another service. If you moved from one 2Captcha-style API to another, you changed the base URL. Check that you changed the key too.

Balance errors: ERROR_ZERO_BALANCE

I didn't trigger this one on purpose, so here is what the docs say: ERROR_ZERO_BALANCE comes from in.php when there is "insufficient balance/threads to accept the task", and the fix is to "top up or reduce concurrency and retry".

The "threads" part matters on a thread-based plan, where you pay for concurrent slots instead of per solve. There, res.php?action=getbalance returns your thread count, not money. My test key replied {"status":1,"request":"5"}. So, going by the docs' wording, ERROR_ZERO_BALANCE can mean that every thread is busy, not only that the plan ran out. The module below backs off for 10, then 20 seconds and tries again. If it still fails, it raises, because at that point the plan needs a human. If you run tasks in parallel, cap the number of workers at the getbalance number so you don't run into it in the first place.

The module

This is the whole thing, standard requests and nothing else. call() turns every kind of reply (JSON, plain text, empty, HTTP 5xx, network failure) into an (ok, text) pair. submit() and poll() decide what to retry. solve() sends a new task when the solver gave up on the old one.

"""captcha_api.py: submit a captcha task to an in.php/res.php API and poll for the answer.
Needs: pip install requests
"""
import os
import time

import requests

API = "https://ocr.captchaai.com"
API_KEY = os.environ.get("CAPTCHAAI_KEY", "").strip()  # a stray newline = a wrong key

NOT_READY = "CAPCHA_NOT_READY"  # sic: no T. Match this exact string.
TRANSIENT = {"ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR", "NETWORK_ERROR"}
BUSY = {"ERROR_ZERO_BALANCE"}             # no funds or no free thread: wait, then give up
RESUBMIT = {"ERROR_CAPTCHA_UNSOLVABLE"}   # this task failed; a new task can still work


class CaptchaError(Exception):
    def __init__(self, stage, code):
        super().__init__(f"{stage}: {code or '(empty reply)'}")
        self.code = code


def call(path, **params):
    """One request. Returns (ok, text) and never raises for HTTP or network trouble."""
    try:
        r = requests.post(f"{API}/{path}", data={**params, "key": API_KEY, "json": 1}, timeout=30)
    except requests.RequestException:
        return False, "NETWORK_ERROR"
    if r.status_code >= 500:
        return False, "ERROR_SERVER_ERROR"
    try:
        reply = r.json()
    except ValueError:  # seen live: a plain-text error even with json=1
        return False, r.text.strip()[:120]
    return reply.get("status") == 1, str(reply.get("request", ""))  # the id can be an int


def submit(task, tries=3, log=None):
    """POST the task to in.php and return its id. Retries only what a retry can fix."""
    if not API_KEY:
        raise SystemExit("Set CAPTCHAAI_KEY to your API key first")
    for attempt in range(tries):
        if attempt:
            time.sleep(10 * 2 ** (attempt - 1))  # 10 s, then 20 s
        ok, text = call("in.php", **task)
        if log:
            log("in.php", text)
        if ok:
            return text
        if text not in TRANSIENT | BUSY:
            raise CaptchaError("in.php", text)  # bad key or bad request: retrying won't help
    raise CaptchaError("in.php", text)


def poll(task_id, first_wait=5, interval=5, timeout=120, log=None):
    """Poll res.php until the answer arrives, the task fails, or the time runs out."""
    deadline = time.monotonic() + timeout
    time.sleep(first_wait)
    errors = 0
    while time.monotonic() < deadline:
        ok, text = call("res.php", action="get", id=task_id)
        if log:
            log("res.php", text)
        if ok:
            return text
        if text == NOT_READY:
            time.sleep(interval)
        elif text in TRANSIENT and errors < 3:
            errors += 1
            time.sleep(interval * 2 ** errors)
        else:  # unsolvable, unknown id, a broken upload, too many server errors
            raise CaptchaError("res.php", text)
    raise CaptchaError("res.php", f"TIMEOUT: task {task_id} not solved in {timeout}s")


def solve(task, resubmits=1, log=None, **poll_args):
    """submit() + poll(). A task the solver gave up on is sent again, `resubmits` times."""
    for attempt in range(resubmits + 1):
        try:
            return poll(submit(task, log=log), log=log, **poll_args)
        except CaptchaError as e:
            if e.code not in RESUBMIT or attempt == resubmits:
                raise

Set the key with CAPTCHAAI_KEY=... in the environment. Then call it with the task fields for your captcha type and the timing for that type:

"""example.py: use captcha_api.solve() for an image captcha or a reCAPTCHA v2 checkbox.

  CAPTCHAAI_KEY=... python example.py captcha.png
  CAPTCHAAI_KEY=... python example.py recaptcha <sitekey> <page url>
"""
import base64
import sys
import time

from captcha_api import CaptchaError, solve

started = time.monotonic()


def log(path, text):
    print(f"  +{time.monotonic() - started:5.1f}s {path} -> {text[:50]}")


try:
    if sys.argv[1] == "recaptcha":  # a token: slow, so wait longer before the first poll
        task = {"method": "userrecaptcha", "googlekey": sys.argv[2], "pageurl": sys.argv[3]}
        answer = solve(task, first_wait=15, interval=5, timeout=180, log=log)
    else:  # an image: usually answered in a few seconds
        body = base64.b64encode(open(sys.argv[1], "rb").read()).decode()
        answer = solve({"method": "base64", "body": body}, first_wait=2, interval=5, timeout=60, log=log)
    print("answer:", answer[:50])
except CaptchaError as e:
    print("failed:", e.code)  # fatal, or still failing after the retries

A real run on a generated test captcha that shows Q8TP3:

$ CAPTCHAAI_KEY=... python example.py captcha.png
  +  1.1s in.php -> 5540206752
  +  4.2s res.php -> q8tp3
answer: q8tp3

Answers come back in lowercase. If the site cares about case, add regsense=1 to the task. And here is the same script on the reCAPTCHA demo when the task doesn't finish:

$ CAPTCHAAI_KEY=... python example.py recaptcha 6LfW6wATAAAAAHLqO2pb8bDBahxlMxNdo9g947u9 https://recaptcha-demo.appspot.com/recaptcha-v2-checkbox.php
  +  0.5s in.php -> 5540125413
  + 16.3s res.php -> CAPCHA_NOT_READY
  + 22.4s res.php -> CAPCHA_NOT_READY
  ...
  +180.3s res.php -> CAPCHA_NOT_READY
failed: TIMEOUT: task 5540125413 not solved in 180s

To check the error paths, I pushed broken tasks through the same functions with my real key:

1. no method: a request bug, raised on the first reply
  +  0.7s in.php  -> ERROR_METHOD_ERROR
  +  0.7s raised CaptchaError('ERROR_METHOD_ERROR')

2. method=base64 but no body: the server says ERROR_SERVER_ERROR, so it is retried, 3 tries max
  +  0.6s in.php  -> ERROR_SERVER_ERROR
  + 13.5s in.php  -> ERROR_SERVER_ERROR
  + 35.8s in.php  -> ERROR_SERVER_ERROR
  + 35.8s raised CaptchaError('ERROR_SERVER_ERROR')

3. a 20-byte image fragment: accepted by in.php, fails on the first poll
  +  1.6s in.php  -> 5540121107
  +  4.2s res.php -> CaptchaAI INTERNAL ERROR: PROBABLY, INCORRECT REQUEST
  +  4.2s raised CaptchaError('CaptchaAI INTERNAL ERROR: PROBABLY, INCORRECT REQUEST')

4. polling an id that was never issued
  +  0.8s res.php -> ERROR_ID_NOT_EXIST
  +  0.8s raised CaptchaError('ERROR_ID_NOT_EXIST')

Case 2 is why every retry needs a cap. The server called a missing parameter a server error, three times in a row. A loop that retries "transient" errors without a limit would have kept going forever.

What can still go wrong

status: 1 means the solver answered, not that the answer is right. Some of my test images came back with wrong characters. Only the site can tell you. On a rejection, load a fresh captcha and submit a new task. Don't send the same image again with a different guess, since most sites have already thrown that code away.
in.php accepting a task doesn't mean the input was good. A string that wasn't base64 and a 20-byte fragment both got a task id. The error only showed up on the first poll. Check the image size and format before you submit. The docs ask for JPG, PNG or GIF between 100 bytes and 100 KB.
A network error on in.php is ambiguous. The task may have been created even though you never saw its id. Retrying creates a second task. That's harmless for correctness, but on a thread-based plan the lost one may hold a thread until it finishes.
Tokens expire. A reCAPTCHA token is valid for two minutes and can be verified only once. Solve right before you need it, not when the page loads.
The TRANSIENT set is a guess about the future. If your logs show an error text you haven't seen before, look at it before you add it to a retry list. Most of the replies in the table above are bugs on the caller's side.

FAQ

What does CAPCHA_NOT_READY mean?
The task is still being solved. It's status: 0 but not an error: wait about 5 seconds and poll res.php again with the same id. Note the spelling, without the T.

What is the difference between ERROR_WRONG_USER_KEY and ERROR_KEY_DOES_NOT_EXIST?
On paper, the first is a key in the wrong format and the second is a well-formed key that doesn't exist. In practice, the live API answered ERROR_WRONG_USER_KEY to both kinds of fake key. Either way: check the key for whitespace, for an unset variable, and for a key from another service. Don't retry.

How often should I poll a captcha API?
Every 5 seconds. Start after about 2 seconds for an image captcha and 15 seconds for a token. Stop at 60 seconds for images and around 180 for tokens.

Can I skip polling?
For image captchas, yes: the docs list a solve.php endpoint that takes the same fields as in.php and replies with the answer in one call. Mine came back in 1.0 seconds. Token tasks still go through in.php and res.php.

Which errors are worth retrying?
CAPCHA_NOT_READY (wait and poll), ERROR_SERVER_ERROR and ERROR_INTERNAL_SERVER_ERROR (back off, at most three times), ERROR_ZERO_BALANCE (back off, then stop), and ERROR_CAPTCHA_UNSOLVABLE (as a new task). Everything else is a problem with the key or the request.

Disclosure: I run CaptchaAI, the API these examples call. This article was written by an AI agent; the harness, the raw replies and the module above came from real runs against it on 2026-10-12.

— Bassem

reCAPTCHA v2 solver in Python: solve the checkbox with an API and submit the token in Selenium

Bassem Shahin — Mon, 19 Oct 2026 13:00:00 +0000

Your Selenium script fills in a form, reaches the "I'm not a robot" checkbox and stops. Clicking the box from automation usually opens an image grid, and the grid keeps coming back. Even when a run gets through, it isn't something you can repeat a thousand times a day.

The checkbox itself doesn't matter, though. What the site checks is a token. When a person solves the widget, reCAPTCHA writes a token into a hidden g-recaptcha-response field, and the site's backend sends that token to Google to verify. A solving API returns the same kind of token from two inputs: the sitekey and the page URL. So a reCAPTCHA v2 solver in Python has three jobs: read the sitekey, get a token from the API, and put the token where the form reads it before you submit.

This post does all three against Google's own checkbox demo, first in Selenium and then with plain requests. I ran everything on 2026-10-10, and every output below is copied from those runs.

What the token is, and what Google checks

The token is a long opaque string (2,489 characters in the Selenium run below). The site's server posts it to Google's siteverify endpoint with its secret key. Google answers with success and the hostname the token was issued for. Two rules from Google's verification docs shape the code:

A token is valid for two minutes.
A token can be verified once.

So get the token right before you submit, use it straight away, and never reuse one.

For a standard v2 checkbox, the browser that submits the token doesn't have to be the one that solved it. In my runs, Google's demos accepted API tokens submitted from headless Chrome, where navigator.webdriver was true, and from requests, with no browser at all. Enterprise keys can be stricter; there's more on that under "What can still go wrong".

Step 1: read the sitekey from the anchor iframe

A sitekey is 40 characters long and starts with 6L. When the widget is declared in the HTML you can read it from data-sitekey="6L...". Many sites render the widget from JavaScript instead, so in Selenium it's more reliable to read what reCAPTCHA actually rendered. Every widget gets an anchor iframe, and its URL carries the sitekey as k= and the widget type as size=. These are the anchors on Google's checkbox demo and on its invisible demo:

https://www.google.com/recaptcha/api2/anchor?ar=1&k=6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-&co=aHR0cHM6Ly93d3cuZ29vZ2xlLmNvbTo0NDM.&hl=en&v=nY0xPItgwtlvjEjk2TqdwOQz&size=normal&sa=action&anchor-ms=20000&execute-ms=30000&cb=go5o9v7hms4v
https://www.google.com/recaptcha/api2/anchor?ar=1&k=6LfP0CITAAAAAHq9FOgCo7v_fb0-pmmH9VW3ziFs&co=aHR0cHM6Ly93d3cuZ29vZ2xlLmNvbTo0NDM.&hl=en&v=nY0xPItgwtlvjEjk2TqdwOQz&size=invisible&sa=action&anchor-ms=20000&execute-ms=30000&cb=f34pt91snzb9

A checkbox reports size=normal (or compact). Invisible v2 and v3 both report size=invisible, and they need different solver parameters, so the script below skips them. If that's what you have, the invisible reCAPTCHA v2 walkthrough and the v3 solver post cover them.

Two more things the anchor URL tells you. The path is /recaptcha/api2/anchor for a standard key and /recaptcha/enterprise/anchor when the widget is served as Enterprise. And sa= is present on the standard demo too, so sa on its own doesn't mean Enterprise.

Step 2: get a token from the API

The solve is a standard reCAPTCHA v2 task on the 2Captcha-style in.php / res.php API:

Parameter	Value
`method`	`userrecaptcha`
`googlekey`	the sitekey from step 1
`pageurl`	the full URL of the page that shows the widget
`json`	`1`, so the replies are JSON

There's no invisible=1 and no version for a checkbox. You get a task id back. Wait about 15 seconds, then poll res.php every 5 seconds until the token arrives. Server errors are retried with a backoff capped at 30 seconds. Account and input errors stop at once, because retrying won't fix them.

"""recaptcha_v2.py: get a reCAPTCHA v2 (checkbox) token from a solving API. Needs: pip install requests"""
import os
import re
import time

import requests

API = "https://ocr.captchaai.com"  # 2Captcha-style in.php / res.php
API_KEY = os.environ.get("CAPTCHAAI_KEY", "YOUR_API_KEY")
TRANSIENT = {"ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"}


def call(path, **kw):
    """One API call; network errors and non-JSON replies come back as a transient error."""
    try:
        return requests.request(timeout=30, url=f"{API}/{path}", **kw).json()
    except (requests.RequestException, ValueError) as exc:
        return {"status": 0, "request": "ERROR_SERVER_ERROR", "detail": str(exc)}


def solve_recaptcha_v2(sitekey, pageurl, timeout=180, log=print):
    """Return a g-recaptcha-response token for a checkbox widget."""
    if API_KEY in ("", "YOUR_API_KEY"):
        raise SystemExit("Set CAPTCHAAI_KEY to your API key first")
    if not re.fullmatch(r"6L[\w-]{38}", sitekey):
        raise SystemExit(f"{sitekey!r} doesn't look like a reCAPTCHA sitekey")
    params = {"key": API_KEY, "method": "userrecaptcha", "googlekey": sitekey,
              "pageurl": pageurl, "json": 1}
    for attempt in range(3):
        r = call("in.php", method="POST", data=params)
        if r["status"] == 1:
            break
        if r["request"] not in TRANSIENT:  # ERROR_WRONG_USER_KEY, ERROR_ZERO_BALANCE,
            raise RuntimeError(f"in.php: {r['request']}")  # ERROR_PAGEURL, ...
        time.sleep(5 * 2 ** attempt)
    else:
        raise RuntimeError("in.php: server errors on 3 tries")

    task_id, started, wait = r["request"], time.time(), 5
    log(f"task {task_id} submitted")
    time.sleep(15)  # nothing is ready before ~15 s
    while time.time() - started < timeout:
        r = call("res.php", method="GET", params={
            "key": API_KEY, "action": "get", "id": task_id, "json": 1})
        if r["status"] == 1:
            log(f"solved in {time.time() - started:.0f}s")
            return r["request"]
        if r["request"] in TRANSIENT:
            wait = min(wait * 2, 30)  # back off on server trouble
        elif r["request"] == "CAPCHA_NOT_READY":
            wait = 5
        else:  # ERROR_CAPTCHA_UNSOLVABLE, ERROR_WRONG_CAPTCHA_ID, ...
            raise RuntimeError(f"res.php: {r['request']}")
        time.sleep(wait)
    raise TimeoutError(f"task {task_id} not solved in {timeout}s")

The timeout is 180 seconds, not 60. Solve times vary, and the next sections show what they were in my runs.

Step 3: put the token where the form reads it

This is where most Selenium attempts break. The token belongs in the g-recaptcha-response textarea, which reCAPTCHA adds to the page itself, not inside the iframe. It's hidden with display: none, so send_keys can't reach it. This is what my probe of the demo page printed:

textarea id=g-recaptcha-response displayed=False style='width: 250px; height: 40px; border: 1px solid rgb(193, 193, 193); margin: 10px 25px; padding: 0px; resize: none; display: none;'
send_keys: ElementNotInteractableException Message: element not interactable

So set the value with JavaScript. Then do what reCAPTCHA would do after a real solve: call the widget's callback if it has one. On Google's demo that's data-callback="onSuccess", a function that clears the "please verify" error. On real sites, the callback often enables the submit button or submits the form itself, and filling the textarea without calling it changes nothing.

The whole flow in Selenium

Prerequisites: Python 3.9+, Chrome, and pip install selenium requests, with recaptcha_v2.py from step 2 in the same folder. Selenium 4.6+ downloads a matching chromedriver by itself.

# selenium_recaptcha_v2.py: solve a reCAPTCHA v2 checkbox in Selenium with a solving API.
# Needs: pip install selenium requests   (recaptcha_v2.py sits next to it, Chrome installed)
import sys
from urllib.parse import parse_qs, urlparse

from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.ui import WebDriverWait

from recaptcha_v2 import solve_recaptcha_v2

ANCHOR = 'iframe[src*="/recaptcha/"][src*="/anchor"]'  # one per rendered widget

# Fill every response textarea (it's hidden, so send_keys can't reach it),
# then call the widget's data-callback if it has one, as reCAPTCHA would.
INJECT = """
const [token, sitekey] = arguments;
document.querySelectorAll('textarea[name="g-recaptcha-response"]')
  .forEach((t) => { t.value = token; });
const el = document.querySelector(`[data-sitekey="${sitekey}"][data-callback]`);
const name = el ? el.getAttribute("data-callback") : null;
let fn = window;
for (const part of (name || "").split(".").filter(Boolean)) fn = fn ? fn[part] : undefined;
if (typeof fn === "function") { fn(token); return name; }
return null;
"""


def find_checkbox(driver, timeout=20):
    """Read the sitekey from the widget's anchor iframe, the one reCAPTCHA really rendered."""
    WebDriverWait(driver, timeout).until(
        EC.presence_of_element_located((By.CSS_SELECTOR, ANCHOR)))
    for frame in driver.find_elements(By.CSS_SELECTOR, ANCHOR):
        q = parse_qs(urlparse(frame.get_attribute("src")).query)
        if q.get("size", [""])[0] != "invisible":  # invisible v2 and v3 say "invisible"
            return q["k"][0]
    raise SystemExit("No checkbox widget: the page uses invisible v2 or v3")


def main(url, token=None):
    opts = webdriver.ChromeOptions()
    opts.add_argument("--headless=new")
    driver = webdriver.Chrome(options=opts)
    try:
        driver.get(url)
        sitekey = find_checkbox(driver)
        print("sitekey:", sitekey)

        # pageurl is the page that shows the widget, after any redirects
        token = token or solve_recaptcha_v2(sitekey, driver.current_url)
        print("token:", token[:20] + "...", f"({len(token)} chars)")
        print("callback called:", driver.execute_script(INJECT, token, sitekey))

        old_page = driver.find_element(By.TAG_NAME, "html")
        driver.find_element(By.CSS_SELECTOR, "form [type=submit]").click()
        WebDriverWait(driver, 20).until(EC.staleness_of(old_page))  # the form posted
        # Google's demo answers with one of these two lines; on your site, use its own signal
        lines = driver.find_element(By.TAG_NAME, "body").text.splitlines()
        print("demo says:", [s for s in lines if "Hooray" in s or "not a robot" in s])
    finally:
        driver.quit()


if __name__ == "__main__":
    main(sys.argv[1] if len(sys.argv) > 1 else "https://www.google.com/recaptcha/api2/demo",
         sys.argv[2] if len(sys.argv) > 2 else None)

With an API key set and no second argument, it solves and submits:

$ CAPTCHAAI_KEY=... python selenium_recaptcha_v2.py
sitekey: 6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-
task 5520654748 submitted
solved in 91s
token: 0cAFcWeA4OJwZvvxnoKD... (2489 chars)
callback called: onSuccess
demo says: ['Verification Success... Hooray!']

Verification Success... Hooray! is the demo's answer after its backend verified the token with Google.

Test the plumbing without spending a solve

The optional second argument is used as the token, so you can check the page side for free. A fake token shows what a rejection looks like. The script finds the widget, fills the field, calls the callback and submits, and the demo refuses the token:

$ python selenium_recaptcha_v2.py https://www.google.com/recaptcha/api2/demo 03AFcWeA-not-a-real-token
sitekey: 6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-
token: 03AFcWeA-not-a-real-... (25 chars)
callback called: onSuccess
demo says: ['Please verify that you are not a robot.']

Pointed at the invisible demo, the script stops before it spends anything:

$ python selenium_recaptcha_v2.py "https://www.google.com/recaptcha/api2/demo?invisible=true"
No checkbox widget: the page uses invisible v2 or v3

No browser: the same token with requests

If the form is plain HTML and posts normally, you don't need Selenium at all. Google's other checkbox demo, on recaptcha-demo.appspot.com, is that kind of form, and its backend prints its own siteverify result. The regexes below fit that demo's markup. For real forms, use a proper parser like the finder in the invisible post.

# requests_recaptcha_v2.py: the same solve with no browser, for a plain HTML form.
# Needs: pip install requests   (recaptcha_v2.py sits next to it)
import re
import sys

import requests

from recaptcha_v2 import solve_recaptcha_v2

page = sys.argv[1] if len(sys.argv) > 1 else \
    "https://recaptcha-demo.appspot.com/recaptcha-v2-checkbox.php"
s = requests.Session()
html = s.get(page, timeout=30).text
sitekey = re.search(r'data-sitekey="(6L[\w-]{38})"', html).group(1)
action = re.search(r'<form[^>]*action="([^"]*)"', html).group(1)
fields = dict(re.findall(r'<input type="text" name="([^"]+)" value="([^"]*)"', html))
print("sitekey:", sitekey, "| form:", action, fields)

token = sys.argv[2] if len(sys.argv) > 2 else solve_recaptcha_v2(sitekey, page)
reply = s.post(requests.compat.urljoin(page, action),
               data={**fields, "g-recaptcha-response": token}, timeout=30)
# the demo backend prints its own siteverify result
print("siteverify:", re.findall(r"'(success|hostname)' => '?([\w.-]+)", reply.text),
      re.findall(r"\d+ => '([a-z-]+)'", reply.text))

$ CAPTCHAAI_KEY=... python requests_recaptcha_v2.py
sitekey: 6LfW6wATAAAAAHLqO2pb8bDBahxlMxNdo9g947u9 | form: /recaptcha-v2-checkbox.php {'ex-a': 'foo', 'ex-b': 'bar'}
task 5520667118 submitted
solved in 90s
siteverify: [('success', 'true'), ('hostname', 'recaptcha-demo.appspot.com')] []

With the fake token, this demo spells out why Google rejected it:

$ python requests_recaptcha_v2.py https://recaptcha-demo.appspot.com/recaptcha-v2-checkbox.php 03AFcWeA-not-a-real-token
sitekey: 6LfW6wATAAAAAHLqO2pb8bDBahxlMxNdo9g947u9 | form: /recaptcha-v2-checkbox.php {'ex-a': 'foo', 'ex-b': 'bar'}
siteverify: [('success', 'false'), ('hostname', 'NULL')] ['invalid-input-response', 'hostname-mismatch']

What can still go wrong

ElementNotInteractableException on the textarea. You used send_keys. The field is hidden, so set .value with execute_script as above.
The form still says "please verify" with a real token. Most often the token expired or was already used: it's valid for two minutes from when the solver got it, so don't solve ahead and queue tokens. Next, check that the token went into the textarea the form posts. A page with two widgets has g-recaptcha-response and g-recaptcha-response-1. The script fills all of them, which is fine for one widget but not for two different forms.
Nothing happens after you inject. The site waits for its callback, and this one isn't in data-callback. Sites that call grecaptcha.render(el, {callback: fn}) keep it in reCAPTCHA's internal config instead. This post on reCAPTCHA v2 callbacks shows how to find and trigger it from Selenium.
find_checkbox times out. The widget is inside another iframe, so the anchor isn't in the top document. Use driver.switch_to.frame(...) into that frame first and fill the textarea there. Send the frame's own URL as pageurl, because that's the page that shows the widget. driver.current_url still returns the top page, so read it with driver.execute_script("return location.href") inside the frame.
The submit wait times out after a successful inject. The form submits by XHR and the page never reloads. Wait for the site's own success element instead of staleness_of.
TimeoutError: task ... not solved in 180s. It happened to me once in five solves while writing this. The other four took 45, 114, 91 and 90 seconds. Submit a new task, and don't lower the timeout to make a slow solve fail sooner.
ERROR_WRONG_SITEKEY or ERROR_PAGEURL from in.php. The sitekey is blank or malformed, or pageurl is missing. Read both from the page again.
ERROR_WRONG_KEY_TYPE. The key isn't a v2 checkbox key. Check size= in the anchor URL.
An Enterprise checkbox. If the anchor path has /enterprise/ and the page calls grecaptcha.enterprise, send enterprise=1, and the sa= value as action if the anchor has one. The reply then includes the solver's User-Agent, which you have to submit with, so check the response format in the reCAPTCHA v2 Enterprise guide before you reuse solve_recaptcha_v2(). The anchor path is only a hint, though: this comparison of v2, v3 and Enterprise shows a demo whose standard key was served from the Enterprise path in most runs.
The token is accepted but the site still blocks you. reCAPTCHA is often only one of the site's checks. A valid token doesn't change navigator.webdriver or your IP's reputation. The demo didn't care about either, but your target might.
Old snippets fail with AttributeError: 'WebDriver' object has no attribute 'find_element_by_id'. Selenium 4.3 removed the find_element_by_* helpers. Use find_element(By.ID, ...).

FAQ

Can Selenium just click the checkbox?
You can switch into the anchor iframe and click #recaptcha-anchor, but an automated browser often gets the image challenge, and then you're solving grids. The token route skips the widget entirely.

Do I need a proxy for reCAPTCHA v2?
Not for the runs above, which used none. The API accepts an optional proxy and User-Agent for sites that check more than the token. Enterprise keys are where that comes up most.

How long can I keep a token?
Two minutes from issue, and one verification. Solve right before you submit.

Disclosure: I run CaptchaAI, the API these examples call. This article was written by an AI agent, and every output above is from a real run on 2026-10-10.

— Bassem

Image CAPTCHA solver in Python: send the right image to an OCR API and get an answer the site accepts

Bassem Shahin — Thu, 15 Oct 2026 13:00:00 +0000

An image CAPTCHA solver in Python comes down to three steps. Capture the exact image the page showed, in the session that loaded the page. Send those bytes to an OCR solving API and poll until it returns the text. Then type that text into the form and POST it in the same session, along with every hidden field the form carries.

The OCR step gets most of the attention, but it's rarely where things break. The usual failure is step one: code downloads the CAPTCHA URL a second time, the server generates a new code for that request, and a correct answer to the old picture gets rejected. Below is all three steps with runnable code, plus a decision on when local OCR like Tesseract is enough.

The setup

You're automating a form you're allowed to automate: an internal tool, a test environment, a portal you have an account on. It shows distorted letters and digits in an <img> and wants them typed into a text box. The goal is plain requests where possible, Playwright where the page needs a browser, and an accepted POST at the end.

First, check it's a text image CAPTCHA

Three different things get called "image CAPTCHAs", and each needs a different API call:

What you see	What it is	What the solver returns
Wavy letters/digits in one picture, a text box below	Text image CAPTCHA (OCR)	The text, e.g. `fadc5`
"Select all images with crosswalks", 3x3 or 4x4 tiles	Grid image challenge	Tile numbers to click, e.g. `1,4,7`
"I'm not a robot" checkbox, or nothing visible at all	reCAPTCHA / Turnstile (token-based)	A token for a hidden field; there's no image to OCR

This article covers the first row. If you're looking at the third, there's no picture to read; you need the site key and a token flow. I wrote up how to tell reCAPTCHA v2, v3 and Enterprise apart for that case.

Is Tesseract enough?

Try it first if the images are clean: one font, no overlapping characters, no strike-through lines, little rotation. Convert to grayscale, threshold to black and white, and run Tesseract in single-line mode with a character whitelist (--psm 7 -c tessedit_char_whitelist=ABCDEFGHJKLMNPQRSTUVWXYZ23456789). Some older or homemade CAPTCHAs are readable that way.

Tesseract is built to read documents, though. Distortion, characters that touch, and background noise are the features CAPTCHA generators add to defeat exactly that kind of OCR, and a whitelist doesn't fix them. Don't guess from one sample. Save 50 images from your target, label them by hand, and measure. If local OCR is right often enough for your retry budget, keep it. If not, send the image to a solving API, which is what the rest of this article does.

Step 1: capture the exact image the page showed

Most text CAPTCHAs work like this: the page HTML contains <img src="/captcha.php?r=0.123">, and each request to that URL generates a new random code, stores it in your server-side session, and returns its picture. The consequences:

Fetch the image exactly once, with the same cookie jar as the page and the form. Fetching it again (to save a copy, to retry a download, or with a fresh requests.get that has no cookies) replaces the code the server expects.
In a browser, don't download it at all. The browser has already fetched it once to render it. Downloading the src again counts as a second fetch. Screenshot the element instead; you get the exact pixels on screen.
If the src is a data:image/...;base64, URI, the image is already in the HTML. Decode it; there's nothing to download.
If it's drawn on a <canvas>, screenshot the canvas element the same way.

I tested the first rule with real solves against a local test form whose CAPTCHA endpoint stores one code per session. I downloaded the image, downloaded it a second time, then submitted the solver's answer for the first copy. All five tries got Incorrect captcha, including the three where the answer matched the first picture exactly (jjsva for an image showing JJSVA).

Step 2: send it to the solver

The API is the 2Captcha-style in.php/res.php pair: POST the image to in.php with method=post (multipart) or method=base64, get a task id back, then poll res.php until the text comes back. The docs say the image must be JPG, PNG or GIF, between 100 bytes and 100 KB. Enforce that on your side. In my tests the live in.php accepted a 50-byte fragment, a 250 KB PNG and a WebP file without complaint, and the problem only showed up when polling: a nonsense answer, or a non-JSON error page instead of a result.

Two optional flags help. Use regsense=1 when the CAPTCHA is case-sensitive: without it, answers came back in lowercase (fadc5 for an image showing FADC5). Use numeric=1 when it's digits only.

Prerequisites: Python 3.9+, pip install requests pillow, and an API key.

import io
import time
import requests
from PIL import Image

API_KEY = "YOUR_API_KEY"
API = "https://ocr.captchaai.com"
MAX_BYTES = 100 * 1024                       # the API takes 100 B to 100 KB
TRANSIENT = {"ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"}


class SolveError(Exception):
    pass


def prepare(img: bytes) -> tuple[bytes, str]:
    """Return (bytes, extension) in a format and size the API accepts."""
    if len(img) < 100 or img.lstrip()[:1] == b"<":
        raise SolveError(f"not a captcha image ({len(img)} bytes): did you save an error page?")
    if img[:8] == b"\x89PNG\r\n\x1a\n" and len(img) <= MAX_BYTES:
        return img, "png"
    if img[:3] == b"\xff\xd8\xff" and len(img) <= MAX_BYTES:
        return img, "jpg"
    if img[:4] == b"GIF8" and len(img) <= MAX_BYTES:
        return img, "gif"
    # WebP, BMP, or too big: re-encode as JPEG, lowering quality until it fits
    try:
        im = Image.open(io.BytesIO(img)).convert("RGB")
    except OSError:                          # PIL can't read it: SVG, a truncated file
        raise SolveError("not a readable image; convert it to PNG or JPG first")
    for quality in (90, 75, 60, 45):
        buf = io.BytesIO()
        im.save(buf, "JPEG", quality=quality)
        if len(buf.getvalue()) <= MAX_BYTES:
            return buf.getvalue(), "jpg"
    raise SolveError("image is still over 100 KB after re-encoding; crop it to the captcha")


def _call(method: str, path: str, **kw) -> dict:
    r = requests.request(method, f"{API}/{path}", timeout=30, **kw)
    try:
        return r.json()
    except ValueError:
        raise SolveError(f"non-JSON reply from {path} (HTTP {r.status_code}): {r.text[:80]!r}")


def solve_image(img: bytes, case_sensitive: bool = False, digits_only: bool = False) -> str:
    data, ext = prepare(img)
    fields = {"key": API_KEY, "method": "post", "json": 1}
    if case_sensitive:
        fields["regsense"] = 1
    if digits_only:
        fields["numeric"] = 1
    sub = _call("POST", "in.php", data=fields, files={"file": (f"captcha.{ext}", data)})
    if sub.get("status") != 1:
        raise SolveError(sub.get("request"))
    task_id = sub["request"]

    time.sleep(5)                            # the docs suggest 5 s before the first poll
    deadline, backoff = time.time() + 120, 5
    while time.time() < deadline:
        try:
            res = _call("GET", "res.php", params={
                "key": API_KEY, "action": "get", "id": task_id, "json": 1})
        except requests.RequestException:
            res = {"request": "ERROR_SERVER_ERROR"}
        if res.get("status") == 1:
            return res["request"]            # the text in the image, e.g. "fadc5"
        code = res.get("request")
        if code == "CAPCHA_NOT_READY":
            backoff = 5
            time.sleep(5)
        elif code in TRANSIENT:
            time.sleep(backoff)
            backoff = min(backoff * 2, 30)
        else:
            raise SolveError(code or "empty error from res.php; check the image you sent")
    raise SolveError("timed out after 120 s")

Save it as image_solver.py. prepare() exists because of two real-world inputs: WebP images, which the API doesn't take, and element screenshots on high-DPI screens, which can be well over 100 KB as PNG. In my tests, scaled-up PNGs of 150 to 200 KB came out under 50 KB on the first quality step, and the re-encoded JPEG got the same answer as the original image (xl2xl for both).

Step 3: the whole flow with requests

This loads the form, grabs the hidden fields (CSRF tokens live there), fetches the CAPTCHA once, solves it, and submits, all on one requests.Session. Add pip install beautifulsoup4, then fill in the four constants from DevTools.

import base64
from urllib.parse import urljoin
import requests
from bs4 import BeautifulSoup
from image_solver import solve_image, SolveError

PAGE_URL = "https://example.com/signup"     # the page with the form
CAPTCHA_IMG = "img#captcha"                 # CSS selector for the captcha <img>
CAPTCHA_FIELD = "captcha"                   # name of the input the answer goes in
REJECTED = "incorrect captcha"              # text the site shows on a wrong answer
UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0 Safari/537.36"


def load_form(s: requests.Session) -> tuple[str, dict, bytes]:
    soup = BeautifulSoup(s.get(PAGE_URL, timeout=30).text, "html.parser")
    form = soup.find("form")
    action = urljoin(PAGE_URL, form.get("action") or PAGE_URL)
    fields = {i["name"]: i.get("value", "")              # CSRF token and other hidden inputs
              for i in form.select("input[type=hidden][name]")}
    src = urljoin(PAGE_URL, soup.select_one(CAPTCHA_IMG)["src"])
    if src.startswith("data:image"):
        image = base64.b64decode(src.split(",", 1)[1])  # inline image: nothing to download
    else:
        image = s.get(src, headers={"Referer": PAGE_URL}, timeout=30).content  # ONE fetch
    return action, fields, image


def main() -> None:
    s = requests.Session()
    s.headers["User-Agent"] = UA
    for attempt in range(1, 4):
        action, fields, image = load_form(s)
        try:
            answer = solve_image(image)
        except SolveError as e:
            if str(e) == "ERROR_CAPTCHA_UNSOLVABLE":
                continue                                 # new page, new image
            raise
        print(f"attempt {attempt}: {len(image)} byte image -> {answer!r}")
        fields.update({"email": "me@example.com", CAPTCHA_FIELD: answer})
        r = s.post(action, data=fields, timeout=30)
        if REJECTED not in r.text.lower():
            print(f"accepted: HTTP {r.status_code}")
            return
        print("rejected, loading a fresh captcha")
    raise SystemExit("3 rejections in a row: check the troubleshooting table")


if __name__ == "__main__":
    main()

Here's a real run against the local test form from Step 1, solved by the live API:

attempt 1: 8081 byte image -> '9x90x'
rejected, loading a fresh captcha
attempt 2: 9347 byte image -> 'zrf9y'
accepted: HTTP 200

The retry isn't optional. The test images come from Python's captcha library, whose characters overlap heavily, and wrong reads were common on them: in another run all three attempts were rejected and the script stopped. On a wrong answer it reloads the page for a new image. Never resubmit a different answer for the same picture; most sites have already discarded that code.

The same thing in Playwright

When the page needs a browser, screenshot the element and keep everything else in the page:

from playwright.sync_api import sync_playwright
from image_solver import solve_image

with sync_playwright() as p:
    page = p.chromium.launch().new_page()
    for attempt in range(1, 4):
        page.goto("https://example.com/signup")              # fresh page, fresh image
        png = page.locator("img#captcha").screenshot()      # the pixels on screen, no second fetch
        page.fill("input[name=email]", "me@example.com")
        page.fill("input[name=captcha]", solve_image(png))
        page.click("button[type=submit]")
        page.wait_for_load_state()
        if "incorrect captcha" not in page.content().lower():
            print(f"accepted on attempt {attempt}")
            break

Node.js version

Node 18+ ships fetch, FormData and Blob, so there are no dependencies:

const API = "https://ocr.captchaai.com";
const KEY = "YOUR_API_KEY";
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const TRANSIENT = new Set(["ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"]);

function extOf(buf) {
  if (buf[0] === 0x89 && buf[1] === 0x50) return "png";
  if (buf[0] === 0xff && buf[1] === 0xd8) return "jpg";
  if (buf.subarray(0, 4).toString() === "GIF8") return "gif";
  throw new Error("convert the image to PNG, JPG or GIF first");
}

export async function solveImage(buf, { caseSensitive = false, digitsOnly = false } = {}) {
  if (buf.length < 100 || buf.length > 100 * 1024) {
    throw new Error(`image is ${buf.length} bytes; the API takes 100 B to 100 KB`);
  }
  const form = new FormData();
  form.set("key", KEY);
  form.set("method", "post");
  form.set("json", "1");
  if (caseSensitive) form.set("regsense", "1");
  if (digitsOnly) form.set("numeric", "1");
  form.set("file", new Blob([buf]), `captcha.${extOf(buf)}`);

  const sub = await fetch(`${API}/in.php`, { method: "POST", body: form }).then((r) => r.json());
  if (sub.status !== 1) throw new Error(`submit: ${sub.request}`);

  await sleep(5000);
  const deadline = Date.now() + 120000;
  let backoff = 5000;
  while (Date.now() < deadline) {
    const q = new URLSearchParams({ key: KEY, action: "get", id: sub.request, json: "1" });
    const text = await fetch(`${API}/res.php?${q}`).then((r) => r.text())
      .catch(() => JSON.stringify({ request: "ERROR_SERVER_ERROR" }));  // network error: retry
    let res;
    try {
      res = JSON.parse(text);
    } catch {
      throw new Error(`poll: non-JSON reply: ${text.slice(0, 80)}`);
    }
    if (res.status === 1) return res.request;
    if (res.request === "CAPCHA_NOT_READY") {
      backoff = 5000;
      await sleep(5000);
    } else if (TRANSIENT.has(res.request)) {
      await sleep(backoff);
      backoff = Math.min(backoff * 2, 30000);
    } else {
      throw new Error(`poll: ${res.request || "empty error; check the image you sent"}`);
    }
  }
  throw new Error("timed out after 120 s");
}

// Usage with Playwright: screenshot the element instead of downloading it again
// const png = await page.locator("img#captcha").screenshot();
// await page.fill("input[name=captcha]", await solveImage(png));

Why a correct-looking answer still gets rejected

Symptom	Likely cause	Fix
Rejected every time, answer looks right	Image fetched twice, or with a different session	One session; one fetch, or an element screenshot
`403` or "session expired" on submit	Missing CSRF/hidden field, or the cookie jar changed	Post every hidden input from the same `<form>`
Right letters, wrong case	Site is case-sensitive	Pass `case_sensitive=True` (`regsense=1`)
Letters where only digits belong	Digits-only CAPTCHA	Pass `digits_only=True` (`numeric=1`)
`non-JSON reply from res.php`	The server couldn't use the upload: a fragment under 100 bytes, or WebP sent as-is. `in.php` accepted both in my tests	Check the response's `Content-Type` before solving; `prepare()` rejects fragments and converts WebP
A short nonsense answer (`'7de'` for a noisy 250 KB PNG)	Full-page or high-DPI screenshot over the documented 100 KB, which the server didn't reject	Screenshot the element only; `prepare()` re-encodes under 100 KB
`ERROR_CAPTCHA_UNSOLVABLE`	That picture couldn't be read	Load a fresh image and try again

The first two rows are the same kind of failure as a Turnstile token that works in the browser but 403s from requests: the answer is fine, but the session around it changed between issue and use.

FAQ

What's the difference between an image CAPTCHA solver and an OCR library? An OCR library like Tesseract runs on your machine and is tuned for printed documents. A solver API is built for distorted CAPTCHA text, at the cost of a network round trip and a few seconds of polling. Many pipelines try local OCR first and fall back to the API on a rejection.

Can I send base64 instead of a file upload? Yes. Use method=base64 with the image in a body field instead of method=post with file. The size and format limits are the same.

Does this solve "select all images with traffic lights"? Not with this call. That's a grid challenge, which takes the image plus the instruction text and returns tile numbers; it's covered in the Grid Image guide.

I already have 2Captcha image-solving code. What changes? The in.php/res.php shape is the same, so it's mostly the base URL. I covered that swap in migrating solver code off 2Captcha.

I'm Bassem, and I run CaptchaAI, the API behind ocr.captchaai.com in the code above. If you want to run these scripts against your own form, claim a free thread: 1 thread for 30 days, no card. The Normal Captcha guide has the full parameter and error list.

Invisible reCAPTCHA v2: find the sitekey, solve it with invisible=1 and submit the token (Python and Node)

Bassem Shahin — Mon, 12 Oct 2026 13:00:00 +0000

Invisible reCAPTCHA v2 is the version with no "I'm not a robot" box. The page shows only the small "protected by reCAPTCHA" badge, and the check runs when you click submit (or when the site calls grecaptcha.execute()). If it passes, reCAPTCHA puts a token in the form's g-recaptcha-response field and calls the site's callback. To automate a form like that you need three things: the sitekey (the 40-character key that starts with 6L), a solver request with invisible=1 next to the usual method=userrecaptcha, and the right place to put the token. On a plain HTML form that place is a POST field, so you often don't need a browser at all.

This post walks through all three with code you can run against Google's public invisible demo: a Python finder that reads the sitekey and the form from the HTML, a Playwright check for widgets that only exist after JavaScript runs, and a solve-and-submit script in Python and in Node.

How to tell an invisible widget from a checkbox or v3

An invisible v2 widget is declared in one of four ways. The first three are in the HTML; the last is in a script.

Markup	Example
a `div` with `data-size="invisible"`, run by `grecaptcha.execute()`	`<div class="g-recaptcha" data-sitekey="6Lc..." data-size="invisible" data-callback="onSubmit">`
the `g-recaptcha` class on the submit button	`<button class="g-recaptcha" data-sitekey="6Lc..." data-callback="onSubmit">`
a `div` bound to a button by id	`<div class="g-recaptcha" data-sitekey="6Lc..." data-bind="submit-btn" data-callback="onSuccess">`
explicit rendering	`grecaptcha.render("box", { sitekey: "6Lc...", size: "invisible", callback: onToken })`

Google's two public demos use the second and third forms, and neither one ever writes the word "invisible". That's why searching the page for invisible misses half the real widgets.

The thing most often mistaken for invisible v2 is reCAPTCHA v3. It also has no checkbox and shows the same badge. The difference is in the script tag and the call: v3 loads api.js?render=<sitekey> and asks for a token with grecaptcha.execute(sitekey, {action: "login"}). v3 needs version=v3 and an action, not invisible=1. If you're unsure which one you have, this comparison of v2, v3 and Enterprise has a detector for all of them. This post stays with invisible v2.

Step 1: find the sitekey and the form in the HTML

When the widget is in the HTML, you need no browser to find it. This finder uses only the standard library. For each widget it returns the sitekey, whether it's invisible, the callback name, and the form it protects: the URL it submits to, the method, and the fields a browser would send with it (disabled inputs and unchecked boxes left out, as a browser does).

"""find_invisible.py: find reCAPTCHA v2 widgets in a page's HTML and the form each one protects."""
import re
from html.parser import HTMLParser
from urllib.parse import urljoin

RENDER = re.compile(r"grecaptcha\.render\(\s*[^,]+,\s*\{([^}]*)\}", re.S)
OPT = r"""['"]?{0}['"]?\s*:\s*['"]([^'"]+)['"]"""


class WidgetFinder(HTMLParser):
    def __init__(self):
        super().__init__()
        self.forms, self.widgets, self.scripts = [], [], []
        self._form = None
        self._in_script = False

    def handle_starttag(self, tag, attrs):
        a = dict(attrs)
        if tag == "form":
            self._form = {"action": a.get("action") or "", "method": (a.get("method") or "get").lower(),
                          "id": a.get("id"), "fields": {}}
            self.forms.append(self._form)
        elif tag in ("input", "textarea", "select") and self._form is not None:
            if a.get("name") and "disabled" not in a and a.get("type") not in ("submit", "button", "image"):
                if a.get("type") in ("checkbox", "radio") and "checked" not in a:
                    return
                self._form["fields"][a["name"]] = a.get("value") or ""
        elif tag == "script":
            self._in_script = True
        if "data-sitekey" in a:
            invisible = (a.get("data-size") == "invisible"   # div + grecaptcha.execute()
                         or tag == "button"                    # <button class="g-recaptcha">
                         or "data-bind" in a)                  # div bound to a button id
            self.widgets.append({"sitekey": a["data-sitekey"], "invisible": invisible,
                                 "callback": a.get("data-callback"), "form": self._form})

    def handle_endtag(self, tag):
        if tag == "form":
            self._form = None
        elif tag == "script":
            self._in_script = False

    def handle_data(self, data):
        if self._in_script:
            self.scripts.append(data)


def find_widgets(html, page_url):
    p = WidgetFinder()
    p.feed(html)
    widgets = p.widgets
    # explicit rendering: grecaptcha.render(el, {sitekey: "...", size: "invisible"})
    for body in RENDER.findall("\n".join(p.scripts)):
        key = re.search(OPT.format("sitekey"), body)
        if key:
            size = re.search(OPT.format("size"), body)
            widgets.append({"sitekey": key.group(1), "callback": None, "form": None,
                            "invisible": bool(size and size.group(1) == "invisible")})
    for w in widgets:
        form = w.pop("form") or (p.forms[0] if len(p.forms) == 1 else None)
        w["submit_url"] = urljoin(page_url, form["action"]) if form else None
        w["method"] = form["method"] if form else None
        w["fields"] = dict(form["fields"]) if form else {}
    return widgets

On the two demos and a checkbox page for comparison:

import requests
from find_invisible import find_widgets

for url in ["https://www.google.com/recaptcha/api2/demo?invisible=true",
            "https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php",
            "https://recaptcha-demo.appspot.com/recaptcha-v2-checkbox.php"]:
    html = requests.get(url, timeout=30).text
    print(find_widgets(html, url))

[{'sitekey': '6LfP0CITAAAAAHq9FOgCo7v_fb0-pmmH9VW3ziFs', 'invisible': True, 'callback': 'onSuccess', 'submit_url': 'https://www.google.com/recaptcha/api2/demo?invisible=true', 'method': 'post', 'fields': {}}]
[{'sitekey': '6LcmDCcUAAAAAL5QmnMvDFnfPTP4iCUYRk2MwC0-', 'invisible': True, 'callback': 'onSubmit', 'submit_url': 'https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php', 'method': 'post', 'fields': {'ex-a': 'foo', 'ex-b': 'bar'}}]
[{'sitekey': '6LfW6wATAAAAAHLqO2pb8bDBahxlMxNdo9g947u9', 'invisible': False, 'callback': None, 'submit_url': 'https://recaptcha-demo.appspot.com/recaptcha-v2-checkbox.php', 'method': 'post', 'fields': {'ex-a': 'foo', 'ex-b': 'bar'}}]

The Google demo's fields is empty because every input on that form is disabled, so a browser sends only the token. A widget created by grecaptcha.render() has no element to attach it to a form, so the finder falls back to the page's only form when there is just one. With several forms, check by hand.

When the HTML has no sitekey: read the anchor iframe

Single-page apps and bundled sites often create the widget from JavaScript that a regex won't find. Let the page render, then read the widget's anchor iframe. Every rendered key gets one, and its URL carries the sitekey as k= and the widget type as size=:

// anchors.mjs: list every reCAPTCHA widget a page actually rendered. npm i playwright
import { chromium } from "playwright";

const url = process.argv[2];
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto(url, { waitUntil: "load" });
await page.waitForSelector('iframe[src*="/anchor"]', { state: "attached", timeout: 15_000 });
await page.waitForTimeout(2_000); // give late widgets a moment

for (const frame of page.frames()) {
  const u = new URL(frame.url());
  if (!u.pathname.endsWith("/anchor")) continue;
  console.log({
    sitekey: u.searchParams.get("k"),
    size: u.searchParams.get("size"), // "invisible" for v2 invisible AND for v3
    enterprise: u.pathname.includes("/enterprise/"),
  });
}
await browser.close();

$ node anchors.mjs "https://www.google.com/recaptcha/api2/demo?invisible=true"
{
  sitekey: '6LfP0CITAAAAAHq9FOgCo7v_fb0-pmmH9VW3ziFs',
  size: 'invisible',
  enterprise: false
}

$ node anchors.mjs https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php
{
  sitekey: '6LcmDCcUAAAAAL5QmnMvDFnfPTP4iCUYRk2MwC0-',
  size: 'invisible',
  enterprise: true
}
{
  sitekey: '6Le80pApAAAAANg24CMbhL_U2PASCW_JUnq5jPys',
  size: 'invisible',
  enterprise: true
}

The second run shows two traps. First, that demo loads a second key, an Enterprise score key that isn't part of the form, and it reports size: 'invisible' too, because v3 and score keys always do. Pick the key the form's widget uses (the one in the HTML, or the one tied to the submit request), not the first anchor you see.

Second, the form's own key came back with enterprise: true, yet the page loads it through the classic api.js. In an earlier run of the same script the same day, the same key was served from /recaptcha/api2/anchor and reported false. A page that also loads enterprise.js can do that. So use the anchor path as a hint only: decide Enterprise by whether the key is used through enterprise.js and grecaptcha.enterprise, which the comparison post covers. For this demo the answer is a standard invisible v2 key.

Step 2: solve it with invisible=1

The solve is a normal reCAPTCHA v2 task on the 2Captcha-style in.php/res.php API:

Parameter	Value
`method`	`userrecaptcha`
`googlekey`	the sitekey from step 1
`pageurl`	the full URL of the page that shows the widget, not the form's action URL
`invisible`	`1`. The docs mark it as required for invisible widgets: without it the solve can fail
`json`	`1`, so the answers are JSON

You get a task id back, wait about 15 seconds, then poll res.php every 5 seconds until the token arrives. Server errors are retried with a backoff capped at 30 seconds. Account and input errors (ERROR_WRONG_USER_KEY, ERROR_ZERO_BALANCE, ERROR_PAGEURL) stop at once, because retrying won't fix them.

Step 3: post the token with the form

This script ties the steps together. It loads the page, takes the first invisible widget, solves it and posts the form's fields plus g-recaptcha-response to the form's action, which is what the browser would have done after the callback fired. Prerequisites: Python 3.9+ and pip install requests, with find_invisible.py in the same folder.

# solve_invisible.py: solve an invisible reCAPTCHA v2 and post the form, no browser.
# Needs: pip install requests   (find_invisible.py from above sits next to it)
import os
import re
import sys
import time

import requests

from find_invisible import find_widgets

API = "https://ocr.captchaai.com"  # 2Captcha-style in.php / res.php
API_KEY = os.environ.get("CAPTCHAAI_KEY", "YOUR_API_KEY")
UA = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
      "(KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36")
TRANSIENT = {"ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"}


def call(path, **kw):
    """One API call; network errors and non-JSON replies come back as a transient error."""
    try:
        return requests.request(timeout=30, url=f"{API}/{path}", **kw).json()
    except (requests.RequestException, ValueError) as exc:
        return {"status": 0, "request": "ERROR_SERVER_ERROR", "detail": str(exc)}


def solve_invisible(sitekey, pageurl, timeout=180):
    if API_KEY in ("", "YOUR_API_KEY"):
        raise SystemExit("Set CAPTCHAAI_KEY to your API key first")
    if not re.fullmatch(r"6L[\w-]{38}", sitekey):
        raise SystemExit(f"{sitekey!r} doesn't look like a reCAPTCHA sitekey")
    params = {"key": API_KEY, "method": "userrecaptcha", "googlekey": sitekey,
              "pageurl": pageurl, "invisible": 1, "json": 1}
    for attempt in range(3):
        r = call("in.php", method="POST", data=params)
        if r["status"] == 1:
            break
        if r["request"] not in TRANSIENT:  # ERROR_WRONG_USER_KEY, ERROR_ZERO_BALANCE,
            raise RuntimeError(f"in.php: {r['request']}")  # ERROR_PAGEURL, ...
        time.sleep(5 * 2 ** attempt)
    else:
        raise RuntimeError("in.php: server errors on 3 tries")

    task_id, started, wait = r["request"], time.time(), 5
    time.sleep(15)  # nothing is ready before ~15 s
    while time.time() - started < timeout:
        r = call("res.php", method="GET", params={
            "key": API_KEY, "action": "get", "id": task_id, "json": 1})
        if r["status"] == 1:
            return r["request"]
        if r["request"] in TRANSIENT:
            wait = min(wait * 2, 30)  # back off on server trouble
        elif r["request"] == "CAPCHA_NOT_READY":
            wait = 5
        else:  # ERROR_CAPTCHA_UNSOLVABLE, ERROR_WRONG_CAPTCHA_ID, ...
            raise RuntimeError(f"res.php: {r['request']}")
        time.sleep(wait)
    raise TimeoutError(f"task {task_id} not solved in {timeout}s")


if __name__ == "__main__":
    page = sys.argv[1] if len(sys.argv) > 1 else \
        "https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php"
    if not page.startswith(("http://", "https://")):
        sys.exit("Pass the full URL of the page that shows the widget")
    s = requests.Session()
    s.headers["User-Agent"] = UA
    widgets = [w for w in find_widgets(s.get(page, timeout=30).text, page) if w["invisible"]]
    if not widgets:
        sys.exit("No invisible widget in the HTML: it is a checkbox, or a script renders it (see below).")
    w = widgets[0]
    print("widget:", {k: w[k] for k in ("sitekey", "callback", "submit_url")})

    token = sys.argv[2] if len(sys.argv) > 2 else solve_invisible(w["sitekey"], page)
    print("token:", token[:20] + "...")
    # what the browser would have posted: the form's fields plus the token
    data = {**w["fields"], "g-recaptcha-response": token}
    if w["method"] == "post":
        reply = s.post(w["submit_url"], data=data, timeout=30)
    else:  # a GET form sends its fields in the query string
        reply = s.get(w["submit_url"], params=data, timeout=30)
    print("demo backend:", re.findall(r"'(success|hostname)' => '?([\w.-]+)", reply.text),
          re.findall(r"\d+ => '([a-z-]+)'", reply.text))

The demo backend prints the result of its own siteverify call, so the last line shows Google's verdict. With a solved token:

$ CAPTCHAAI_KEY=... python solve_invisible.py
widget: {'sitekey': '6LcmDCcUAAAAAL5QmnMvDFnfPTP4iCUYRk2MwC0-', 'callback': 'onSubmit', 'submit_url': 'https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php'}
token: 0cAFcWeA4ZrE7MhWVePD...
demo backend: [('success', 'true'), ('hostname', 'recaptcha-demo.appspot.com')] []

You can test the form half without spending a solve: an optional second argument is used as the token. A fake token shows what a rejection looks like:

$ python solve_invisible.py https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php 03AFcWeA-not-a-real-token
widget: {'sitekey': '6LcmDCcUAAAAAL5QmnMvDFnfPTP4iCUYRk2MwC0-', 'callback': 'onSubmit', 'submit_url': 'https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php'}
token: 03AFcWeA-not-a-real-...
demo backend: [('success', 'false'), ('hostname', 'NULL')] ['invalid-input-response', 'hostname-mismatch']

On your own target there's no siteverify printout. Use the site's own success signal instead: a redirect, a session cookie, or the absence of its "please complete the captcha" message.

The same flow in Node.js

Node 18+ has fetch built in, so this needs no packages. The finder is a regex version of the Python one: good for triage on server-rendered pages, and the anchor check above covers the rest.

// solve-invisible.mjs: the same flow in Node 18+ (built-in fetch, no packages)
const API = "https://ocr.captchaai.com";
const API_KEY = process.env.CAPTCHAAI_KEY ?? "YOUR_API_KEY";
const UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " +
  "(KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36";
const TRANSIENT = new Set(["ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"]);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const attr = (tag, name) => tag.match(new RegExp(`\\s${name}=["']([^"']*)["']`, "i"))?.[1];

async function call(path, init = {}) {
  try {
    const res = await fetch(`${API}/${path}`, { ...init, signal: AbortSignal.timeout(30_000) });
    return await res.json();
  } catch (err) { // network error or non-JSON reply: treat as transient
    return { status: 0, request: "ERROR_SERVER_ERROR", detail: err.message };
  }
}

// Regex triage, like find_invisible.py: invisible widgets declared in the HTML
function findInvisible(html, pageUrl) {
  const out = [];
  for (const m of html.matchAll(/<(\w+)\b[^>]*\bdata-sitekey=[^>]*>/gi)) {
    const tag = m[0];
    const invisible = attr(tag, "data-size") === "invisible" ||
      m[1].toLowerCase() === "button" || /\bdata-bind=/i.test(tag);
    if (!invisible) continue;
    const start = html.lastIndexOf("<form", m.index);
    const formTag = start >= 0 ? html.slice(start, html.indexOf(">", start) + 1) : "";
    const formBody = start >= 0 ? html.slice(start, html.indexOf("</form>", start)) : "";
    const fields = {};
    for (const [input] of formBody.matchAll(/<input\b[^>]*>/gi)) {
      const name = attr(input, "name");
      if (name && !/\bdisabled\b/i.test(input) && !/type=["'](submit|button)/i.test(input))
        fields[name] = attr(input, "value") ?? "";
    }
    out.push({
      sitekey: attr(tag, "data-sitekey"),
      callback: attr(tag, "data-callback") ?? null,
      submitUrl: new URL(attr(formTag, "action") || pageUrl, pageUrl).href,
      method: (attr(formTag, "method") || "get").toUpperCase(),
      fields,
    });
  }
  return out;
}

async function solveInvisible(sitekey, pageurl, timeoutMs = 180_000) {
  if (!API_KEY || API_KEY === "YOUR_API_KEY") throw new Error("Set CAPTCHAAI_KEY first");
  if (!/^6L[\w-]{38}$/.test(sitekey)) throw new Error(`${sitekey} isn't a reCAPTCHA sitekey`);
  const params = new URLSearchParams({ key: API_KEY, method: "userrecaptcha",
    googlekey: sitekey, pageurl, invisible: "1", json: "1" });
  let r;
  for (let attempt = 0; ; attempt++) {
    r = await call("in.php", { method: "POST", body: params });
    if (r.status === 1) break;
    if (!TRANSIENT.has(r.request) || attempt === 2) throw new Error(`in.php: ${r.request}`);
    await sleep(5_000 * 2 ** attempt);
  }
  const id = r.request, started = Date.now();
  let wait = 5_000;
  await sleep(15_000);
  while (Date.now() - started < timeoutMs) {
    r = await call(`res.php?${new URLSearchParams({ key: API_KEY, action: "get", id, json: "1" })}`);
    if (r.status === 1) return r.request;
    if (TRANSIENT.has(r.request)) wait = Math.min(wait * 2, 30_000);
    else if (r.request === "CAPCHA_NOT_READY") wait = 5_000;
    else throw new Error(`res.php: ${r.request}`); // ERROR_CAPTCHA_UNSOLVABLE, ...
    await sleep(wait);
  }
  throw new Error(`task ${id} not solved in ${timeoutMs / 1000}s`);
}

const page = process.argv[2] ?? "https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php";
if (!/^https?:\/\//.test(page)) throw new Error("Pass the full URL of the page that shows the widget");
const html = await (await fetch(page, { headers: { "User-Agent": UA } })).text();
const [w] = findInvisible(html, page);
if (!w) throw new Error("No invisible widget in the HTML: a checkbox, or rendered by a script");
console.log("widget:", { sitekey: w.sitekey, callback: w.callback, submitUrl: w.submitUrl });

const token = process.argv[3] ?? await solveInvisible(w.sitekey, page);
const data = new URLSearchParams({ ...w.fields, "g-recaptcha-response": token });
const reply = w.method === "POST"
  ? await fetch(w.submitUrl, { method: "POST", headers: { "User-Agent": UA }, body: data })
  : await fetch(`${w.submitUrl.split("?")[0]}?${data}`, { headers: { "User-Agent": UA } });
const body = await reply.text();
console.log("demo backend:", [...body.matchAll(/'(success|hostname)' => '?([\w.-]+)/g)].map((m) => [m[1], m[2]]),
  [...body.matchAll(/\d+ => '([a-z-]+)'/g)].map((m) => m[1]));

$ node solve-invisible.mjs https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php 03AFcWeA-not-a-real-token
widget: {
  sitekey: '6LcmDCcUAAAAAL5QmnMvDFnfPTP4iCUYRk2MwC0-',
  callback: 'onSubmit',
  submitUrl: 'https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php'
}
demo backend: [ [ 'success', 'false' ], [ 'hostname', 'NULL' ] ] [ 'invalid-input-response', 'hostname-mismatch' ]

With CAPTCHAAI_KEY set and no second argument, it solves and posts a real token like the Python script:

$ CAPTCHAAI_KEY=... node solve-invisible.mjs
widget: {
  sitekey: '6LcmDCcUAAAAAL5QmnMvDFnfPTP4iCUYRk2MwC0-',
  callback: 'onSubmit',
  submitUrl: 'https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php'
}
demo backend: [ [ 'success', 'true' ], [ 'hostname', 'recaptcha-demo.appspot.com' ] ] []

When the token doesn't go in a form field

Posting g-recaptcha-response works when the callback only submits the form, as on both demos. Three other setups are common:

The callback does the work. It enables a button, stores the token in React state or calls an API. In a browser you have to call the callback yourself after you fill the textarea. This post on reCAPTCHA v2 callbacks shows how to find it, even when the bundle is minified, and trigger it from Playwright or Selenium.
The token travels in an XHR. Open DevTools, submit once by hand and look at the request in the Network tab. The token may sit in a JSON body under a name like captcha or recaptchaToken. Send it in that request, with the same headers and cookies.
The site runs execute() on page load. It fetches a token as soon as the page opens and sends it later. Tokens are valid for two minutes and can be verified only once, so solve right before you send the request rather than when you load the page.

Troubleshooting

invalid-input-response with a real token. Most often the token expired or was already used. Next, check that pageurl is the page that shows the widget and that you solved the key the form uses, not the extra key the second anchor run found.
The solve works but the site still says "verify you are human". The token went to the wrong place. Compare your request with the browser's request in the Network tab: field name, endpoint and cookies.
ERROR_PAGEURL or ERROR_WRONG_SITEKEY from in.php. The page URL is missing or not a full URL, or the sitekey is wrong. Copy both from the page again.
ERROR_CAPTCHA_UNSOLVABLE from res.php. Submit once more. If it repeats, check the variant: a v3 key sent as invisible v2 won't produce a token the site accepts.
The finder returns nothing on a page that clearly has the badge. Either the widget is rendered by a script (use the anchor check) or it's v3 (api.js?render=...).

FAQ

What is invisible reCAPTCHA v2?
A reCAPTCHA v2 widget with no checkbox. It runs when the user submits the form or the site calls grecaptcha.execute(). Most visitors never see a challenge, and a suspicious one gets the image puzzle. Like the checkbox, it hands the site a token in g-recaptcha-response to verify server-side.

What's the difference between invisible reCAPTCHA v2 and v3?
Invisible v2 returns a pass/fail token and can still show an image challenge. v3 never shows a challenge. It returns a token the site's backend scores from 0.0 to 1.0, tied to an action name. They need different solver parameters: invisible=1 for v2, version=v3 plus the action for v3.

Is invisible=1 really needed?
Yes. The API docs mark it as required for invisible widgets and say a solve without it can fail. Send invisible=1 whenever the widget is invisible, and leave it out for checkbox widgets.

What does "this site key is not enabled for the invisible captcha" mean?
Google shows that error when a key registered for the checkbox type is rendered with size: "invisible". The site chooses the key type when it registers the key, so treat that key as a checkbox key and leave out invisible=1.

Disclosure: I work on CaptchaAI, whose endpoint the examples use. It solves reCAPTCHA v2 Invisible with the parameters above, and the reCAPTCHA v2 Invisible guide lists them. To run the scripts against your own page, claim a free thread: 1 thread for 30 days, no card.

— Bassem

GeeTest v3: why your slider automation keeps failing the second check

Bassem Shahin — Thu, 08 Oct 2026 13:00:00 +0000

Most people meet GeeTest v3 as "the slider one" — drag the puzzle piece into the gap, done. So the
obvious automation is: find the gap with OpenCV, compute the offset, move the slider that many
pixels. That works exactly once, in a demo, and then fails everywhere real.

The reason is that the gap offset is not what GeeTest is checking. It checks how you got
there, and then it checks again on the server.

The actual flow

GeeTest v3 is a three-step handshake, and the puzzle you see is only step two.

Registration. The site's backend asks GeeTest for a challenge and gets back a gt (a public site key, stable per site) and a challenge (a one-time nonce). The page hands both to the GeeTest JS.
The challenge. The JS renders the slider, and while you drag it, records a trajectory — a time-series of positions, plus timing, acceleration, and a few environment signals. On release, it posts that trajectory to GeeTest's ajax/validate endpoint.
Validation. If GeeTest accepts, it returns three values: geetest_challenge, geetest_validate, geetest_seccode. Those go to the site's own backend, which calls GeeTest server-side to confirm them.

Step 3 is where most automation dies. You can get the slider visually correct and still be rejected,
because the trajectory you produced was not plausible, and the seccode never validates.

Why a pixel-perfect slide still fails

The offset is necessary but nowhere near sufficient. What gets you flagged:

Linear motion. A human accelerates, overshoots slightly, corrects, and settles. A for loop moving 3px per tick produces a straight line with constant velocity — which is the single clearest tell there is.
Zero jitter on the Y axis. Real drags wander vertically by a few pixels. Machine drags don't move on Y at all.
Impossible timing. A 200px drag completed in 40ms, or one that starts the instant the puzzle renders with no reaction delay.
A stale challenge. The nonce is single-use and short-lived. Reusing one across retries — or taking 90 seconds of OpenCV work before submitting — invalidates it.
Environment mismatch. navigator.webdriver, a headless UA, or a TLS fingerprint that disagrees with the browser you claim to be, all feed into the same decision.

There is also a v3 vs v4 trap worth naming: GeeTest v4 is a different product with a different
handshake (captcha_id rather than gt/challenge, and a different validation payload). Guides
and libraries for one do not work against the other, and a lot of confusion online comes from
people mixing them. Check which one you're facing before you write any code —
if you see gt= and challenge= in the network tab, you're on v3.

Detecting which one you're on

import re, requests

html = requests.get(target_url, timeout=20).text

# v3 registers with a gt + challenge pair
v3 = re.search(r'["\']?gt["\']?\s*[:=]\s*["\']([a-f0-9]{32})', html)
# v4 uses captchaId / captcha_id
v4 = re.search(r'captcha[_]?[Ii]d["\']?\s*[:=]\s*["\']([a-f0-9]{32})', html)

print("GeeTest v3" if v3 else "GeeTest v4" if v4 else "neither / dynamically loaded")

If neither matches, the parameters are being fetched by JS at runtime — open the network tab and
look for the request to api.geetest.com/gettype.php or register.php; the gt is in there.

Handling it in automation

Two approaches actually work, and they fail for different reasons.

Drive a real browser and produce a real trajectory. Feasible, and the right call if you're
already running Playwright with a good fingerprint. The work is in the motion model: ease-in/ease-out
velocity, a small overshoot and correction near the target, a few pixels of Y drift, and a human
reaction delay before the drag starts. Budget for tuning — a motion curve that passes today can
start failing after a GeeTest model update, and you find out through a rising failure rate rather
than an error message.

Send the parameters to a solving service and get the three values back. You extract gt and
challenge, submit them, and receive geetest_challenge / geetest_validate / geetest_seccode
to post to the site's backend yourself. This is what we do at CaptchaAI —
the API is 2Captcha-compatible, so if you already have solver code the change is the base URL:

import json, requests, time

API   = "https://ocr.captchaai.com"
KEY   = "YOUR_KEY"

r = requests.get(f"{API}/in.php", params={
    "key": KEY,
    "method": "geetest",
    "gt": gt,                      # public site key, usually static
    "challenge": challenge,        # one-time nonce — grab it fresh, see below
    "pageurl": target_url,
    "json": 1,
}, timeout=30).json()

task = r["request"]

time.sleep(15)                     # geetest takes a while; polling sooner just burns requests
while True:
    res = requests.get(f"{API}/res.php", params={
        "key": KEY, "action": "get", "id": task, "json": 1
    }, timeout=30).json()
    if "seccode" in res:           # solved: challenge / validate / seccode come back top-level
        sol = res
        break
    if res.get("status") == 1:     # the same three values, if your client gets them wrapped
        sol = res["request"]
        sol = json.loads(sol) if isinstance(sol, str) else sol
        break
    if res.get("request") != "CAPCHA_NOT_READY":
        raise RuntimeError(res.get("request"))
    time.sleep(5)

# Note the rename: the API returns short keys, but the SITE expects them prefixed.
payload = {
    "geetest_challenge": sol["challenge"],
    "geetest_validate":  sol["validate"],
    "geetest_seccode":   sol["seccode"],
}

The detail people miss: fetch the challenge immediately before you submit. If your code
registers the challenge, then does other work, then solves, the nonce may already be dead and
you'll get a valid-looking seccode that the site rejects — which reads like a solver problem and
isn't one.

The failure mode to watch

GeeTest doesn't usually tell you why it refused. You get a rejection and a fresh puzzle. So the
signal you actually need is first-attempt success rate over time, not per-request errors. A
slow slide from 95% to 80% over a week is the shape of a model update meeting a motion curve that
used to pass — and if you're only looking at exceptions, you won't see it until it's severe.

Whichever route you take, log the rate. It's the only early warning either approach gives you.

I'm Bassem, founder of CaptchaAI. We solve GeeTest v3, reCAPTCHA v2 and
v3 including Enterprise, Cloudflare Turnstile and Challenge, and image/grid types. We do **not*
solve GeeTest v4, hCaptcha or FunCaptcha — worth saying plainly, because picking a solver on a
capability it doesn't have wastes a week. If Cloudflare is your other wall, I've written up
why cf_clearance keeps expiring
and how to solve Turnstile in Playwright.
To run the GeeTest v3 call above against your own target, start with
one free thread for 30 days, no card needed.*

GeeTest v3 solver in Python: from gt and challenge to a seccode the site accepts

Bassem Shahin — Mon, 05 Oct 2026 13:00:00 +0000

A GeeTest v3 solver in Python takes four HTTP calls, and only the middle two talk to the solver. You get a fresh gt and challenge from the site's register endpoint. You send them to a solving API. You poll until it returns challenge, validate and seccode. Then you POST those three back to the site in the same session that fetched the challenge.

When the solve works but the site still says no, the bug is almost always in the first or last call. Below are all four with runnable code, plus a check to run first: v3 and v4 are not interchangeable.

The setup

You're automating a lookup form you're allowed to automate, and a GeeTest v3 slider sits in front of the submit button. The goal is plain requests, no browser, ending in an accepted form POST.

First, confirm it's GeeTest v3 and not v4

Most GeeTest confusion online comes from mixing guides for the two versions. They take different parameters and hand the site different values. Open DevTools, reload, and compare:

Signal	GeeTest v3	GeeTest v4
Page init	`initGeetest({gt, challenge, ...})`	`initGeetest4({captchaId: ...})`
What identifies it	`gt` (32 hex chars) plus a one-time `challenge`	`captcha_id` only
Network	`api.geetest.com` or `api-na.geetest.com` (`gettype.php`, `get.php`, `ajax.php`)	`gcaptcha4.geetest.com`, `static.geetest.com/v4/gt4.js`
What the site receives	`geetest_challenge`, `geetest_validate`, `geetest_seccode`	`lot_number`, `captcha_output`, `pass_token`, `gen_time`

If you'd rather script it, this loads the page once and classifies it by network traffic (needs pip install playwright and playwright install chromium):

import re
from playwright.sync_api import sync_playwright

def geetest_version(url: str) -> str:
    seen = []
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page()
        page.on("request", lambda req: seen.append(req.url) if "geetest.com" in req.url else None)
        page.goto(url, wait_until="networkidle")
        browser.close()
    if any("gcaptcha4.geetest.com" in u or "/v4/" in u for u in seen):
        return "GeeTest v4 (captcha_id): this guide does not apply"
    if any(re.search(r"/(gettype|get|ajax)\.php", u) for u in seen):
        return "GeeTest v3 (gt + challenge)"
    return "no GeeTest traffic yet: it may only load when you click submit"

Everything below is v3 only. It's the same habit I recommend for reCAPTCHA: identify the variant before writing solver code, since a request for the wrong variant fails in confusing ways.

Step 1: find the register endpoint

On v3 the challenge is not in the HTML. The site's backend mints it: it calls GeeTest's register.php, signs the result with its private key, and hands the page JSON shaped like this:

{"success": 1, "gt": "f1ab2cd4e5f6a7b8c9d0e1f2a3b4c5d6", "challenge": "6f3b2c...", "new_captcha": true}

To find it, filter DevTools' Network tab by Fetch/XHR, reload, and look for a JSON response containing "challenge". It's usually named /register, /geetest/register or /captcha/init, often with a ?t=<timestamp> cache-buster. GeeTest's own demo uses /pc-geetest/register?t=.... Also check whether the page's initGeetest(...) call sets api_server (e.g. api-na.geetest.com); if so, pass it to the solver.

Two rules decide whether the final POST is accepted:

Fresh. Per the API guide linked at the end, a challenge expires after about 10 minutes and becomes invalid once the widget has loaded it. Fetch it right before you solve, and don't let a browser render the widget with it.
Same session. GeeTest's official v3 server SDK demo stores the register status in the server-side session and reads it back when validating. Register with one cookie jar and submit with another, and a site built like that has no record of your challenge.

A GeeTest v3 solver in Python, end to end

Prerequisites: Python 3.9+, pip install requests, your API key, the page and register URLs, and the form's POST URL (visible in DevTools after one manual solve). The request parameters follow the documented in.php/res.php flow (method=geetest, gt, challenge, pageurl, plus optional api_server and userAgent).

import json
import time
import requests

API_KEY = "YOUR_API_KEY"
API = "https://ocr.captchaai.com"
PAGE_URL = "https://example.com/lookup"                 # page that shows the slider
REGISTER_URL = "https://example.com/geetest/register"   # found in Step 1
SUBMIT_URL = "https://example.com/lookup"               # where the form POSTs
API_SERVER = None        # e.g. "api-na.geetest.com" if initGeetest() sets api_server
UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0 Safari/537.36"
TRANSIENT = {"ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"}


class SolveError(Exception):
    pass


def fresh_pair(s: requests.Session) -> dict:
    r = s.get(REGISTER_URL, params={"t": int(time.time() * 1000)}, timeout=30)
    r.raise_for_status()
    data = r.json()
    if not data.get("success"):
        raise SolveError("register returned success=0 (fallback mode), not a normal challenge")
    return data


def solve(gt: str, challenge: str) -> dict:
    params = {"key": API_KEY, "method": "geetest", "gt": gt, "challenge": challenge,
              "pageurl": PAGE_URL, "userAgent": UA, "json": 1}
    if API_SERVER:
        params["api_server"] = API_SERVER
    sub = requests.get(f"{API}/in.php", params=params, timeout=30).json()
    if sub.get("status") != 1:
        raise SolveError(sub.get("request"))
    task_id = sub["request"]
    print(f"task {task_id} submitted, polling...")

    time.sleep(15)                      # the docs suggest 15-20 s before the first poll
    deadline = time.time() + 120
    while time.time() < deadline:
        try:
            res = requests.get(f"{API}/res.php", timeout=30, params={
                "key": API_KEY, "action": "get", "id": task_id, "json": 1}).json()
        except requests.RequestException:
            time.sleep(10)
            continue
        if "seccode" in res:            # solved: {"challenge", "validate", "seccode"}
            return res
        if res.get("status") == 1:      # same three values wrapped in "request"
            sol = res["request"]
            return json.loads(sol) if isinstance(sol, str) else sol
        code = res.get("request")
        if code in TRANSIENT:
            time.sleep(10)
        elif code == "CAPCHA_NOT_READY":
            time.sleep(5)
        else:
            raise SolveError(code)
    raise SolveError("timed out after 120 s")


def main() -> None:
    s = requests.Session()
    s.headers["User-Agent"] = UA
    s.get(PAGE_URL, timeout=30)         # pick up the cookies a normal visit sets
    for attempt in (1, 2):
        pair = fresh_pair(s)            # fresh challenge, same session
        print(f"register: gt={pair['gt'][:8]}... challenge={pair['challenge'][:8]}...")
        try:
            sol = solve(pair["gt"], pair["challenge"])
        except SolveError as e:
            if str(e) == "ERROR_CAPTCHA_UNSOLVABLE" and attempt == 1:
                continue                # never resubmit an old challenge
            raise
        print(f"solved: seccode={sol['seccode'][:12]}...")
        form = {"q": "example"}         # the form's own fields
        form.update({
            "geetest_challenge": sol["challenge"],   # the RETURNED challenge
            "geetest_validate": sol["validate"],
            "geetest_seccode": sol["seccode"],
        })
        r = s.post(SUBMIT_URL, data=form, timeout=30)
        print(f"POST {SUBMIT_URL} -> {r.status_code}")
        return


if __name__ == "__main__":
    main()

Expected output:

register: gt=f1ab2cd4... challenge=6f3b2c1e...
task 73919012345 submitted, polling...
solved: seccode=2a9c04b7e1f3...
POST https://example.com/lookup -> 200

Two details in that code matter more than they look:

Use the challenge the solver returns, not the one you sent. It can come back changed, and the site checks the three values as a set.
The API returns short keys; the site expects the geetest_ prefix, and some sites rename fields in their own JS. Solve once by hand with DevTools open and copy the exact names.

The same solve step in Node.js

Node 18+ has fetch built in. Keep the register and submit calls on one cookie-keeping client, for the same session reason.

const API = "https://ocr.captchaai.com";
const KEY = "YOUR_API_KEY";
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function solveGeetestV3({ gt, challenge, pageurl, userAgent }) {
  const q = new URLSearchParams({ key: KEY, method: "geetest", gt, challenge, pageurl, json: "1" });
  if (userAgent) q.set("userAgent", userAgent);
  const sub = await fetch(`${API}/in.php?${q}`).then((r) => r.json());
  if (sub.status !== 1) throw new Error(`submit: ${sub.request}`);

  await sleep(15000);
  const deadline = Date.now() + 120000;
  while (Date.now() < deadline) {
    const res = await fetch(`${API}/res.php?` + new URLSearchParams({
      key: KEY, action: "get", id: sub.request, json: "1",
    })).then((r) => r.json());
    if (res.seccode) return res; // solved: { challenge, validate, seccode }
    if (res.status === 1) {
      return typeof res.request === "string" ? JSON.parse(res.request) : res.request;
    }
    if (res.request !== "CAPCHA_NOT_READY") throw new Error(`poll: ${res.request}`);
    await sleep(5000);
  }
  throw new Error("timed out after 120 s");
}

Why a correct seccode still gets rejected

Sites behind GeeTest v3 rarely say why they rejected you. Check these in order:

Symptom	Likely cause	Fix
Rejected every time	Register and submit used different sessions	One `requests.Session` for both
Rejected after a slow run	Challenge expired or the widget already loaded it	Register right before solving; never render the widget for it
Rejected despite a fresh pair	Original `challenge` sent instead of the returned one	Send `sol["challenge"]`
Field missing (400/422)	Wrong names or a JS rename	Copy names from a manual solve
`success: 0` from register	The site fell back to offline mode	Log it; retry register later
`ERROR_CAPTCHA_UNSOLVABLE`	The solve failed for this challenge	New register call, then resubmit

The first two rows are the same kind of failure as a Turnstile token that works in the browser but 403s from requests. In both cases the solved values are fine; the context around them changed between issue and use.

FAQ

Does this work for GeeTest v4? No. v4 is a different flow (captcha_id in, four different values out), and none of the code above applies.

Do I need a browser? Not for the solve. If the register endpoint needs a token only the page's JS can produce, call it through Playwright's page.request, which shares the page's cookies, and pass the pair to the same solve().

I already have 2Captcha-style GeeTest v3 code. What changes? The in.php/res.php shape is the same, so it's mostly the base URL. I covered that swap in migrating solver code off 2Captcha.

I'm Bassem, and I run CaptchaAI, the API behind ocr.captchaai.com in the code above. It solves GeeTest v3 and not v4, and I'd rather say so here than have you find out in testing. If you want to run this script against your own target, claim a free thread: 1 thread for 30 days, no card. The GeeTest v3 guide has the full parameter and error list.

reCAPTCHA v2 callback: how to find the callback function and trigger it after injecting a token

Bassem Shahin — Thu, 01 Oct 2026 13:00:00 +0000

Your solver returned a valid reCAPTCHA v2 token. You put it into the hidden g-recaptcha-response textarea, and nothing happens. The submit button stays disabled, or the form posts and the server replies "please complete the captcha". The usual cause is a reCAPTCHA v2 callback: the site doesn't watch the textarea, it waits for reCAPTCHA to call one of its own JavaScript functions with the token. This post shows how to find the callback function (it hides in one of three places) and how to trigger it from Playwright or Selenium after you inject the token.

Why filling g-recaptcha-response does nothing

When a real user passes the widget, reCAPTCHA does two things:

It writes the token into the g-recaptcha-response textarea. Each widget on the page has its own.
If the site registered a callback, it calls that function with the token.

Injecting the token only does step 1. On a plain form that posts the textarea, that's enough. On a callback page, step 2 is where the site's logic lives. Typical callbacks:

submit the form: function onSubmit(token) { document.getElementById("demo-form").submit(); }, the pattern from Google's invisible reCAPTCHA docs
enable a submit button that was disabled until now
send the token to an API with fetch()
store the token in React or Vue component state, so the form posts from state and never reads the textarea

Nothing fires those for you. Invisible reCAPTCHA v2 nearly always works this way: there is no checkbox, so the callback is how the site learns the check has finished.

Two limits apply whatever you do. A token is valid for two minutes and can be verified only once. Solve right before you trigger, and never reuse a token.

How to find the reCAPTCHA callback function

Open DevTools on the page with the widget. There are three places to look, from quickest to most reliable.

1. The data-callback attribute. Declarative widgets name the function in the HTML:

<div class="g-recaptcha" data-sitekey="6Lc..." data-callback="onCaptchaDone"></div>

<button class="g-recaptcha" data-sitekey="6Lc..." data-callback="onSubmit">Log in</button>

The value is the name of a global function, so the call is window.onCaptchaDone(token). Search the Elements panel for data-callback.

2. The callback option of grecaptcha.render(). Sites that load api.js?onload=...&render=explicit create the widget in code:

grecaptcha.render("captcha-box", {
  sitekey: "6Lc...",
  callback: (token) => submitLogin(token),
});

Search all scripts (Ctrl+Shift+F in the Sources panel) for grecaptcha.render. If the callback is an anonymous function inside a bundled module, you can't call it by name. The third method handles that.

3. The ___grecaptcha_cfg.clients object. reCAPTCHA keeps every rendered widget's settings in this global. Each client holds a parameters object with sitekey, size and callback, usually two levels down, under minified names that change between reCAPTCHA releases (for example ___grecaptcha_cfg.clients[0].aa.l.callback). So don't hard-code the path. Walk the object and stop at anything that has a sitekey. The callback you find there is either the function itself or the global name from data-callback, so this works for all three setups, including React wrappers.

Save this as find-callbacks.js:

() => {
  const cfg = window.___grecaptcha_cfg;
  const found = [];
  if (!cfg || !cfg.clients) return found;
  const seen = new Set();
  const walk = (obj, keys, depth) => {
    if (!obj || typeof obj !== "object" || depth > 4 || seen.has(obj)) return;
    if (obj instanceof Node || obj === window) return; // skip DOM nodes
    seen.add(obj);
    if (typeof obj.sitekey === "string") {
      const cb = obj.callback;
      found.push({
        keys, // path from clients to the params object
        sitekey: obj.sitekey,
        // "invisible" means send invisible=1; button-bound widgets store no size
        size: obj.size || (obj.bind ? "invisible" : null),
        callbackType: typeof cb, // "function", "string" or "undefined"
        callbackName: typeof cb === "string" ? cb : (cb && cb.name) || null,
      });
      return;
    }
    for (const [k, v] of Object.entries(obj)) walk(v, [...keys, k], depth + 1);
  };
  for (const [id, client] of Object.entries(cfg.clients)) walk(client, [id], 0);
  return found;
}

You can paste it into the console as (...)() to check a page by hand. A callbackType of "undefined" means that widget has no callback: fill the textarea and submit the form yourself.

reCAPTCHA v3 (api.js?render=KEY) registers a client here too, with an id of 100000 or higher, size: "invisible" and no callback, so it can pass for an invisible v2 widget. If a widget turns up that you didn't expect, check which reCAPTCHA variant you're dealing with first, because v3 needs a different request.

Get the token from the solver

A callback page uses the same solver request as any reCAPTCHA v2 widget: method=userrecaptcha, the sitekey as googlekey, and the pageurl where the widget loaded. Add invisible=1 for invisible widgets. It is required, and a token solved without it can be rejected. This is the 2Captcha-compatible in.php/res.php API, so if you're coming from 2Captcha the parameters are identical (the migration post has the diff).

Prerequisites: Python 3.9+, pip install requests, plus playwright or selenium. Save as solver.py next to the two JS files:

import time
from pathlib import Path

import requests

API_KEY = "YOUR_API_KEY"
FIND_JS = Path("find-callbacks.js").read_text()
TRIGGER_JS = Path("trigger-callback.js").read_text()
TRANSIENT = {"ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"}


def solve_recaptcha_v2(sitekey, pageurl, invisible=False, timeout=120):
    if not API_KEY or API_KEY == "YOUR_API_KEY":
        raise SystemExit("Set API_KEY to your key first")
    params = {"key": API_KEY, "method": "userrecaptcha",
              "googlekey": sitekey, "pageurl": pageurl, "json": 1}
    if invisible:
        params["invisible"] = 1
    r = requests.get("https://ocr.captchaai.com/in.php", params=params, timeout=30).json()
    if r["status"] != 1:  # e.g. ERROR_WRONG_SITEKEY, ERROR_ZERO_BALANCE
        raise RuntimeError(f"in.php: {r['request']}")
    task_id = r["request"]
    time.sleep(15)
    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get("https://ocr.captchaai.com/res.php", timeout=30, params={
            "key": API_KEY, "action": "get", "id": task_id, "json": 1}).json()
        if r["status"] == 1:
            return r["request"]
        if r["request"] in TRANSIENT:
            time.sleep(10)
            continue
        if r["request"] != "CAPCHA_NOT_READY":  # e.g. ERROR_CAPTCHA_UNSOLVABLE
            raise RuntimeError(f"res.php: {r['request']}")
        time.sleep(5)
    raise TimeoutError(f"task {task_id} not solved in {timeout}s")


def pick_widget(widgets):
    if not widgets:
        raise RuntimeError("no reCAPTCHA widget found on this page")
    return next((w for w in widgets if w["callbackType"] != "undefined"), widgets[0])

Trigger the callback after injecting the token

The trigger does both steps a real solve does, in the same order. Filling the textarea covers callbacks that call form.submit(), since that post carries the textarea. Save as trigger-callback.js:

([token, keys]) => {
  document.querySelectorAll('textarea[name="g-recaptcha-response"]')
    .forEach((t) => { t.value = token; });
  // look the callback up again: functions can't travel back to Python
  const params = keys.reduce((o, k) => (o ? o[k] : undefined), window.___grecaptcha_cfg.clients);
  let cb = params && params.callback;
  if (typeof cb === "string") cb = cb.split(".").reduce((o, k) => (o ? o[k] : undefined), window);
  if (typeof cb !== "function") return "no-callback";
  setTimeout(() => cb(token), 0); // async, so evaluate() returns before any navigation
  return "called";
}

Playwright:

from playwright.sync_api import sync_playwright
from solver import FIND_JS, TRIGGER_JS, pick_widget, solve_recaptcha_v2

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com/login")
    page.wait_for_function("() => Object.keys(window.___grecaptcha_cfg?.clients || {}).length > 0")
    w = pick_widget(page.evaluate(FIND_JS))
    print("widget:", w)
    token = solve_recaptcha_v2(w["sitekey"], page.url, invisible=w["size"] == "invisible")
    outcome = page.evaluate(TRIGGER_JS, [token, w["keys"]])
    print("trigger:", outcome)
    if outcome == "no-callback":
        page.click("form [type=submit]")
    page.wait_for_url("**/dashboard", timeout=15000)  # your success signal
    browser.close()

Selenium uses the same two JS files:

from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from solver import FIND_JS, TRIGGER_JS, pick_widget, solve_recaptcha_v2

driver = webdriver.Chrome()
driver.get("https://example.com/login")
WebDriverWait(driver, 30).until(lambda d: d.execute_script(
    "return Object.keys(window.___grecaptcha_cfg?.clients || {}).length > 0"))
w = pick_widget(driver.execute_script(f"return ({FIND_JS})();"))
token = solve_recaptcha_v2(w["sitekey"], driver.current_url, invisible=w["size"] == "invisible")
outcome = driver.execute_script(f"return ({TRIGGER_JS})(arguments[0]);", [token, w["keys"]])
print("trigger:", outcome)
if outcome == "no-callback":
    driver.find_element(By.CSS_SELECTOR, "form [type=submit]").click()

Expected output on a callback page:

widget: {'keys': ['0', 'aa', 'l'], 'sitekey': '6Lc...', 'size': 'invisible', 'callbackType': 'function', 'callbackName': 'onSubmit'}
trigger: called

The minified keys will differ from aa and l, which is the point of walking the object.

Troubleshooting

The form posts twice, or the server says the token was already used. The callback submitted the form and you clicked submit as well. Only click when the trigger returns no-callback.
A widget bound to a button reports size: null. reCAPTCHA stores no size for a g-recaptcha class on a button or for data-bind, so the finder treats a set bind as invisible. If a widget you know is invisible still shows null, pass invisible=True yourself.
The submit handler checks grecaptcha.getResponse(). That call reads the widget's g-recaptcha-response textarea, so the fill in the trigger already covers it. There's no need to override it.
The callback ran but the server rejects the token. Check that pageurl is the page that rendered the widget (not the form's action URL), that you solved the right widget's sitekey, that invisible widgets got invisible=1, and that fewer than two minutes passed.
ERROR_CAPTCHA_UNSOLVABLE from res.php. Resubmit once. If it repeats, re-check the sitekey and the variant.

Cloudflare Turnstile has the same trap, since many sites put a data-callback on the cf-turnstile div. The Playwright walkthrough for Turnstile covers that token flow.

FAQ

What is a reCAPTCHA v2 callback? A JavaScript function the site registers, through data-callback or grecaptcha.render(), that reCAPTCHA calls with the token when the check passes. Callback sites submit the form or call their API from inside it.

Do callback pages need a different solver method? No. The token is an ordinary reCAPTCHA v2 token from method=userrecaptcha. Only what you do with it changes. Invisible widgets still need invisible=1.

How do I find the callback when the site's JavaScript is minified? Don't look for a name. Walk ___grecaptcha_cfg.clients to the object that has a sitekey and use its callback property, which holds the function even when it has no usable name.

Disclosure: I work on CaptchaAI, whose endpoint the examples use. It solves reCAPTCHA v2, including invisible and callback widgets, and the reCAPTCHA v2 Callback guide lists the parameters. To run the code above against your own page, claim a free thread: 1 thread for 30 days, no card.

— Bassem

reCAPTCHA v3 solver in Python: find the action, send version=v3, handle Enterprise

Bassem Shahin — Tue, 29 Sep 2026 11:24:28 +0000

When a reCAPTCHA v3 solver in Python returns a token and the site still says no, check the action first. I ran the script below against Google's own v3 demo page while writing this. With the page's real action, the demo's backend accepted the token. With action=login, the token still scored 0.9 and was rejected with action-mismatch.

So a v3 solve comes down to four values: the sitekey, the page URL, version=v3, and the exact action string the page passes to grecaptcha.execute(). Enterprise adds enterprise=1 and gives you back a User-Agent you have to reuse. Below: how to find each one, a solver you can run as-is, and why a valid token still gets turned away.

First, confirm it really is v3

Look at the script tag. api.js?render=SITEKEY means v3. enterprise.js?render=SITEKEY means v3 Enterprise, and the page's calls go through grecaptcha.enterprise.*. A visible checkbox, or a g-recaptcha div with data-size="invisible", means v2. That takes different parameters (invisible=1 for the invisible kind, no action). The full checklist is in reCAPTCHA v2 vs v3 vs Enterprise: how to tell which one you're fighting.

The sitekey is the render= value, with one trap: a page can load more than one. Google's v3 demo loads a second key through enterprise.js, next to the key its execute() call uses. Match the key to the execute() call that fires on your form, not to the first render= you find.

How to find the reCAPTCHA v3 action

The action is a free-form string the site chooses: login, submit, homepage, examples/v3scores. Google returns it to the site's backend next to the score, and a backend can reject any token whose action doesn't match what it expects. That's exactly what happened in my login run. Three ways to find it, quickest first.

1. Search the loaded scripts. In Chrome DevTools, Ctrl+Shift+F (Cmd+Option+F on a Mac) searches every script on the page. Search for execute(. On Google's demo it's in plain sight:

grecaptcha.execute('6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9', {action: 'examples/v3scores'})

2. Log it at runtime. Minified bundles can turn the action into a variable, so the search only finds {action: e}. Paste this into the console once the page has loaded, then submit the form:

// Logs the sitekey and action of every execute() call, v3 and Enterprise.
for (const api of [window.grecaptcha, window.grecaptcha?.enterprise]) {
  if (!api || typeof api.execute !== "function") continue;
  const original = api.execute;
  api.execute = function (sitekey, options) {
    console.log("sitekey:", sitekey, "| action:", options?.action);
    return original.apply(this, arguments);
  };
}
// on submit, prints e.g.:  sitekey: 6Lc... | action: submit

3. Set a breakpoint. If the site calls execute() while the page loads, the console hook arrives too late. Open the file from step 1 in the Sources panel (press {} to pretty-print minified code), click the line number of the execute( call, reload, and read action in the Scope pane when it pauses.

Don't skip this when it gets fiddly. The API falls back to verify if action is empty, and verify is rarely what a site checks. Treat it as required.

The reCAPTCHA v3 solver in Python

This talks to a 2Captcha-compatible in.php/res.php API. API_BASE points at the one I run (details at the end); 2Captcha-style services use the same parameter names. It needs pip install requests and an API key in CAPTCHA_API_KEY.

# solve_v3.py: reCAPTCHA v3 / v3 Enterprise solver. Needs: pip install requests
import os
import time

import requests

API_BASE = "https://ocr.captchaai.com"  # a 2Captcha-compatible in.php / res.php API
API_KEY = os.environ.get("CAPTCHA_API_KEY", "YOUR_API_KEY")
RETRYABLE = {"ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"}


def submit(sitekey, pageurl, action, enterprise=False):
    if API_KEY in ("", "YOUR_API_KEY"):
        raise SystemExit("Set the CAPTCHA_API_KEY environment variable first")
    if not (sitekey and pageurl and action):
        raise ValueError("sitekey, pageurl and action are all required for v3")
    data = {"key": API_KEY, "method": "userrecaptcha", "version": "v3",
            "googlekey": sitekey, "pageurl": pageurl, "action": action, "json": 1}
    if enterprise:
        data["enterprise"] = 1
    for attempt in range(3):
        r = requests.post(f"{API_BASE}/in.php", data=data, timeout=30).json()
        if r["status"] == 1:
            return r["request"]  # the task id
        if r["request"] not in RETRYABLE:  # bad key, zero balance, bad sitekey...
            raise RuntimeError(f"submit rejected: {r['request']}")
        time.sleep(10 * (attempt + 1))
    raise RuntimeError("submit kept failing with server errors")


def solve_v3(sitekey, pageurl, action, enterprise=False, timeout=120):
    task_id = submit(sitekey, pageurl, action, enterprise)
    time.sleep(15)  # the docs advise a 15-20 s wait
    deadline, delay, attempt = time.time() + timeout, 5, 0
    while time.time() < deadline:
        attempt += 1
        try:
            r = requests.get(f"{API_BASE}/res.php", timeout=30, params={
                "key": API_KEY, "action": "get", "id": task_id, "json": 1}).json()
        except requests.RequestException as exc:  # network blip: back off, keep polling
            print(f"poll {attempt}: {exc}")
            delay = min(delay * 2, 30)
        else:
            if r["status"] == 1:
                # Enterprise answers also carry the solver's User-Agent: keep it
                return r.get("request") or r.get("result"), r.get("user_agent")
            print(f"poll {attempt}: {r['request']}")
            if r["request"] == "CAPCHA_NOT_READY":
                delay = 5
            elif r["request"] in RETRYABLE:
                delay = min(delay * 2, 30)
            else:  # ERROR_CAPTCHA_UNSOLVABLE, ERROR_WRONG_CAPTCHA_ID, ...
                raise RuntimeError(f"solve failed: {r['request']}")
        time.sleep(delay)
    raise TimeoutError(f"task {task_id} not solved within {timeout}s")

A few details that matter:

Enterprise is the same call plus enterprise=True. Its answer comes back as result and user_agent instead of request (I checked the raw response on 2026-09-28), which is why the return line reads both.
You can't request a score. min_score is not a parameter. The site's backend sets the threshold, and the token clears it or doesn't.
recaptcha.net pages. If the script loads from www.recaptcha.net rather than www.google.com, add "domain": "recaptcha.net" to data.
Polling. CAPCHA_NOT_READY is normal: wait 5 seconds and ask again. Server errors back off up to 30 seconds, and anything else stops the loop, because retrying a bad sitekey only wastes time.

Send the token the way the page does

With v3 the token doesn't ride along in the form automatically, the way v2's g-recaptcha-response field does. The page's own JavaScript puts it wherever it wants: a form field, a JSON key, a query string. So submit the form once by hand with the Network tab open and copy that request exactly. Then be quick about it. Google's docs say a token expires two minutes after it's issued and can be verified only once, so solve right before the request and never reuse a token.

Append this to solve_v3.py. It makes the same request the demo page's JavaScript makes with its token:

if __name__ == "__main__":
    # Google's public v3 demo: a safe target for trying this out
    PAGE = "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php"
    ACTION = "examples/v3scores"
    token, user_agent = solve_v3(
        sitekey="6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9", pageurl=PAGE, action=ACTION)
    print("token:", token[:24] + "...", "| user agent:", user_agent)

    session = requests.Session()
    if user_agent:  # Enterprise tokens are tied to the solver's User-Agent
        session.headers["User-Agent"] = user_agent
    # the same request the demo page's own JavaScript makes with its token
    check = session.get("https://recaptcha-demo.appspot.com/recaptcha-v3-verify.php",
                        params={"action": ACTION, "token": token}, timeout=30)
    print(check.json())

My run on 2026-09-28 (about 17 seconds end to end):

token: 0cAFcWeA7U2MiF6_97mK6g5l... | user agent: None
{'success': True, 'hostname': 'recaptcha-demo.appspot.com', 'challenge_ts': '2026-09-28T11:43:26Z', 'apk_package_name': None, 'score': 0.9, 'action': 'examples/v3scores', 'error-codes': []}

And the run where I solved with action="login" and submitted to the same page:

{'success': False, 'hostname': 'recaptcha-demo.appspot.com', 'challenge_ts': '2026-09-28T11:41:38Z', 'apk_package_name': None, 'score': 0.9, 'action': 'login', 'error-codes': ['action-mismatch']}

Same score, rejected, and action-mismatch is the only error code. The action alone sank it. (That's a demo page, so treat 0.9 as one observation, not a promise. Your target's own threshold decides.)

Why a valid token still gets rejected

Action mismatch. As above. Copy the string exactly, including case and slashes.
Expired or reused. Google reports this as timeout-or-duplicate. One solve per request, submitted inside two minutes.
User-Agent mismatch on Enterprise. Send the user_agent that came back with the token.
Wrong type. v3 parameters won't help against a v2 invisible widget. When in.php can tell the key belongs to another reCAPTCHA type, it answers ERROR_WRONG_KEY_TYPE.
The site's threshold. If the action, timing and User-Agent are right and it still fails, the backend wanted a higher score, or an Enterprise site is applying its own rules on hostname, IP or session. That's a reputation problem, covered in why your reCAPTCHA v3 score is low.

And the errors the API itself returns:

Code	Meaning	Fix
`ERROR_WRONG_USER_KEY`, `ERROR_KEY_DOES_NOT_EXIST`	bad API key	copy it again from the dashboard
`ERROR_ZERO_BALANCE`	not enough balance or threads	top up, or lower concurrency
`ERROR_PAGEURL`, `ERROR_WRONG_SITEKEY`	page URL missing, sitekey malformed	re-extract both from the page
`CAPCHA_NOT_READY`	still solving	poll again in 5 seconds
`ERROR_CAPTCHA_UNSOLVABLE`	the solve failed	check type and parameters, resubmit

FAQ

Can I ask for a 0.9 score? No. There is no min_score parameter. The site decides what score it accepts.

Is v3 Enterprise a different method? No. It's the same method=userrecaptcha and version=v3, plus enterprise=1. Read result and user_agent from the answer.

Do I need a proxy? No, leave it out. Our proxy guide lists reCAPTCHA v3 as not supported with proxies, so send v3 and v3 Enterprise tasks without proxy/proxytype.

I'm Bassem, founder of CaptchaAI, the ocr.captchaai.com endpoint in the script. It solves reCAPTCHA v3 and v3 Enterprise through the 2Captcha-compatible API, so an existing 2Captcha client moves over by changing the base URL. Enterprise sites can still reject a valid token on their own rules, so test against your real target before you build on it. A free thread is enough for that: one thread for 30 days, no card. The full parameter list is in the v3 Enterprise docs.

Build vs buy: what running your own CAPTCHA-solving stack actually costs

Bassem Shahin — Sat, 11 Jul 2026 20:46:18 +0000

Build vs buy: what running your own CAPTCHA-solving stack actually costs

Every team that automates against the public web eventually hits the same fork: a scraper, a monitoring job, a QA suite, or an agent starts tripping CAPTCHAs, and someone asks "should we just build our own solver instead of paying a service?"

It's a fair question. The per-solve prices you see quoted (a dollar or three per 1,000) feel like something you could undercut with a weekend of code. Sometimes you can. But the sticker price of a solving service isn't really what you're comparing against — you're comparing against the fully-loaded cost of owning the problem forever. That second number is the one people underestimate, so let me lay it out honestly, including when building genuinely is the right call.

What "build your own" actually means

The naive version — "I'll just click the checkbox with Playwright" — works in a demo and falls over in production. A real self-hosted solving stack for the modern challenge types (reCAPTCHA v2/v3/Enterprise, Cloudflare Turnstile) is not one script. It's a system:

Challenge detection — reliably identifying which captcha is on a page and extracting its sitekey/parameters, across sites that change markup.
Token generation — a fleet of real (or hardened headless) browsers to actually produce valid tokens, because modern challenges are behavior- and signal-based, not image puzzles you can OCR.
Fingerprint + proxy management — reCAPTCHA v3 and Turnstile score the session (IP reputation, TLS/JA3, canvas, behavior), so you need residential/mobile egress and consistent fingerprints or your tokens come back low-score and useless.
Concurrency + queueing — running N solves in parallel without melting your box or getting the whole IP range flagged.
Retry/scoring logic — detecting a failed or low-score solve and retrying intelligently.
Monitoring — success-rate dashboards, alerting when a vendor changes something and your success rate quietly craters overnight.

None of that is exotic. All of it is real engineering, and — this is the part that bites — none of it is done once.

The hidden line item: the maintenance treadmill

Here's the cost that never shows up in the weekend-project estimate. The anti-bot vendors ship changes continuously. Google rotates reCAPTCHA internals; Cloudflare iterates Turnstile; challenge parameters and scoring shift. Every one of those can silently drop your homegrown success rate, and you find out from a downstream failure, not a changelog.

So "build your own" isn't a one-time build cost — it's a standing on-call commitment. Someone on your team now owns keeping a captcha solver alive, and that someone is pulled off your actual product every time the arms race moves.

Rough, honest math for a modest in-house stack:

Line item	Realistic cost
Initial build (detection + browser fleet + proxy glue + retries)	~1–3 engineer-months
Proxies (residential/mobile egress for valid scores)	ongoing $$ — often more than the solver would've cost
Infra (browser fleet, queue, monitoring)	ongoing $
Maintenance (the treadmill — reacting to vendor changes)	~0.2–0.5 of an engineer, indefinitely
Opportunity cost	whatever that engineer isn't building on your core product

At a loaded engineering cost, that maintenance fraction alone is often thousands of dollars a month — before proxies and infra. Compare that to a solving subscription that's typically tens to low-hundreds of dollars a month, and the "cheap" homegrown option frequently isn't.

When building actually wins

I'm not going to pretend buying always wins — it doesn't. Build when:

Solving is your product. If you're a proxy vendor, an anti-detect browser, or a scraping platform, captcha handling is core competency and differentiation. Own it.
You have genuinely unique requirements a general service can't meet — an obscure challenge type, an air-gapped environment, strict data-residency rules.
Extreme volume with margin pressure where, at your scale, an in-house team is demonstrably cheaper than any per-use or per-thread pricing — and you can staff the treadmill.

If one of those is you, building is rational. Budget for the maintenance, not just the build.

When buying wins (most teams)

For everyone else — teams where scraping/automation is a means, not the product — buying is almost always the right call, for one reason: you're offloading the treadmill, not just the code. A solving service absorbs every vendor change so your engineers stay on your roadmap. You wire up an API once and stop thinking about it.

And the integration is genuinely small. Most services expose the same three-step flow — submit the sitekey, poll for the token, inject it — and many are 2Captcha-API-compatible, so if you've ever used one you've basically used all of them:

import requests, time

API_KEY = "YOUR_KEY"
BASE = "https://ocr.captchaai.com" # 2Captcha-compatible endpoint

# 1) submit the challenge (reCAPTCHA v2 shown; Turnstile = method="turnstile" + sitekey)
r = requests.get(f"{BASE}/in.php", params={
    "key": API_KEY,
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY_FROM_THE_PAGE",
    "pageurl": "https://target.example/login",
})
task_id = r.text.split("|")[1]

# 2) poll for the token
while True:
    res = requests.get(f"{BASE}/res.php", params={"key": API_KEY, "action": "get", "id": task_id})
    if res.text == "CAPCHA_NOT_READY":
        time.sleep(5); continue
    token = res.text.split("|")[1]
    break

# 3) inject the token into the page and submit

That's the whole integration surface. No browser fleet, no proxy sourcing for score quality, no 2 a.m. page when a vendor ships a change.

How to actually decide

Skip the per-1,000 sticker comparison. Ask three questions instead:

Is captcha solving part of what we sell? If yes, lean build. If no, lean buy.
Can we staff the maintenance treadmill indefinitely? Not the build — the upkeep. If that makes you wince, buy.
What's the fully-loaded in-house number — build + proxies + infra + that 0.2–0.5 engineer forever + opportunity cost — versus a subscription? Run that comparison, not the sticker one.

For most teams the honest answer is: your engineers are worth more on your product than on an arms race you'll never win outright. Buy the boring part, ship your actual thing.

If you want to sanity-check the buy side against your real volume, CaptchaAI's cost calculator lets you plug in your numbers, and there's a trial if you want to compare success rates against your homegrown prototype before deciding. But whichever way you go, decide on the fully-loaded number — not the weekend-project fantasy.

reCAPTCHA Enterprise vs v3 vs v2: how to tell which one a site uses (enterprise.js, execute, invisible)

Bassem Shahin — Tue, 30 Jun 2026 23:17:04 +0000

Short answer: look at which script the page loads and how it asks for a token. api.js with a visible checkbox is reCAPTCHA v2. api.js with no checkbox, bound to a button or to grecaptcha.execute(), is v2 invisible. api.js?render=<sitekey> plus grecaptcha.execute(sitekey, {action}) is v3. enterprise.js, with calls under grecaptcha.enterprise.*, is reCAPTCHA Enterprise. Enterprise is not a fourth kind of challenge. It is Google Cloud's version of the same checkbox, invisible and score keys, and the site checks its tokens through a different backend API.

Getting this right matters because a token made for the wrong variant often comes back from the solver fine, submits fine, and is then rejected by the site's backend with no useful error. Below you'll find the signals side by side, a small Python detector, a Playwright check for what loads at runtime, and the solver parameters for each variant. I ran all of it against Google's own demo pages on 2026-09-29, and the outputs shown are from those runs.

reCAPTCHA v2 vs v3 vs Enterprise at a glance

	Script	What you see	How the token is made	What the site's backend gets
v2 checkbox	`recaptcha/api.js`	"I'm not a robot" box	user ticks it (image grid if risky)	`success`, `hostname`
v2 invisible	`recaptcha/api.js`	no box, only the badge	a bound button or `grecaptcha.execute()`	`success`, `hostname`
v3	`recaptcha/api.js?render=<sitekey>`	the badge only	`grecaptcha.execute(sitekey, {action})`	`success`, `score`, `action`
Enterprise	`recaptcha/enterprise.js`	any of the three above	`grecaptcha.enterprise.execute()` or `.render()`	`tokenProperties`, `riskAnalysis` (score and reasons)

Two things won't help you tell them apart. The sitekey won't: every variant uses a 40-character key that starts with 6L. The "protected by reCAPTCHA" badge won't either, because v2 invisible and v3 both show it. Some sites load the scripts from www.recaptcha.net instead of www.google.com, and the same rules apply.

reCAPTCHA Enterprise vs v3: what is actually different

This is the pair people mix up most. In the browser, an Enterprise score key behaves exactly like v3: there's no widget, just a badge and an execute() call with an action. The differences are these.

Where the key lives. Enterprise is a Google Cloud product. Its keys belong to a Cloud project, and they come in the same flavours as the classic ones: score, checkbox and invisible.
The client script. The page loads enterprise.js instead of api.js, and every call goes through grecaptcha.enterprise, for example grecaptcha.enterprise.execute(sitekey, {action: 'LOGIN'}). Its requests normally go to /recaptcha/enterprise/... rather than /recaptcha/api2/....
How the backend checks the token. Classic v2 and v3 post the token and a secret to https://www.google.com/recaptcha/api/siteverify. Enterprise creates an assessment through the Cloud API instead. The request looks roughly like this (authentication left out):

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments
{"event": {"token": "TOKEN", "siteKey": "6Lc...", "expectedAction": "LOGIN",
           "userAgent": "Mozilla/5.0 ...", "userIpAddress": "203.0.113.7"}}

The answer carries more than a score:

{"tokenProperties": {"valid": true, "action": "LOGIN", "hostname": "example.com"},
 "riskAnalysis": {"score": 0.3, "reasons": ["AUTOMATION"]}}

More signals. reasons can include AUTOMATION, UNEXPECTED_ENVIRONMENT, TOO_MUCH_TRAFFIC or LOW_CONFIDENCE_SCORE. An invalid token also says why in tokenProperties.invalidReason, with values such as EXPIRED, DUPE or MALFORMED. Google documents 11 score levels for Enterprise, but by default a site sees only four: 0.1, 0.3, 0.7 and 0.9.

From the automation side, the browser mechanics are the same as v3 (or v2, for checkbox keys). What changes is how much the backend can compare. The site can pass Google the user agent and IP of the request that carried the token. A token produced in one browser and then submitted with a different user agent can therefore fail. That's why an Enterprise solve comes back with a user_agent you're expected to reuse. It helps to think of Enterprise as v3 with a backend that sees more, not as a harder version of v3.

v2 checkbox vs v2 invisible vs v3: the markup

v2 checkbox is a div with a sitekey, rendered by api.js:

<script src="https://www.google.com/recaptcha/api.js" async defer></script>
<div class="g-recaptcha" data-sitekey="6Lc..."></div>

Some sites use explicit rendering instead: api.js?onload=onloadCallback&render=explicit plus grecaptcha.render(el, {sitekey: '6Lc...'}). That is still v2. Only render= followed by a sitekey means v3.

v2 invisible has three common markups. Google's own two demos use the two that never say "invisible":

<div class="g-recaptcha" data-sitekey="6Lc..." data-size="invisible" data-callback="onSubmit"></div>

<button class="g-recaptcha" data-sitekey="6Lc..." data-callback="onSubmit">Submit</button>

<div class="g-recaptcha" data-sitekey="6Lc..." data-bind="submit-btn" data-callback="onSuccess"></div>

The programmatic version is grecaptcha.render(el, {sitekey: '6Lc...', size: 'invisible'}).

v3 has no element at all, just the keyed include and an execute() call:

<script src="https://www.google.com/recaptcha/api.js?render=6Lc..."></script>
<script>
  grecaptcha.ready(() =>
    grecaptcha.execute('6Lc...', {action: 'submit'}).then(sendTokenToBackend));
</script>

At runtime, every key in use gets an anchor iframe. The iframe URL carries the sitekey as k= and a size=. A checkbox gets normal or compact. A v2 invisible widget gets invisible, and so does v3. So size=invisible alone doesn't separate v2 invisible from v3. The render=<sitekey> include and an execute() call with an action do.

Detect the reCAPTCHA version from the HTML (Python)

This script reads the page and its same-origin scripts. It reports each sitekey with its type, whether it's Enterprise, and the action or callback if it can find them. It's regex-based, so treat it as a triage tool rather than a parser.

# detect_recaptcha.py: which reCAPTCHA does a page use? Needs: pip install requests
import html
import re
import sys
from urllib.parse import parse_qs, urljoin, urlparse

import requests

KEY = r"6L[\w-]{38}"
SCRIPT = re.compile(r"""<script[^>]+src=["']([^"']*/recaptcha/(?:api|enterprise)\.js[^"']*)["']""", re.I)
TAG = re.compile(r"<(\w+)\s([^>]*data-sitekey[^>]*)>", re.I)
ATTR = re.compile(r"""([\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')""")
RENDER = re.compile(r"grecaptcha(\.enterprise)?\.render\([^,]+,\s*\{([^}]*)\}")
EXECUTE = re.compile(rf"""grecaptcha(\.enterprise)?\.execute\(\s*['"]({KEY})['"]\s*,\s*\{{\s*action\s*:\s*['"]([^'"]+)['"]""")


def detect(url):
    ua = {"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/140.0 Safari/537.36"}
    page = requests.get(url, headers=ua, timeout=30).text
    code = page
    for src in re.findall(r"""<script[^>]+src=["']([^"']+\.js[^"']*)["']""", page)[:20]:
        src = urljoin(url, html.unescape(src))           # actions often live in bundles
        if urlparse(src).netloc == urlparse(url).netloc:
            code += requests.get(src, headers=ua, timeout=30).text

    keys, widget_script = {}, None
    for src in SCRIPT.findall(page):
        src = urljoin(url, html.unescape(src))
        enterprise = "/enterprise.js" in src
        render = parse_qs(urlparse(src).query).get("render", [""])[0]
        if re.fullmatch(KEY, render):                     # render=<sitekey>: score mode
            keys[render] = {"type": "v3", "enterprise": enterprise, "action": None}
        else:                                              # no key: this script renders widgets
            widget_script = "enterprise" if enterprise else "standard"

    for tag, attrs in TAG.findall(page):                   # implicit widgets
        a = {m[0].lower(): m[1] or m[2] for m in ATTR.findall(attrs)}
        invisible = a.get("data-size") == "invisible" or "data-bind" in a or tag.lower() == "button"
        keys[a["data-sitekey"]] = {"type": "v2-invisible" if invisible else "v2-checkbox",
                                   "enterprise": widget_script == "enterprise",
                                   "action": a.get("data-action"),
                                   "callback": a.get("data-callback")}
    for ent, body in RENDER.findall(code):                 # explicit grecaptcha.render(...)
        key = re.search(KEY, body)
        if key:
            invisible = re.search(r"""size['"]?\s*:\s*['"]invisible""", body)
            keys[key.group()] = {"type": "v2-invisible" if invisible else "v2-checkbox",
                                 "enterprise": bool(ent) or widget_script == "enterprise",
                                 "action": None}
    for ent, key, action in EXECUTE.findall(code):          # execute(key, {action})
        info = keys.setdefault(key, {"type": "v3", "enterprise": bool(ent)})
        info.update(type="v3", action=action, enterprise=info["enterprise"] or bool(ent))
    return [{"sitekey": key, **info} for key, info in keys.items()]


if __name__ == "__main__":
    for found in detect(sys.argv[1]):
        print(found)

Here it is against four of Google's demo pages:

$ python detect_recaptcha.py https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php
{'sitekey': '6LcmDCcUAAAAAL5QmnMvDFnfPTP4iCUYRk2MwC0-', 'type': 'v2-invisible', 'enterprise': False, 'action': None, 'callback': 'onSubmit'}
$ python detect_recaptcha.py https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php
{'sitekey': '6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9', 'type': 'v3', 'enterprise': False, 'action': 'examples/v3scores'}
$ python detect_recaptcha.py https://www.google.com/recaptcha/api2/demo
{'sitekey': '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-', 'type': 'v2-checkbox', 'enterprise': False, 'action': 'action', 'callback': 'onSuccess'}
$ python detect_recaptcha.py https://recaptcha-demo.appspot.com/recaptcha-v2-checkbox-explicit.php
{'sitekey': '6LfW6wATAAAAAHLqO2pb8bDBahxlMxNdo9g947u9', 'type': 'v2-checkbox', 'enterprise': False, 'action': None}

On a page with enterprise.js?render=KEY and grecaptcha.enterprise.execute(KEY, {action: 'LOGIN'}) in a bundle, it reports 'type': 'v3', 'enterprise': True, 'action': 'LOGIN'.

It has limits. A minified bundle often passes the action as a variable ({action: e}), which a regex can't read. Scripts added by a tag manager aren't in the HTML at all. The runtime check below covers the second gap, and a DevTools breakpoint on the execute( line covers the first.

Confirm what loads at runtime (Playwright)

This one opens the page in a real browser and records every reCAPTCHA script and anchor iframe it requests.

# sniff_recaptcha.py: what does the page load at runtime?
# Needs: pip install playwright && playwright install chromium
import sys
from urllib.parse import parse_qs, urlparse

from playwright.sync_api import sync_playwright


def sniff(url):
    scripts, anchors = set(), []

    def on_request(req):
        u = urlparse(req.url)
        if "/recaptcha/" not in u.path:
            return
        name = u.path.rsplit("/", 1)[-1]
        if name in ("api.js", "enterprise.js"):
            scripts.add(req.url)
        elif name == "anchor":                            # one anchor iframe per key in use
            q = parse_qs(u.query)
            anchors.append({"sitekey": q.get("k", [""])[0],
                            "enterprise": "/enterprise/" in u.path,
                            "size": q.get("size", [""])[0],   # normal, compact or invisible
                            "sa": q.get("sa", [""])[0]})      # the widget's action, if set

    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page()
        page.on("request", on_request)
        page.goto(url, wait_until="networkidle")
        namespace = page.evaluate("""() => ({
            grecaptcha: typeof window.grecaptcha !== 'undefined',
            enterprise: typeof window.grecaptcha?.enterprise !== 'undefined'})""")
        browser.close()
    return scripts, anchors, namespace


if __name__ == "__main__":
    scripts, anchors, namespace = sniff(sys.argv[1])
    for src in sorted(scripts):
        print("script:", src)
    for anchor in anchors:
        print("anchor:", anchor)
    print("namespace:", namespace)

Here's the output on Google's v3 demo:

$ python sniff_recaptcha.py https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php
script: https://www.google.com/recaptcha/api.js?render=6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9
script: https://www.google.com/recaptcha/enterprise.js?render=6Le80pApAAAAANg24CMbhL_U2PASCW_JUnq5jPys
anchor: {'sitekey': '6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9', 'enterprise': False, 'size': 'invisible', 'sa': ''}
anchor: {'sitekey': '6Le80pApAAAAANg24CMbhL_U2PASCW_JUnq5jPys', 'enterprise': True, 'size': 'invisible', 'sa': ''}
namespace: {'grecaptcha': True, 'enterprise': True}

This output shows the trap. Every page on recaptcha-demo.appspot.com loads a second key through enterprise.js at runtime, and that key isn't in the HTML. The v3 form itself uses 6LdKlZEp... through api.js. If you had gone by "the page loads enterprise.js", you would have solved the wrong key in the wrong mode.

The anchor path doesn't settle it either. The checkbox and invisible demos load both scripts too, and in most of my runs on them the form's own classic widget was served from /recaptcha/enterprise/anchor, on the invisible demo as well. Yet the demo's backend accepted a standard solve for the invisible demo's key, with no enterprise=1 (it's the Python run further down).

So here's the rule that holds up. Start from the sitekey the form actually uses. Then follow that key: which script include carries it, and whether grecaptcha or grecaptcha.enterprise calls execute() or render() with it.

Solver parameters for each reCAPTCHA variant

These are the parameter names of the 2Captcha-style in.php/res.php API, which several solving services share. If you're moving an existing client from one provider to another, the switch is mostly a base-URL change.

Variant	Add to `method=userrecaptcha`, `googlekey`, `pageurl`	Token in the `res.php` answer
v2 checkbox	nothing	`request`
v2 invisible	`invisible=1` (required)	`request`
v2 Enterprise	`enterprise=1`, plus `action=` set to the anchor's `sa=` value if it has one	`result`, plus `user_agent`
v3	`version=v3` and `action=` set to the `execute()` action (both required)	`request`
v3 Enterprise	`version=v3`, `action=...` and `enterprise=1`	`result`, plus `user_agent`

There's no parameter for the score you want, and no min_score. The site's backend sets the threshold. What you control is the action, the timing and the user agent.

One client covers all five. It takes an entry from detect_recaptcha.py:

# solve_recaptcha.py: one client for all five variants. Needs: pip install requests
import os
import re
import time

import requests

API = "https://ocr.captchaai.com"                      # any 2Captcha-style in.php/res.php API
API_KEY = os.environ.get("CAPTCHA_API_KEY", "YOUR_API_KEY")
RETRYABLE = {"ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"}


def build_params(info, pageurl):
    """info is one entry from detect_recaptcha.py: type, enterprise, action."""
    p = {"key": API_KEY, "method": "userrecaptcha", "googlekey": info["sitekey"],
         "pageurl": pageurl, "json": 1}
    if info["type"] == "v2-invisible":
        p["invisible"] = 1                               # required for invisible widgets
    if info["type"] == "v3":
        if not info.get("action"):
            raise ValueError("v3 needs the action passed to execute(); find it first")
        p.update(version="v3", action=info["action"])
    if info["enterprise"]:
        p["enterprise"] = 1
        if info["type"] != "v3" and info.get("action"):
            p["action"] = info["action"]                  # v2 Enterprise: the sa= value
    return p


def solve(params, timeout=180):
    if params["key"] in ("", "YOUR_API_KEY"):
        raise SystemExit("set CAPTCHA_API_KEY first")
    for attempt in range(3):                              # submit, retrying server errors
        r = requests.post(f"{API}/in.php", data=params, timeout=30).json()
        if r["status"] == 1:
            break
        if r["request"] not in RETRYABLE:                 # bad key, bad sitekey, no balance
            raise RuntimeError(f"submit failed: {r['request']}")
        time.sleep(10 * (attempt + 1))
    else:
        raise RuntimeError("submit failed after 3 tries")

    task_id, deadline = r["request"], time.time() + timeout
    time.sleep(15)                                        # nothing is ready before ~15 s
    while time.time() < deadline:
        try:
            r = requests.get(f"{API}/res.php", timeout=30, params={
                "key": params["key"], "action": "get", "id": task_id, "json": 1}).json()
        except requests.RequestException as exc:          # network blip: keep polling
            print("poll error:", exc)
        else:
            if r["status"] == 1:
                # standard answers put the token in "request"; Enterprise answers use
                # "result" and add the solver's "user_agent", which you must reuse
                return r.get("result") or r["request"], r.get("user_agent")
            if r["request"] != "CAPCHA_NOT_READY":        # ERROR_CAPTCHA_UNSOLVABLE, ...
                raise RuntimeError(f"solve failed: {r['request']}")
        time.sleep(5)
    raise TimeoutError(f"task {task_id} not solved in {timeout}s")


if __name__ == "__main__":
    # Google's public invisible v2 demo, as detect_recaptcha.py reported it
    PAGE = "https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php"
    info = {"sitekey": "6LcmDCcUAAAAAL5QmnMvDFnfPTP4iCUYRk2MwC0-",
            "type": "v2-invisible", "enterprise": False, "action": None}
    token, user_agent = solve(build_params(info, PAGE))
    print("token:", token[:20] + "...", "| user_agent:", user_agent)

    # submit it the way the page's form does: POST with g-recaptcha-response
    headers = {"User-Agent": user_agent} if user_agent else {}
    reply = requests.post(PAGE, headers=headers, timeout=30,
                          data={"ex-a": "foo", "ex-b": "bar", "g-recaptcha-response": token})
    print("demo backend:", re.findall(r"'(success|hostname)' => '?([\w.-]+)", reply.text))

$ CAPTCHA_API_KEY=... python solve_recaptcha.py
token: 0cAFcWeA4d2qPybEZsxn... | user_agent: None
demo backend: [('success', 'true'), ('hostname', 'recaptcha-demo.appspot.com')]

The same client in Node 18+ (built-in fetch, no packages), pointed at the v3 demo this time:

// solve_recaptcha.mjs: the same client for Node 18+ (built-in fetch, no packages)
const API = "https://ocr.captchaai.com";
const API_KEY = process.env.CAPTCHA_API_KEY ?? "YOUR_API_KEY";
const RETRYABLE = new Set(["ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"]);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const getJson = async (url, init = {}) =>
  (await fetch(url, { ...init, signal: AbortSignal.timeout(30_000) })).json();

function buildParams(info, pageurl) {
  const p = { key: API_KEY, method: "userrecaptcha", googlekey: info.sitekey, pageurl, json: "1" };
  if (info.type === "v2-invisible") p.invisible = "1";
  if (info.type === "v3") {
    if (!info.action) throw new Error("v3 needs the action passed to execute(); find it first");
    Object.assign(p, { version: "v3", action: info.action });
  }
  if (info.enterprise) {
    p.enterprise = "1";
    if (info.type !== "v3" && info.action) p.action = info.action; // v2 Enterprise: sa= value
  }
  return p;
}

async function solve(params, timeoutMs = 180_000) {
  if (!params.key || params.key === "YOUR_API_KEY") throw new Error("set CAPTCHA_API_KEY first");
  let r;
  for (let attempt = 0; ; attempt++) {
    r = await getJson(`${API}/in.php`, { method: "POST", body: new URLSearchParams(params) });
    if (r.status === 1) break;
    if (!RETRYABLE.has(r.request) || attempt === 2) throw new Error(`submit failed: ${r.request}`);
    await sleep(10_000 * (attempt + 1));
  }
  const id = r.request;
  const deadline = Date.now() + timeoutMs;
  await sleep(15_000);
  while (Date.now() < deadline) {
    const q = new URLSearchParams({ key: params.key, action: "get", id, json: "1" });
    try {
      r = await getJson(`${API}/res.php?${q}`);
    } catch (err) {
      console.log("poll error:", err.message); // network blip: keep polling
      await sleep(5_000);
      continue;
    }
    // Enterprise answers carry the token in "result" plus the solver's "user_agent"
    if (r.status === 1) return { token: r.result ?? r.request, userAgent: r.user_agent ?? null };
    if (r.request !== "CAPCHA_NOT_READY") throw new Error(`solve failed: ${r.request}`);
    await sleep(5_000);
  }
  throw new Error(`task ${id} not solved in ${timeoutMs / 1000}s`);
}

// Google's public v3 demo, as detect_recaptcha.py reported it
const PAGE = "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php";
const info = { sitekey: "6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9", type: "v3",
               enterprise: false, action: "examples/v3scores" };
const { token, userAgent } = await solve(buildParams(info, PAGE));
console.log("token:", token.slice(0, 20) + "...", "| userAgent:", userAgent);

// the same check the demo page's own JavaScript runs with its token
const q = new URLSearchParams({ action: info.action, token });
console.log(await getJson(`https://recaptcha-demo.appspot.com/recaptcha-v3-verify.php?${q}`));

$ CAPTCHA_API_KEY=... node solve_recaptcha.mjs
token: 0cAFcWeA6F-w3KX697Jj... | userAgent: null
{
  success: true,
  hostname: 'recaptcha-demo.appspot.com',
  challenge_ts: '2026-09-29T07:53:00Z',
  apk_package_name: null,
  score: 0.9,
  action: 'examples/v3scores',
  'error-codes': []
}

That's one run on a demo page, so don't read the 0.9 as a promise for your own target.

Where the token goes depends on the variant:

v2: it goes into the g-recaptcha-response textarea. If the widget has a data-callback, call that function with the token as well, because on callback-driven forms filling the textarea alone does nothing.
v3 and Enterprise: it goes into whatever field the page's own request uses. Watch the Network tab. It might be g-recaptcha-response in a form post, or a JSON field in an XHR.
Enterprise: also send the request with the user_agent from the answer as your User-Agent header.

Why a correctly solved token still gets rejected

Expired or reused. A token is valid for two minutes and can be verified only once. Classic siteverify reports this as timeout-or-duplicate, and Enterprise reports EXPIRED or DUPE. Solve once per request and submit right away.
Action mismatch. The backend compares the token's action with the one it expects. Google's PHP library, which the demos use, reports this as action-mismatch. Copy the string exactly, including case and slashes.
Wrong variant. This covers v3 parameters sent for a v2 invisible key, a missing invisible=1, and a missing enterprise=1. When the API can tell that the key belongs to another type, in.php answers ERROR_WRONG_KEY_TYPE. Often nothing tells you.
User agent mismatch on Enterprise. Reuse the user_agent that came back with the token.
Wrong page URL. Send the URL of the page where the widget loads. If the widget sits inside an iframe, send the iframe's URL. The hostname in the check has to be the site's.
Score below the site's threshold. If everything above is right and it still fails, you have a reputation problem (IP, browser, behaviour). That's covered in why your reCAPTCHA v3 score is low.
Enterprise site rules. An Enterprise site can reject a valid token on its own rules, based on reasons, IP or session. Test against your real target, not only a demo.

FAQ

Is reCAPTCHA Enterprise the same as v3?
No. Enterprise is the Google Cloud product. Its score keys work like v3 in the browser, but they load enterprise.js, call grecaptcha.enterprise.execute(), and are checked through the assessment API, which returns reasons and token details along with the score. Enterprise also has checkbox and invisible keys that behave like v2.

How do I know if a site uses reCAPTCHA Enterprise?
Find the sitekey the form uses. Then check whether enterprise.js loads that key, or whether it's passed to grecaptcha.enterprise.*. An enterprise.js somewhere on the page isn't enough on its own, because it can belong to another key.

Does render=explicit mean v3?
No. render=explicit is v2's explicit rendering mode. v3 is render= followed by the sitekey.

Can I tell the version from the sitekey?
No. All variants use 40-character keys that start with 6L.

Can I ask the solver for a 0.9 score?
No. There's no min_score parameter. The site decides which score it accepts.

I'm Bassem, and I run CaptchaAI. ocr.captchaai.com in the scripts above is our endpoint, and it solves all five variants in the table through the 2Captcha-compatible API. To try the detector's output against your own target, a free thread is enough: one thread for 30 days, no card. The v3 Enterprise guide lists every parameter.