Skip to content

CapMonster

CapMonster actions integrate Marvin with the CapMonster Cloud service so it can solve reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, and image captchas automatically.

To use these actions you must have a CapMonster Cloud account and a valid API key (api_key).

Important: reCAPTCHA and Turnstile solutions usually expire quickly (about 2 minutes). Solve the captcha as the last step before submitting the form or validating the page.

Return values (state variables) - Actions expose return values as state variables that can be read by the integrator. - To read a returned value, assign a local variable from the state variable using the $ prefix. The name must match exactly the key returned by the action.

Generic example:

# call the action
capmonster.recaptcha_v2(browser, "MY_KEY")

# read the returned token
g_recaptcha_response = $g_recaptcha_response

The sitekey is read automatically from the current page. The action first looks for the data-sitekey attribute. If it is missing, it reads the k query parameter from the reCAPTCHA iframe (recaptcha/api2/anchor or recaptcha/enterprise/anchor).

Actions

The actions below are available in Marvin:

capmonster.recaptcha_v2

Solves reCAPTCHA v2 found on the current page.

The action creates a CapMonster RecaptchaV2Task, polls until the result is ready, and returns the token. When auto_inject is True, the token is written into the page g-recaptcha-response fields (including nested frames) and the reCAPTCHA callback is executed.

Parameters:
  • browser — the browser/page object where the reCAPTCHA is present.
  • api_key — the CapMonster Cloud account key (string).
  • callback_function (optional) — JavaScript callback name or path used by the page. Used only when auto_inject is True.
  • isInvisible (optional) — whether the widget is an invisible reCAPTCHA. The value is sent to CapMonster as provided.
  • auto_inject (optional) — when True, injects the token into the page and runs the callback. The default is False: the action only returns the token.
Return:
  • g_recaptcha_response — the solution token (string).

Usage example:

# token only
capmonster.recaptcha_v2(browser, "MY_KEY")
g_recaptcha_response = $g_recaptcha_response

# invisible reCAPTCHA, injecting the token and running the page callback
capmonster.recaptcha_v2(browser, "MY_KEY", isInvisible=True, auto_inject=True)

# explicit callback
capmonster.recaptcha_v2(browser, "MY_KEY", callback_function="onSuccess", auto_inject=True)

Exceptions: - Sitekey not found on the page (neither data-sitekey nor the reCAPTCHA iframe). - Account with zero balance (Account has zero balance). - Failure creating or polling the CapMonster task. - Failure running an explicit callback after 3 attempts. Without callback_function, a missing callback does not stop the action.

capmonster.recaptcha_v3

Solves reCAPTCHA v3 found on the current page.

The action creates a CapMonster RecaptchaV3TaskProxyless, polls until the result is ready, and returns the token. When auto_inject is True, the token is written into the g-recaptcha-response fields and the reCAPTCHA callback is executed.

Parameters:
  • browser — the browser/page object where the reCAPTCHA is present.
  • api_key — the CapMonster Cloud account key (string).
  • callback_function (optional) — JavaScript callback name or path used by the page. Used only when auto_inject is True.
  • isEnterprise (optional) — when True, solves the challenge as reCAPTCHA Enterprise. The default is False.
  • auto_inject (optional) — when True, injects the token into the page and runs the callback. The default is False: the action only returns the token.
Return:
  • g_recaptcha_response — the solution token (string).

Usage example:

# standard reCAPTCHA v3
capmonster.recaptcha_v3(browser, "MY_KEY")
g_recaptcha_response = $g_recaptcha_response

# reCAPTCHA Enterprise, injecting the token into the page
capmonster.recaptcha_v3(browser, "MY_KEY", isEnterprise=True, auto_inject=True)

Exceptions: - Sitekey not found on the page. - Account with zero balance (Account has zero balance). - Failure creating or polling the CapMonster task. - Failure running an explicit callback after 3 attempts. Without callback_function, a missing callback does not stop the action.

capmonster.cloudflare_turnstile

Solves Cloudflare Turnstile found on the current page.

The action creates a CapMonster TurnstileTask and returns the token. When auto_inject is True, the token is written into the page cf-turnstile-response fields.

Parameters:
  • browser — the browser/page object where Turnstile is present.
  • api_key — the CapMonster Cloud account key (string).
  • auto_inject (optional) — when True, injects the token into the cf-turnstile-response fields. The default is False: the action only returns the token.
Return:
  • token_cloudflare — the solution token (string).

Usage example:

# get the token
capmonster.cloudflare_turnstile(browser, "MY_KEY")
token_cloudflare = $token_cloudflare

# inject the token into the page
capmonster.cloudflare_turnstile(browser, "MY_KEY", auto_inject=True)

Exceptions: - Sitekey not found on the page. - Account with zero balance (Account has zero balance). - Failure creating or polling the CapMonster task.

capmonster.image_to_text

Solves an image captcha from a local file or a public URL.

The image is converted to Base64 and sent to CapMonster as an ImageToTextTask. Provide image_path or image_url. When both are provided, the local file is used.

Parameters:
  • api_key — the CapMonster Cloud account key (string).
  • image_url (optional) — public URL of the captcha image.
  • image_path (optional) — local path to the image file.
  • case (optional) — when True, recognition is case-sensitive. The default is False.
Return:
  • captcha — the solved text (string).

Usage example:

# local file
capmonster.image_to_text("MY_KEY", image_path="C:/temp/captcha.png")
captcha = $captcha

# public URL, case-sensitive
capmonster.image_to_text("MY_KEY", image_url="https://example.com/captcha.png", case=True)
captcha = $captcha

Exceptions: - Neither image_url nor image_path was provided (Enter the image URL or path). - Account with zero balance (Account has zero balance). - Failure downloading the image, or creating or polling the CapMonster task.

How the reCAPTCHA callback is executed

recaptcha_v2 and recaptcha_v3 run the callback only when auto_inject is True.

  • Without callback_function, the action tries to discover a callback once: the data-callback attribute on .g-recaptcha elements, or functions registered in ___grecaptcha_cfg. If none is found, execution continues and the injected token stays available.
  • With callback_function, the action tries that function up to 3 times, waiting 0.5 seconds between attempts. If every attempt fails, the action stops.

You can find the callback function in two common ways:

  • HTML element using the g-recaptcha class with data-callback. Example:
<input type="submit" class="g-recaptcha" data-callback="loginFn" onclick="validateForm" value="OK" data-sitekey="XXXXXXXXXXXXXXXXXXXXXXXX">
  • Programmatic definition using grecaptcha.render, where the callback parameter points to the function. Example:
grecaptcha.render("recaptcha", {
    "sitekey": "XXXXXXXXXXXXXXXXXXXXXXXX",
    "callback": verifyCallbackCaptcha,
    "size": "invisible"
})

If the page validates the reCAPTCHA via POST, injecting the token (auto_inject=True) is usually enough, and callback_function can be omitted.