Metadata-Version: 2.4
Name: kimicap
Version: 1.0.0
Summary: Official Python SDK for KimiCap Captcha Solving API (reCAPTCHA v2/v3, Turnstile, OCR)
Author-email: KimiCap Team <contact@kimidev.net>
License-Expression: MIT
Project-URL: Homepage, https://api.kimidev.net
Project-URL: Documentation, https://api.kimidev.net
Keywords: captcha,recaptcha,turnstile,solver,kimicap,ocr,antibot
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Dynamic: license-file

# KimiCap Python SDK 🚀

[![PyPI version](https://img.shields.io/pypi/v/kimicap.svg)](https://pypi.org/project/kimicap/)
[![Python versions](https://img.shields.io/pypi/pyversions/kimicap.svg)](https://pypi.org/project/kimicap/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**KimiCap Python SDK** là thư viện chính thức kết nối và giải Captcha tự động qua hệ thống **KimiCap API** ([api.kimidev.net](https://api.kimidev.net)).

---

## ⚡ Tính năng nổi bật

- 🎯 **Google reCAPTCHA v2**: Tự động giải checkbox / invisible reCAPTCHA cực nhanh.
- 🚀 **Google reCAPTCHA v3**: Tùy chọn `pageAction` và `minScore` linh hoạt.
- 🛡️ **Cloudflare Turnstile**: Vượt qua thử thách xác thực Cloudflare trong vài giây.
- 🖼️ **Image Captcha (OCR)**: Nhận diện chữ/số từ ảnh bằng AI ddddocr.
- 💰 **Kiểm tra số dư**: Hàm `get_balance()` lấy số dư tài khoản thời gian thực.
- 🛡️ **Xử lý lỗi toàn diện**: Các lớp ngoại lệ chuyên biệt `KimiCapAuthError`, `KimiCapBalanceError`, `KimiCapTimeoutError`.

---

## 📦 Cài đặt (Installation)

Cài đặt nhanh thông qua pip:

```bash
pip install kimicap
```

Hoặc cài đặt từ source code:

```bash
git clone https://github.com/your-repo/kimicap.git
cd kimicap
pip install .
```

---

## 🚀 Hướng dẫn sử dụng nhanh (Quick Start)

### 1. Khởi tạo Client

```python
from kimicap import KimiCap

API_KEY = "sk_your_api_key_here"

# Khởi tạo SDK
client = KimiCap(api_key=API_KEY)

# Kiểm tra số dư tài khoản
balance = client.get_balance()
print(f"Số dư tài khoản: {balance:,.0f} đ")
```

---

### 2. Giải Google reCAPTCHA v2

```python
token = client.recaptcha_v2(
    website_url="https://accounts.spreadshirt.com/login?context=next-www&lang=en",
    website_key="6LeRuowUAAAAALscfGRnDzSK8lQ59U4TRt6PTXhB"
)
print("reCAPTCHA Token:", token)
```

---

### 3. Giải Google reCAPTCHA v3

```python
token = client.recaptcha_v3(
    website_url="https://example.com/contact",
    website_key="6LcyX...",
    page_action="submit",
    min_score=0.7
)
print("reCAPTCHA v3 Token:", token)
```

---

### 4. Giải Cloudflare Turnstile

```python
token = client.turnstile(
    website_url="https://example.com/login",
    website_key="0x4AAAAAAADnPIDROrmt1Wwj"
)
print("Turnstile Token:", token)
```

---

### 5. Giải Captcha Hình ảnh (Image to Text / OCR)

Hỗ trợ truyền đường dẫn file, bytes, hoặc chuỗi Base64:

```python
# Cách 1: Truyền đường dẫn file ảnh
text = client.image_to_text(image_path="captcha.png")
print("Ký tự captcha:", text)

# Cách 2: Truyền chuỗi Base64
text = client.image_to_text(image="iVBORw0KGgoAAAANSUhEUg...")
print("Ký tự captcha:", text)
```

---

## 🛡️ Bắt lỗi & Ngoại lệ (Exception Handling)

```python
from kimicap import (
    KimiCap,
    KimiCapAuthError,
    KimiCapBalanceError,
    KimiCapTimeoutError,
    KimiCapError
)

client = KimiCap(api_key="your_api_key")

try:
    token = client.recaptcha_v2(website_url="...", website_key="...")
except KimiCapAuthError:
    print("[-] API Key không chính xác hoặc bị khóa!")
except KimiCapBalanceError:
    print("[-] Tài khoản đã hết tiền, vui lòng nạp thêm!")
except KimiCapTimeoutError:
    print("[-] Hết thời gian chờ kết quả giải captcha!")
except KimiCapError as e:
    print(f"[-] Lỗi KimiCap: {e}")
```

---

## 📄 Bản quyền (License)

Dự án được phân phối dưới giấy phép **MIT License**. Chi tiết xem tại [LICENSE](LICENSE).
