Python library for interacting with the Solvecaptcha API (captcha-solving service)

A simple and efficient method to integrate the Solvecaptcha captcha-solving service into your code, enabling the automation of solving various types of captchas. Examples of API requests for different captcha types can be found on the Python captcha solver page.

✅ Supported captcha solvers

To get started quickly, check out the Captcha Solver API documentation.

Helpful links:

• reCAPTCHA v2 solver (Python + Selenium)
• reCAPTCHA v3 solver
• Text & Image captcha solver (Base64 / file input)
• Cloudflare captcha / Turnstile solver
• Amazon captcha (WAF & login forms)
• GeeTest slider solver
• FunCaptcha (Arkose Labs)
• Other custom captcha types

🛠️ Features

• Fast and fully automated captcha bypass
• Works in Python environments
• Compatible with Selenium, Playwright, and other browser automation tools
• Lightweight SDK with modern async/await support
• Pay only for successful solves
• 99.9% uptime
• 24/7 support for developers and integration teams

📦 Use cases

• Web scraping behind reCAPTCHA or Cloudflare walls
• Automated form submission and login flows
• QA pipelines and headless browser testing
• Bypassing captchas in research or bot-detection evaluation
• Custom browser automations using Python

Need help integrating with your Python app or automation tools? Open an issue or fork this repo to contribute.

• Python Library for Interacting with the Solvecaptcha API
  • Installation
  • Configuration
    • Solvecaptcha instance options
  • Solve captcha
    • Captcha options
    • Normal Captcha
    • Text Captcha
    • reCAPTCHA v2
    • reCAPTCHA v3
    • FunCaptcha
    • GeeTest
    • GeeTest v4
    • Cloudflare Turnstile
    • KeyCaptcha
    • Grid
    • ClickCaptcha
    • Rotate
  • Other methods
    • send / get_result
    • balance
    • report
  • Error handling
  • Proxies
  • Async calls
  • Examples
  • Examples using Selenium
  • Useful articles
  • Get in touch
  • License

Installation

This package can be installed using Pip:

pip3 install solvecaptcha-python

or You can install this package directly from GitHub using pip:

pip install git+https://github.com/solvercaptcha/solvecaptcha-python.git

Configuration

An instance of Solvecaptcha can be created as follows:

from solvecaptcha import Solvecaptcha

solver = Solvecaptcha('YOUR_API_KEY')

Additionally, there are several options available for configuration:

config = {
            'server':           'solvecaptcha.com',
            'apiKey':           'YOUR_API_KEY',
            'callback':         'https://your.site/result-receiver',
            'defaultTimeout':    120,
            'recaptchaTimeout':  600,
            'pollingInterval':   10,
            'extendedResponse':  False
        }
solver = Solvecaptcha(**config)

Solvecaptcha instance options

[!IMPORTANT] Once callback is defined for the Solvecaptcha instance, all methods return only the captcha ID and DO NOT poll the API to get the result. The result will be sent to the callback URL.

To get the answer manually, use the get_result method.

Solve captcha

When submitting any image-based CAPTCHA, you can provide additional options to assist Solvecaptcha workers in solving it correctly.

Captcha options

Below, you can find basic examples for each captcha type. For more examples with all available options, check the examples directory.

Normal Captcha

^{API method description.}

To solve a standard captcha (distorted text on an image), use the following method. This method can also be applied for text recognition in any image.

result = solver.normal('path/to/captcha.jpg', param1=..., ...)
# OR
result = solver.normal('https://site-with-captcha.com/path/to/captcha.jpg', param1=..., ...)

result = solver.audio('path/to/captcha.mp3', lang = 'lang', param1=..., ...)
# OR
result = solver.audio('https://site-with-captcha.com/path/to/captcha.mp3', lang = 'lang', param1=..., ...)

Text Captcha

^{API method description.}

This method can be used to solve captchas that require answering a question presented in plain text.

result = solver.text('If tomorrow is Saturday, what day is today?', param1=..., ...)

reCAPTCHA v2

^{API method description.}

Use the following method to solve reCAPTCHA V2 and retrieve a token for bypassing the protection.

result = solver.recaptcha(sitekey='6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-',
                          url='https://mysite.com/page/with/recaptcha',
                          param1=..., ...)

reCAPTCHA v3

^{API method description.}

This method offers a reCAPTCHA V3 solver and returns a token.

result = solver.recaptcha(sitekey='6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-',
                            url='https://mysite.com/page/with/recaptcha-v3',
                            version='v3',
                            param1=..., ...)

FunCaptcha

^{API method description.}

FunCaptcha (Arkoselabs) solving method that returns a token.

result = solver.funcaptcha(sitekey='6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-',
                            url='https://mysite.com/page/with/funcaptcha',
                            param1=..., ...)

GeeTest

^{API method description.}

Method for solving GeeTest puzzle captcha. Returns a set of tokens in JSON format.

result = solver.geetest(gt='f1ab2cdefa3456789012345b6c78d90e',
                        challenge='12345678abc90123d45678ef90123a456b',
                        url='https://www.site.com/page/',
                        param1=..., ...)

GeeTest v4

^{API method description.}

Use this method to solve GeeTest v4. The response is returned in JSON format.

result = solver.geetest_v4(captcha_id='e392e1d7fd421dc63325744d5a2b9c73',
                            url='https://www.site.com/page/',
                            param1=..., ...)

Cloudflare Turnstile

^{API method description.}

Use this method to solve Cloudflare Turnstile. The response is returned as JSON containing the token.

result = solver.turnstile(sitekey='0x1AAAAAAAAkg0s2VIOD34y5',
                            url='http://mysite.com/',
                            data='foo',
                            pagedata='bar',
                            action='challenge',
                            useragent='Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36')

KeyCaptcha

^{API method description.}

Token-based method for solving KeyCaptcha.

result = solver.keycaptcha(s_s_c_user_id=10,
    				   s_s_c_session_id='493e52c37c10c2bcdf4a00cbc9ccd1e8',
    				   s_s_c_web_server_sign='9006dc725760858e4c0715b835472f22-pz-',
    				   s_s_c_web_server_sign2='2ca3abe86d90c6142d5571db98af6714',
    				   url='https://www.keycaptcha.ru/demo-magnetic/',
    				   param1=..., ...)

Grid

^{API method description.}

The grid method was initially known as the Old reCAPTCHA V2 method. It can be used to bypass any captcha that requires selecting specific grid boxes on an image. Returns the numbers of the selected boxes.

result = solver.grid('path/to/captcha.jpg', param1=..., ...)

ClickCaptcha

^{API method description.}

The ClickCaptcha method returns the coordinates of specific points on the captcha image. It is useful when solving captchas that require clicking on designated areas within the image.

result = solver.coordinates('path/to/captcha.jpg', param1=..., ...)

Rotate

^{API method description.}

This method is used to solve captchas that require rotating an object. It is primarily utilized for bypassing FunCaptcha and returns the rotation angle.

result = solver.rotate('path/to/captcha.jpg', param1=..., ...)

Canvas

^{API method description.}

The canvas method is used for captchas that require drawing a line around an object in an image. It returns a set of point coordinates for constructing a polygon.

result = solver.canvas('path/to/captcha.jpg', param1=..., ...)

Other methods

send / get_result

These methods allow manual captcha submission and answer polling. The send() method supports sending any captcha type. To specify the captcha type, you must manually set the method parameter, for example, method='recaptcha' for solving reCAPTCHA.
You can find the available values for the method parameter in the API documentation.

Example of manually solving a Normal captcha:

import time
. . . . .


id = solver.send(file='path/to/captcha.jpg')
time.sleep(20)

code = solver.get_result(id)

balance

^{API method description.}

Use this method to retrieve your account balance.

balance = solver.balance()

report

^{API method description.}

Use this method to report whether a captcha answer was correct or incorrect.

solver.report(id, True) # captcha solved correctly
solver.report(id, False) # captcha solved incorrectly

Error handling

If an error occurs, the captcha solver throws an exception. Proper error handling is essential. We recommend using try except to manage exceptions.
A complete list of possible errors can be found in the API documentation.

try:
    result = solver.text('If tomorrow is Saturday, what day is today?')
except ValidationException as e:
    # invalid parameters passed
	print(e)
except NetworkException as e:
	# network error occurred
	print(e)
except ApiException as e:
    # api respond with error
	print(e)
except TimeoutException as e:
    # captcha is not solved so far
	print(e)

Proxies

You can provide your proxy as an additional argument for the following methods: reCAPTCHA, FunCaptcha, GeeTest, GeeTest v4, KeyCaptcha, Turnstile, Amazon WAF, and other captchas.

The proxy will be passed to the API to facilitate captcha solving.

We also offer our own proxies that you can use.

proxy={
    'type': 'HTTPS',
    'uri': 'login:password@IP_address:PORT'
}

Async calls

You can also perform asynchronous calls using asyncio, for example:

import asyncio
import concurrent.futures
from solvecaptcha import Solvecaptcha

API_KEY = "YOUR_API_KEY"
image = "data:image/png;base64,iVBORw0KGgoA..."

async def captchaSolver(image):
    loop = asyncio.get_running_loop()
    with concurrent.futures.ThreadPoolExecutor() as pool:
        result = await loop.run_in_executor(pool, lambda: Solvecaptcha(API_KEY).normal(image))
        return result

captcha_result = asyncio.run(captchaSolver(image))

Examples

Examples of solving all supported captcha types can be found in the examples directory.

Examples using Selenium

We also have a separate repository where you can find examples of captcha solving using the Selenium \ seleniumbase library.

Useful articles

• Solve and bypass Google reCAPTCHA, Image CAPTCHA, Cloudflare Challenge and any captcha in Selenium with captcha solver.
• Solve and bypass Google reCAPTCHA, Arkose FunCaptcha, Cloudflare Turnstile, and any captcha in Puppeteer with captcha solver.

Get in touch

License

The code in this repository is licensed under the MIT License. For more details, see the LICENSE file.