### Install Shopee Captcha Solver

Source: https://github.com/gbiz123/shopee-captcha-solver/blob/master/README.md

Install the package using pip. Ensure Python version is 3.10 or higher.

```bash
pip install shopee-captcha-solver
```

--------------------------------

### Initialize Async Playwright Solver Context

Source: https://github.com/gbiz123/shopee-captcha-solver/blob/master/README.md

Use `make_async_playwright_solver_context` to create an async Playwright BrowserContext patched with the Shopee Captcha Solver extension. This context automatically handles captcha detection and solving in the background. Ensure you have the necessary API key and Playwright is installed.

```python
import asyncio
from playwright.async_api import async_playwright
from shopee_captcha_solver import make_async_playwright_solver_context

# Need this arg if running headless
launch_args = ["--headless=chrome"]

async def main():
    api_key = "YOUR_API_KEY_HERE"
    async with async_playwright() as p:
        context = await make_async_playwright_solver_context(p, api_key, args=launch_args) # Returns playwright BrowserContext instance
        # ... [The rest of your code that accesses shopee goes here]

asyncio.run(main())
```

--------------------------------

### Initialize Selenium Client for Shopee Captcha Solving

Source: https://github.com/gbiz123/shopee-captcha-solver/blob/master/README.md

Use `make_undetected_chromedriver_solver` to create an `undetected_chromedriver` instance with the Shopee Captcha Solver extension. Captchas are solved automatically. `stealth` can be added for enhanced privacy. `ChromeOptions` and keyword arguments for `uc.Chrome()` can be passed.

```python
from shopee_captcha_solver import make_undetected_chromedriver_solver
from selenium_stealth import stealth
from selenium.webdriver import ChromeOptions
import undetected_chromedriver as uc

chrome_options = ChromeOptions()
# chrome_options.add_argument("--headless=chrome") # If running headless, use this option

api_key = "YOUR_API_KEY_HERE"
driver = make_undetected_chromedriver_solver(api_key, options=options) # Returns uc.Chrome instance
stealth(driver) # Add stealth if needed
# ... [The rest of your code that accesses shopee goes here]

# Now shopee captchas will be automatically solved!
```

--------------------------------

### Initialize Nodriver Client for Shopee Captcha Solving

Source: https://github.com/gbiz123/shopee-captcha-solver/blob/master/README.md

Use `make_nodriver_solver` to create a Nodriver instance patched with the Shopee Captcha Solver extension. Captchas are solved automatically in the background. Pass `browser_args` for headless mode. Any keyword arguments are passed to `nodriver.start()`.

```python
from shopee_captcha_solver.launcher import make_nodriver_solver

async def main():
    launch_args = ["--headless=chrome"] # If running headless, use this option, or headless=new
    api_key = "YOUR_API_KEY_HERE"
    # NOTE: Keyword arguments passed to make_nodriver_solver() are directly passed to nodriver.start()!
    driver = await make_nodriver_solver(api_key, browser_args=launch_args) # Returns nodriver browser 
    # ... [The rest of your code that accesses shopee goes here]
    # Now shopee captchas will be automatically solved!
```

--------------------------------

### Initialize Playwright Client for Shopee Captcha Solving

Source: https://github.com/gbiz123/shopee-captcha-solver/blob/master/README.md

Use `make_playwright_solver_context` to create a Playwright `BrowserContext` instance patched with the Shopee Captcha Solver extension. Captchas are solved automatically. The `launch_args` are needed for headless mode.

```python
from shopee_captcha_solver import make_playwright_solver_context
from playwright.sync_api import sync_playwright

# Need this arg if running headless
launch_args = ["--headless=chrome"]

api_key = "YOUR_API_KEY_HERE"
with sync_playwright() as p:
    context = make_playwright_solver_context(p, api_key, args=launch_args) # Returns playwright BrowserContext instance
    # ... [The rest of your code that accesses shopee goes here]

```

--------------------------------

### Download Image as Base64 with Shopee Captcha Solver

Source: https://context7.com/gbiz123/shopee-captcha-solver/llms.txt

Utility function to download an image from a URL and return it as a base64-encoded string. Supports optional proxy and custom headers for advanced network configurations.

```python
from shopee_captcha_solver.downloader import download_image_b64

# Without proxy
b64 = download_image_b64("https://example.com/captcha.png")

# With proxy and custom headers
b64 = download_image_b64(
    "https://example.com/captcha.png",
    headers={"User-Agent": "Mozilla/5.0"},
    proxy="http://user:pass@proxyhost:8080"
)
print(b64[:40])  # "iVBORw0KGgoAAAANSUhEUgAA..."
```

--------------------------------

### Pydantic Models and Serialization

Source: https://context7.com/gbiz123/shopee-captcha-solver/llms.txt

Demonstrates the usage of Pydantic models for defining request and response structures, and serializing requests to JSON for debugging.

```APIDOC
## Pydantic Models and Serialization

All API payloads and responses are typed Pydantic models.

```python
from shopee_captcha_solver.models import (
    PuzzleCaptchaResponse,       # slide_x_proportion: float
    ImageCrawlCaptchaResponse,   # pixels_from_slider_origin: int
    ProportionalPoint,           # proportion_x: float, proportion_y: float
    ArcedSlideTrajectoryElement, # pixels_from_slider_origin, piece_rotation_angle, piece_center
    ImageCrawlCaptchaRequest,    # puzzle_image_b64, piece_image_b64, slide_piece_trajectory
    SemanticShapesRequest,       # image_b64: str, challenge: str
)
from shopee_captcha_solver.captchatype import CaptchaType  # IMAGE_CRAWL=0, PUZZLE=1, SEMANTIC_SHAPES=2

# Serialize a request to disk for debugging
from shopee_captcha_solver.models import dump_to_json
request = ImageCrawlCaptchaRequest(
    puzzle_image_b64="...",
    piece_image_b64="...",
    slide_piece_trajectory=[]
)
dump_to_json(request, "debug_request.json")
```
```

--------------------------------

### SeleniumSolver (Deprecated)

Source: https://context7.com/gbiz123/shopee-captcha-solver/llms.txt

Wraps a `selenium.webdriver.Chrome` instance for manual solving of captchas. Prefer `make_undetected_chromedriver_solver()` instead.

```APIDOC
## SeleniumSolver (Deprecated)

Wraps a `selenium.webdriver.Chrome` instance and exposes explicit solve methods. **Prefer `make_undetected_chromedriver_solver()` instead.**

### Method
`SeleniumSolver(driver: webdriver.Chrome, api_key: str)`

### Methods

#### `captcha_is_present(timeout: int = 10)`
Checks if a captcha is currently present on the page.

- **timeout** (int) - Maximum time in seconds to wait for the captcha.

**Returns:**
- `bool` - True if a captcha is present, False otherwise.

#### `identify_captcha()`
Identifies the type of captcha present.

**Returns:**
- `str` - The type of captcha detected.

#### `solve_captcha_if_present(captcha_detect_timeout: int = 15, retries: int = 3)`
Attempts to solve the captcha if it is present on the page.

- **captcha_detect_timeout** (int) - Timeout for detecting the captcha.
- **retries** (int) - Number of times to retry solving the captcha.
```

--------------------------------

### Use Async Playwright with Auto-Solving Extension

Source: https://context7.com/gbiz123/shopee-captcha-solver/llms.txt

Async variant of make_playwright_solver_context. Returns playwright.async_api.BrowserContext. Captchas are resolved automatically.

```python
import asyncio
from shopee_captcha_solver import make_async_playwright_solver_context
from playwright.async_api import async_playwright

api_key = "YOUR_API_KEY_HERE"
launch_args = ["--headless=chrome"]

async def main():
    async with async_playwright() as p:
        context = await make_async_playwright_solver_context(p, api_key, args=launch_args)
        page = await context.new_page()
        await page.goto("https://shopee.sg/buyer/login")
        await page.fill("input[name='loginKey']", "user@example.com")
        await page.fill("input[name='password']", "secret")
        await page.click("button[type='submit']")
        await page.wait_for_timeout(5000)
        await context.close()

asyncio.run(main())
```

--------------------------------

### Utility: download_image_b64

Source: https://context7.com/gbiz123/shopee-captcha-solver/llms.txt

Downloads an image from a URL and returns it as a base64-encoded string. Supports optional proxy and custom headers.

```APIDOC
## Utility: `download_image_b64`

Downloads an image from a URL and returns it as a base64-encoded string, with optional proxy and custom headers support.

```python
from shopee_captcha_solver.downloader import download_image_b64

# Without proxy
b64 = download_image_b64("https://example.com/captcha.png")

# With proxy and custom headers
b64 = download_image_b64(
    "https://example.com/captcha.png",
    headers={"User-Agent": "Mozilla/5.0"},
    proxy="http://user:pass@proxyhost:8080"
)
print(b64[:40])  # "iVBORw0KGgoAAAANSUhEUgAA..."
```
```

--------------------------------

### Use Sync Playwright with Auto-Solving Extension

Source: https://context7.com/gbiz123/shopee-captcha-solver/llms.txt

Returns a playwright.sync_api.BrowserContext loaded with the SadCaptcha extension. Captchas are resolved automatically during normal interaction.

```python
from shopee_captcha_solver import make_playwright_solver_context
from playwright.sync_api import sync_playwright

api_key = "YOUR_API_KEY_HERE"
launch_args = ["--headless=chrome"]  # remove for headed mode

with sync_playwright() as p:
    context = make_playwright_solver_context(p, api_key, args=launch_args)
    page = context.new_page()
    page.goto("https://shopee.sg/buyer/login")
    # Interact normally — captchas resolved automatically
    page.fill("#loginForm input[name='loginKey']", "user@example.com")
    page.fill("#loginForm input[name='password']", "secret")
    page.click("#loginForm button[type='submit']")
    page.wait_for_timeout(5000)
    context.close()
```

--------------------------------

### AsyncPlaywrightSolver (Deprecated)

Source: https://context7.com/gbiz123/shopee-captcha-solver/llms.txt

Async version of `PlaywrightSolver` for manual asynchronous solving of captchas. Prefer `make_async_playwright_solver_context()` instead.

```APIDOC
## AsyncPlaywrightSolver (Deprecated)

Async version of `PlaywrightSolver`. **Prefer `make_async_playwright_solver_context()` instead.**

### Method
`AsyncPlaywrightSolver(page: Page, api_key: str)`

### Methods

#### `solve_captcha_if_present(captcha_detect_timeout: int = 15, retries: int = 3)`
Attempts to solve the captcha if it is present on the page asynchronously.

- **captcha_detect_timeout** (int) - Timeout for detecting the captcha.
- **retries** (int) - Number of times to retry solving the captcha.
```

--------------------------------

### Use Selenium/undetected-chromedriver with Auto-Solving Extension

Source: https://context7.com/gbiz123/shopee-captcha-solver/llms.txt

Returns a uc.Chrome instance patched with the SadCaptcha extension. Captchas are solved in the background during normal interaction.

```python
from shopee_captcha_solver import make_undetected_chromedriver_solver
from selenium.webdriver import ChromeOptions

api_key = "YOUR_API_KEY_HERE"
options = ChromeOptions()
# options.add_argument("--headless=chrome")  # headless mode

driver = make_undetected_chromedriver_solver(api_key, options=options)

driver.get("https://shopee.sg/buyer/login")
# Interact with the page normally — captchas are solved in the background
driver.quit()
```

--------------------------------

### Deprecated AsyncPlaywrightSolver for Manual Solving

Source: https://context7.com/gbiz123/shopee-captcha-solver/llms.txt

This class is deprecated. It is the async version of PlaywrightSolver. Prefer `make_async_playwright_solver_context()` instead. Requires a valid API key.

```python
import asyncio
import warnings
from playwright.async_api import async_playwright
from shopee_captcha_solver import AsyncPlaywrightSolver

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://shopee.sg/buyer/login")

        with warnings.catch_warnings():
            warnings.simplefilter("ignore", DeprecationWarning)
            solver = AsyncPlaywrightSolver(page, "YOUR_API_KEY_HERE")

        await solver.solve_captcha_if_present(captcha_detect_timeout=15, retries=3)
        await browser.close()

asyncio.run(main())
```

--------------------------------

### PlaywrightSolver (Deprecated)

Source: https://context7.com/gbiz123/shopee-captcha-solver/llms.txt

Wraps a `playwright.sync_api.Page` for manual synchronous solving of captchas. Prefer `make_playwright_solver_context()` instead.

```APIDOC
## PlaywrightSolver (Deprecated)

Wraps a `playwright.sync_api.Page` and exposes explicit solve methods. **Prefer `make_playwright_solver_context()` instead.**

### Method
`PlaywrightSolver(page: Page, api_key: str)`

### Methods

#### `solve_captcha_if_present(captcha_detect_timeout: int = 15, retries: int = 3)`
Attempts to solve the captcha if it is present on the page.

- **captcha_detect_timeout** (int) - Timeout for detecting the captcha.
- **retries** (int) - Number of times to retry solving the captcha.
```

--------------------------------

### Deprecated PlaywrightSolver for Manual Solving

Source: https://context7.com/gbiz123/shopee-captcha-solver/llms.txt

This class is deprecated. It wraps a Playwright sync Page for manual captcha solving. Prefer `make_playwright_solver_context()` instead. Requires a valid API key.

```python
import warnings
from playwright.sync_api import sync_playwright
from shopee_captcha_solver import PlaywrightSolver

with sync_playwright() as p:
    browser = p.chromium.launch(headless=False)
    page = browser.new_page()
    page.goto("https://shopee.sg/buyer/login")

    with warnings.catch_warnings():
        warnings.simplefilter("ignore", DeprecationWarning)
        solver = PlaywrightSolver(page, "YOUR_API_KEY_HERE")

    solver.solve_captcha_if_present(captcha_detect_timeout=15, retries=3)
    browser.close()
```

--------------------------------

### Deprecated SeleniumSolver for Manual Solving

Source: https://context7.com/gbiz123/shopee-captcha-solver/llms.txt

This class is deprecated. It wraps a Selenium Chrome driver for manual captcha solving. Prefer `make_undetected_chromedriver_solver()` instead. Requires a valid API key.

```python
import warnings
import undetected_chromedriver as uc
from shopee_captcha_solver import SeleniumSolver

driver = uc.Chrome()
driver.get("https://shopee.sg/buyer/login")

with warnings.catch_warnings():
    warnings.simplefilter("ignore", DeprecationWarning)
    solver = SeleniumSolver(driver, "YOUR_API_KEY_HERE")

if solver.captcha_is_present(timeout=15):
    captcha_type = solver.identify_captcha()
    print(f"Detected: {captcha_type}")
    # Solve whichever type is present
    solver.solve_captcha_if_present(captcha_detect_timeout=15, retries=3)

driver.quit()
```

--------------------------------

### Use Nodriver with Auto-Solving Extension

Source: https://context7.com/gbiz123/shopee-captcha-solver/llms.txt

Creates a nodriver.Browser instance with the SadCaptcha Chrome extension for automatic captcha solving. Captchas are solved silently in the background without explicit calls.

```python
import asyncio
from shopee_captcha_solver.launcher import make_nodriver_solver

async def main():
    api_key = "YOUR_API_KEY_HERE"
    # Optional: pass headless flag or any nodriver.start() kwargs
    driver = await make_nodriver_solver(api_key, browser_args=["--headless=chrome"])

    tab = await driver.get("https://shopee.sg/buyer/login")
    # Fill in credentials, submit form — captcha is solved automatically
    await asyncio.sleep(5)
    await driver.stop()

asyncio.run(main())
```

--------------------------------

### Direct API Calls with ApiClient

Source: https://context7.com/gbiz123/shopee-captcha-solver/llms.txt

Use ApiClient for raw REST calls to SadCaptcha endpoints. Handles puzzle slides, image crawls, and semantic shape challenges. Ensure API key is valid and credits are available.

```python
import base64
from shopee_captcha_solver.api import ApiClient, BadRequest, ApiException
from shopee_captcha_solver.models import (
    ImageCrawlCaptchaRequest,
    ArcedSlideTrajectoryElement,
    ProportionalPoint,
    SemanticShapesRequest,
)

client = ApiClient("YOUR_API_KEY_HERE")

# --- 1. Puzzle slide ---
with open("puzzle_background.png", "rb") as f:
    puzzle_b64 = base64.b64encode(f.read()).decode()
with open("puzzle_piece.png", "rb") as f:
    piece_b64 = base64.b64encode(f.read()).decode()

try:
    resp = client.puzzle(puzzle_b64, piece_b64)
    # resp.slide_x_proportion: float — how far (0-1) to drag the slider
    print(f"Slide to {resp.slide_x_proportion * 100:.1f}% of bar width")
except BadRequest as e:
    print(f"Could not solve puzzle: {e}")
except ApiException as e:
    print(f"API error (bad key or no credits): {e}")

# --- 2. Image crawl (arced slide) ---
trajectory = [
    ArcedSlideTrajectoryElement(
        pixels_from_slider_origin=i * 5,
        piece_rotation_angle=float(i * 3),
        piece_center=ProportionalPoint(proportion_x=0.1 + i * 0.02, proportion_y=0.5),
    )
    for i in range(20)
]
request = ImageCrawlCaptchaRequest(
    puzzle_image_b64=puzzle_b64,
    piece_image_b64=piece_b64,
    slide_piece_trajectory=trajectory,
)
crawl_resp = client.image_crawl(request)
print(f"Move slider {crawl_resp.pixels_from_slider_origin}px from origin")

# --- 3. Semantic shapes ---
with open("shapes_challenge.png", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()
shapes_req = SemanticShapesRequest(image_b64=image_b64, challenge="Click the triangle")
point = client.semantic_shapes(shapes_req)
print(f"Click at proportional position ({point.proportion_x:.3f}, {point.proportion_y:.3f})")
```

--------------------------------

### ApiClient - Direct REST calls to SadCaptcha

Source: https://context7.com/gbiz123/shopee-captcha-solver/llms.txt

Provides raw access to the three SadCaptcha API endpoints for solving puzzles, image crawls, and semantic shapes. Handles BadRequest and ApiException on errors.

```APIDOC
## ApiClient

Provides raw access to the three SadCaptcha API endpoints. Raises `BadRequest` (HTTP 400) or `ApiException` (HTTP 401) on errors.

### Method
`ApiClient(api_key: str)`

### Methods

#### `puzzle(puzzle_b64: str, piece_b64: str)`
Solves a puzzle slide captcha.

- **puzzle_b64** (str) - Base64 encoded image of the puzzle background.
- **piece_b64** (str) - Base64 encoded image of the puzzle piece.

**Returns:**
- `resp.slide_x_proportion` (float) - How far (0-1) to drag the slider.

#### `image_crawl(request: ImageCrawlCaptchaRequest)`
Solves an image crawl captcha with an arced slide trajectory.

- **request** (ImageCrawlCaptchaRequest) - Request object containing puzzle and piece images, and slide trajectory.

**Returns:**
- `crawl_resp.pixels_from_slider_origin` (int) - Pixels to move the slider from the origin.

#### `semantic_shapes(request: SemanticShapesRequest)`
Solves a semantic shapes captcha by identifying a click point.

- **request** (SemanticShapesRequest) - Request object containing the image and challenge text.

**Returns:**
- `point` (ProportionalPoint) - Proportional coordinates (proportion_x, proportion_y) to click.
```

--------------------------------

### Pydantic Models for Shopee Captcha Solver

Source: https://context7.com/gbiz123/shopee-captcha-solver/llms.txt

Defines Pydantic models for API requests and responses, including types for captcha challenges and trajectory data. Used for serializing requests to JSON for debugging.

```python
from shopee_captcha_solver.models import (
    PuzzleCaptchaResponse,
    ImageCrawlCaptchaResponse,
    ProportionalPoint,
    ArcedSlideTrajectoryElement,
    ImageCrawlCaptchaRequest,
    SemanticShapesRequest,
)
from shopee_captcha_solver.captchatype import CaptchaType

from shopee_captcha_solver.models import dump_to_json
request = ImageCrawlCaptchaRequest(
    puzzle_image_b64="...",
    piece_image_b64="...",
    slide_piece_trajectory=[]
)
dump_to_json(request, "debug_request.json")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.