---
name: solve-captcha
description: Solve a CAPTCHA that blocks an authorised flow with the managed 2Captcha account - reCAPTCHA, Turnstile, GeeTest, hCaptcha, image and other challenges - through `2captcha-python`. Use when a CAPTCHA stands between you and a signup, login or request you need.
---

# 2Captcha

## Setup

The API key is managed by toadex and exposed as `TOADEX_TWOCAPTCHA_API_KEY`.

```python
import os
from twocaptcha import TwoCaptcha

solver = TwoCaptcha(os.environ["TOADEX_TWOCAPTCHA_API_KEY"])
```

## Common token examples:

```python
# Solve a reCAPTCHA challenge and extract its response token.
result = solver.recaptcha(sitekey=sitekey, url=page_url)
token = result["code"]

# Solve Turnstile with the provider fields captured from the page.
result = solver.turnstile(sitekey=sitekey, url=page_url, action=action, pagedata=pagedata)
token = result["code"]

# Solve a GeeTest challenge using its runtime identifiers.
result = solver.geetest(gt=gt, challenge=challenge, url=page_url)
token = result["code"]
```

## Provider fields

- Pass optional provider fields as keyword arguments when present, such as `action`, `data`, `pagedata`, `userAgent`/`useragent`, `surl`, `enterprise`, `invisible`, `rqdata`, or `proxy={"type": "HTTP", "uri": "user:pass@host:port"}`.

- If the required site tokens or provider fields are generated at runtime, use Pydoll to load the page and collect them from browser state before submitting to 2Captcha.

## Method Shapes

### Image, audio, and text:

- `normal(file, **kwargs)`: image path, URL, or base64 body.
- `audio(file, lang, **kwargs)`: MP3 path or URL plus language such as `en`, `ru`, `de`, `el`, `pt`, or `fr`.
- `text(text, **kwargs)`: plain-text question.
- `grid(file, **kwargs)`: image where numbered grid cells should be selected.
- `canvas(file, **kwargs)`: image where a polygon should be drawn.
- `coordinates(file, **kwargs)`: image where click coordinates are needed.
- `rotate(files, **kwargs)`: image needing rotation.

Useful image options include `numeric`, `minLen`, `maxLen`, `phrase`, `caseSensitive`, `calc`, `lang`, `hintImg`, and `hintText`.

### Common token providers:

- `recaptcha(sitekey, url, version="v2", enterprise=0, **kwargs)`: use `version="v3"` for reCAPTCHA v3; include `action` when the page supplies one.
- `hcaptcha(sitekey, url, **kwargs)`: include `invisible`, `data`/`rqdata`, or `domain` when present.
- `turnstile(sitekey, url, **kwargs)`: include `action`, `data`, `pagedata`, and `useragent`/`userAgent` when present.
- `funcaptcha(sitekey, url, **kwargs)`: Arkose/FunCaptcha; include `surl` for custom Arkose API hosts and `userAgent` when needed.
- `mtcaptcha(sitekey, url, **kwargs)`.
- `friendly_captcha(sitekey, url, **kwargs)`: block the FriendlyCaptcha widget script before page load or the returned token may fail.

### Puzzle and vendor tokens:

- `geetest(gt, challenge, url, **kwargs)`.
- `geetest_v4(captcha_id, url, **kwargs)`.
- `lemin(captcha_id, div_id, url, **kwargs)`.
- `capy(sitekey, url, **kwargs)`: include `api_server` when the page uses a non-default API host.
- `atb_captcha(app_id, api_server, url, **kwargs)`.
- `cutcaptcha(misery_key, apikey, url, **kwargs)`.
- `tencent(app_id, url, **kwargs)`.
- `yandex_smart(sitekey, url, **kwargs)`.

### Provider-specific flows:

- `amazon_waf(sitekey, iv, context, url, **kwargs)`.
- `keycaptcha(s_s_c_user_id, s_s_c_session_id, s_s_c_web_server_sign, s_s_c_web_server_sign2, url, **kwargs)`.
- `datadome(captcha_url, pageurl, userAgent, proxy, **kwargs)`: proxy is required.
- `vkimage(files, steps, **kwargs)`.
- `vkcaptcha(redirect_uri, userAgent, proxy, **kwargs)`: proxy is required.
- `captchafox(sitekey, pageurl, userAgent, proxy, **kwargs)`: proxy is required.

### Newer methods:

- `prosopo(sitekey, pageurl, **kwargs)`.
- `temu(body, part1, part2, part3, **kwargs)`.
- `cybersiara(master_url_id, pageurl, userAgent, **kwargs)`.
- `altcha(pageurl, **kwargs)`: include `challenge_json` or `challenge_url`.
- `binance(pageurl, sitekey, validate_id, **kwargs)`.
- `yidun(sitekey, pageurl, **kwargs)`.
- `hunt(pageurl, api_get_lib, **kwargs)`.
- `alibaba(pageurl, scene_id, prefix, **kwargs)`.
- `tspd(pageurl, tspd_cookie, html_page_base64, proxy, **kwargs)`: proxy is required.
- `basilisk(pageurl, sitekey, **kwargs)`.