TTCaptchaSolved 1.0.0

Solve TikTok CAPTCHAs locally using OpenCV - supports slide, rotate, and 3D shapes captchas

TikTok CAPTCHA Solver 🧩

A Python library for solving TikTok CAPTCHAs using OpenCV.

Get your API key at: https://captchasolved.com

Supports:

• ✅ Slide/Puzzle CAPTCHA - Slide a piece to fit into a gap
• ✅ Rotate/Whirl CAPTCHA - Rotate an image to match the background
• ✅ 3D Shapes CAPTCHA - Click on matching 3D objects

Features

• 🚀 Fast - Solves CAPTCHAs in milliseconds using optimized OpenCV algorithms
• 🎯 Accurate - High accuracy using edge detection and template matching
• 🔌 Easy Integration - Works with Selenium, Playwright, or standalone
• 🐍 Pure Python - Simple pip install

Installation

pip install captchasolved

With Browser Automation Support

# For Selenium
pip install captchasolved[selenium]

# For Playwright
pip install captchasolved[playwright]

# For both
pip install captchasolved[all]

Quick Start

1. Get Your API Key

Sign up at https://captchasolved.com to get your API key.

2. Set Your API Key

from tiktok_captcha_solver import set_api_key

# Option 1: Set in code
set_api_key("cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

# Option 2: Set via environment variable
# export CAPTCHA_SOLVER_API_KEY="cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

3. Solve CAPTCHAs

from tiktok_captcha_solver import TikTokCaptchaSolver, set_api_key

set_api_key("cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
solver = TikTokCaptchaSolver()

# Solve slide/puzzle captcha
result = solver.solve_slide(
    background="path/to/background.png",  # or base64, bytes, numpy array
    piece="path/to/piece.png"
)
print(f"Slide distance: {result.x} pixels")
print(f"Confidence: {result.confidence}")

# Solve rotate captcha
result = solver.solve_rotate(
    outer="path/to/outer.png",
    inner="path/to/inner.png"
)
print(f"Rotate angle: {result.angle} degrees")

# Solve 3D shapes captcha
result = solver.solve_shapes(
    image="path/to/shapes.png"
)
print(f"Click points: ({result.x1}, {result.y1}) and ({result.x2}, {result.y2})")

With Selenium

from tiktok_captcha_solver import SeleniumSolver, set_api_key
from selenium import webdriver

set_api_key("cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

driver = webdriver.Chrome()
driver.get("https://www.tiktok.com/login")

solver = SeleniumSolver(driver)
solver.solve_captcha_if_present()

With Playwright (Sync)

from tiktok_captcha_solver import PlaywrightSolver, set_api_key
from playwright.sync_api import sync_playwright

set_api_key("cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

with sync_playwright() as p:
    browser = p.chromium.launch(headless=False)
    page = browser.new_page()
    page.goto("https://www.tiktok.com/login")
    
    solver = PlaywrightSolver(page)
    solver.solve_captcha_if_present()

With Playwright (Async)

import asyncio
from tiktok_captcha_solver import AsyncPlaywrightSolver, set_api_key
from playwright.async_api import async_playwright

set_api_key("cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=False)
        page = await browser.new_page()
        await page.goto("https://www.tiktok.com/login")
        
        solver = AsyncPlaywrightSolver(page)
        await solver.solve_captcha_if_present()

asyncio.run(main())

Pricing

Plan	Solves	Price
Starter	1,000	$9
Pro	10,000	$49
Enterprise	100,000	$299

Get your API key at: https://captchasolved.com

Check Your Usage

from tiktok_captcha_solver import get_usage_info

info = get_usage_info()
print(f"Plan: {info['plan']}")
print(f"Remaining: {info['remaining_solves']} solves")

API Reference

TikTokCaptchaSolver

Main solver class that combines all CAPTCHA types.

solver = TikTokCaptchaSolver()

Methods

solve_slide(background, piece, piece_start_x=0) -> SlideResult

Solve a slide/puzzle CAPTCHA.

Parameters:

• background: Background image (path, base64, bytes, numpy array, or PIL Image)
• piece: Puzzle piece image
• piece_start_x: Starting X position of the piece (default: 0)

Returns: SlideResult with:

• x: X position/slide distance
• y: Y position
• confidence: Match confidence (0-1)

solve_rotate(outer, inner) -> RotateResult

Solve a rotate/whirl CAPTCHA.

Parameters:

• outer: Outer/background image
• inner: Inner image to rotate

Returns: RotateResult with:

• angle: Degrees to rotate
• confidence: Match confidence (0-1)

solve_shapes(image) -> ShapesResult

Solve a 3D shapes matching CAPTCHA.

Parameters:

• image: CAPTCHA image with shapes

Returns: ShapesResult with:

• x1, y1: First click point
• x2, y2: Second click point
• confidence: Match confidence (0-1)

SeleniumSolver

Selenium integration with automatic CAPTCHA detection.

solver = SeleniumSolver(
    driver,              # Selenium WebDriver instance
    max_retries=3,       # Max retry attempts
    retry_delay=1.0,     # Delay between retries
    callback=None        # Optional callback(event, data)
)

Methods

• solve_captcha_if_present(): Detect and solve any CAPTCHA
• solve_slide_captcha(): Solve slide CAPTCHA
• solve_rotate_captcha(): Solve rotate CAPTCHA
• solve_shapes_captcha(): Solve shapes CAPTCHA
• detect_captcha_type(): Returns 'slide', 'rotate', 'shapes', or None

PlaywrightSolver / AsyncPlaywrightSolver

Playwright integration (sync and async versions).

# Sync
solver = PlaywrightSolver(page, max_retries=3, retry_delay=1.0, callback=None)

# Async
solver = AsyncPlaywrightSolver(page, max_retries=3, retry_delay=1.0, callback=None)

Same methods as SeleniumSolver (async versions return coroutines).

Advanced Usage

Using Individual Solvers

from tiktok_captcha_solver import SlideSolver, RotateSolver, ShapesSolver

# Slide solver with custom settings
slide_solver = SlideSolver(use_edge_detection=True)
result = slide_solver.solve(background, piece)

# Get position as ratio (useful for different screen sizes)
x_ratio, y_ratio = slide_solver.solve_with_ratio(background, piece)

# Rotate solver with custom angle steps
rotate_solver = RotateSolver(angle_step=1.0, refine_step=0.1)
result = rotate_solver.solve(outer, inner)

# Get as drag distance for a slider
distance = rotate_solver.solve_as_distance(outer, inner, slider_width=348)

Callback Events

def on_event(event, data):
    print(f"Event: {event}, Data: {data}")

solver = SeleniumSolver(driver, callback=on_event)
solver.solve_captcha_if_present()

# Events:
# - 'solving': Starting to solve (data = captcha type)
# - 'solved': Solution found (data = result)
# - 'attempt': Retry attempt (data = attempt number)
# - 'success': Successfully solved
# - 'failed': Failed to solve
# - 'error': Error occurred (data = error message)

Loading Images

The solver accepts multiple image formats:

# File path
result = solver.solve_slide("background.png", "piece.png")

# Base64 string
result = solver.solve_slide(base64_bg, base64_piece)

# Bytes
result = solver.solve_slide(image_bytes_bg, image_bytes_piece)

# NumPy array (OpenCV format)
import cv2
bg = cv2.imread("background.png")
result = solver.solve_slide(bg, piece_array)

# PIL Image
from PIL import Image
bg = Image.open("background.png")
result = solver.solve_slide(bg, piece_image)

How It Works

Slide/Puzzle CAPTCHA

1. Load background and puzzle piece images
2. Remove whitespace/transparent borders from piece
3. Apply Canny edge detection to both images
4. Use OpenCV template matching (cv2.matchTemplate)
5. Find the position with highest correlation score

Rotate/Whirl CAPTCHA

1. Load outer and inner images
2. Rotate inner image through 0-360 degrees
3. Calculate similarity between rotated inner and outer
4. Find angle with highest similarity
5. Refine with smaller angle steps

3D Shapes CAPTCHA

1. Load the CAPTCHA image
2. Detect shape regions using contour detection
3. Extract features using ORB detector
4. Compare all pairs of shapes using feature matching
5. Return the centers of the best matching pair

Requirements

• Python 3.8+
• OpenCV (opencv-python)
• NumPy
• Pillow

Optional:

• Selenium (for browser automation)
• Playwright (for browser automation)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file.

Disclaimer

This library is for educational purposes only. Please ensure you comply with TikTok's Terms of Service when using this library. The authors are not responsible for any misuse of this software.