Metadata-Version: 2.4
Name: wulu-geetest-bypass
Version: 0.1.3
Summary: Geetest CAPTCHA v4 bypass library
Project-URL: Homepage, https://github.com/wulu007/geetest-bypass
Project-URL: Documentation, https://github.com/wulu007/geetest-bypass#readme
Project-URL: Repository, https://github.com/wulu007/geetest-bypass.git
Project-URL: Issues, https://github.com/wulu007/geetest-bypass/issues
Author-email: wulu007 <dabaobeix@gmail.com>
License: MIT
License-File: LICENSE
Keywords: bypass,captcha,geetest,pow,reverse-engineering
Requires-Python: >=3.11
Requires-Dist: pycryptodome>=3.23.0
Requires-Dist: smcryptopy>=0.2.1
Requires-Dist: wreq>=0.12.0
Provides-Extra: all
Requires-Dist: opencv-python-headless>=4.13.0.92; extra == 'all'
Requires-Dist: pillow>=12.2.0; extra == 'all'
Requires-Dist: resvg-py>=0.3.2; extra == 'all'
Provides-Extra: image
Requires-Dist: opencv-python-headless>=4.13.0.92; extra == 'image'
Provides-Extra: slide
Requires-Dist: opencv-python-headless>=4.13.0.92; extra == 'slide'
Provides-Extra: svg-seed
Requires-Dist: opencv-python-headless>=4.13.0.92; extra == 'svg-seed'
Requires-Dist: pillow>=12.2.0; extra == 'svg-seed'
Requires-Dist: resvg-py>=0.3.2; extra == 'svg-seed'
Description-Content-Type: text/markdown

# wulu-geetest-bypass

<p>
  <img src="https://img.shields.io/badge/python-3.11+-blue?logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
  <img src="https://img.shields.io/badge/geetest-v4-orange" alt="Geetest v4">
  <img src="https://img.shields.io/badge/risk_types-13-lightgrey" alt="13 risk types">
</p>

极验行为验证 v4 自动化通过库。自动处理 `ai` / `slide` / `match` / `winlinze` / `svg_seed` 五种风险类型，支持自定义重试、代理和 HTTP 客户端。

## 安装

推荐使用 `uv`（更快、更现代的 Python 包管理器）：

```bash
uv add "wulu-geetest-bypass[all]"
```

也可用 `pip`：

```bash
pip install "wulu-geetest-bypass[all]"
```

可选依赖：

```bash
# slide 滑块（需要 opencv）
uv add "wulu-geetest-bypass[slide]"

# svg-seed 图片选择 + slide
uv add "wulu-geetest-bypass[svg-seed]"

# 全部安装
uv add "wulu-geetest-bypass[all]"
```

## 快速开始

```python
import asyncio
from wulu_geetest_bypass import Geetest

async def main():
    g = Geetest(captcha_id='your_captcha_id', risk_type='slide')
    result = await g.resolve()
    print(result)
    # {
    #     "captcha_id": "xxx",
    #     "lot_number": "xxx",
    #     "pass_token": "xxx",
    #     "gen_time": "xxx",
    #     "captcha_output": "xxx"
    # }

asyncio.run(main())
```

每次验证会自动重试最多 3 次（可通过 `retry` 参数调整），失败时抛出 `VerifyError`。

## 风险类型

| 类型 | 说明 | 依赖 | 支持 |
|------|------|------|------|
| `ai` | 无感验证 | 无 | ✅ |
| `slide` | 滑块拼图 | `[slide]` | ✅ |
| `match` | 3×3 连线 & 9宫格 | 无 | ✅ |
| `winlinze` | 五子棋 | 无 | ✅ |
| `svg_seed` | SVG 图片选择 | `[svg-seed]` | ✅ |
| `icon` | 图标点选 | 无 | ❌ |
| `word` | 文字点选 | 无 | ❌ |
| `nine` | 九宫格 | 无 | ❌ |
| `phrase` | 短语识别 | 无 | ❓ |
| `space` | 空间推理 | 无 | ❓ |
| `pencil` | 涂鸦 | 无 | ❓ |
| `voice` | 语音验证 | 无 | ❓ |
| `svg_icon` | SVG 图标 | 无 | ❓ |

## API

### `Geetest(**options)`

| 参数 | 类型 | 说明 |
|------|------|------|
| `captcha_id` | `str` | 验证 ID（必填）|
| `risk_type` | `RiskType` | 风险类型，默认 `'ai'` |
| `client_type` | `ClientType` | 客户端类型，`'web'` / `'web_mobile'` / `'android'` / `'ios'` |
| `lang` | `Lang` | 语言，`'zh'` / `'en'` / `'zho'` / `'eng'` |
| `proxy` | `str` | 代理 URL |
| `client` | `wreq.Client` | 自定义 HTTP 客户端 |

### 方法

#### `load() -> dict`

获取验证初始化数据，返回值包含 `captcha_type`、`lot_number`、`payload`、`process_token`、`pow_detail` 等字段，可直接传入 `verify()`。

#### `verify(data) -> VerifyResponse`

提交验证并返回完整响应：

```python
class VerifyResponse:
    status: str                          # "success" / "fail" / "error"
    data: VerifyData                     # 验证结果数据

class VerifyData:
    lot_number: str
    result: str                          # "success" / "fail"
    fail_count: int
    seccode: Seccode
    score: str
    payload: str
    process_token: str
    payload_protocol: int
```

#### `resolve(retry=3) -> Seccode`

一键完成 `load()` + `verify()`，验证失败时自动重试，返回 `Seccode`：

```python
class Seccode:
    captcha_id: str
    lot_number: str
    pass_token: str
    gen_time: str
    captcha_output: str
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `retry` | `int` | 失败重试次数，默认 `3` |

### 异常

| 异常 | 说明 |
|------|------|
| `GeetestError` | 所有自定义异常的基类 |
| `VerifyError` | 验证失败（所有重试均未通过）|

## 免责声明

本项目仅供学习和研究使用。使用者应遵守相关法律法规及平台服务条款，
禁止用于任何非法用途。作者不对因使用本项目产生的任何法律问题承担责任。