**SDK Python chính thức của CaptchaSonic** biến mọi loại CAPTCHA được hỗ trợ thành một lệnh gọi hàm duy nhất. SDK cung cấp cả client đồng bộ (`CaptchaSonic`) lẫn bất đồng bộ (`AsyncCaptchaSonic`), giao tiếp với hạ tầng của chúng tôi qua **gRPC theo mặc định** (có thể chọn truyền tải HTTP), và đi kèm đầy đủ type hint, tự động thử lại với lỗi tạm thời, và thăm dò kết quả tích hợp sẵn cho các thử thách dạng token.

---

## Cài đặt

```bash
pip install captchasonic
```

Truyền tải gRPC được cài sẵn. Để dùng thêm truyền tải HTTP/JSON tùy chọn, hãy cài phần mở rộng:

```bash
pip install "captchasonic[http]"
```

> [!TIP]
> SDK hỗ trợ **Python 3.10, 3.11, 3.12 và 3.13** và được phát hành theo giấy phép MIT.

---

## Xác thực

Bạn cần một API key của CaptchaSonic. Tạo tài khoản và lấy key từ [bảng điều khiển](/app), sau đó nạp số dư từ [Nạp tiền](/docs/guides/add-funds).

Truyền key làm tham số vị trí đầu tiên cho client:

<Snippet sdk="python" region="authConstruct" />

> [!WARNING]
> Hãy coi API key như mật khẩu. Không đưa key vào kiểm soát phiên bản — hãy tải từ biến môi trường hoặc trình quản lý bí mật thay vì ghi cứng.

<Snippet sdk="python" region="authEnvVar" />

---

## Bắt đầu nhanh

Phần lớn CAPTCHA dạng token (reCAPTCHA, Turnstile, hCaptcha) được giải bằng một lệnh gọi duy nhất. Client tự thăm dò và trả về token khi tác vụ sẵn sàng.

<MethodRef name="solve_recaptcha_v2_token" lang="python" />

<LangTabs>
  <LangTabs.Tab label="Python">

<Snippet sdk="python" region="solveRecaptchaV2Token_quickstart" />

  </LangTabs.Tab>
  <LangTabs.Tab label="Node">

<Snippet sdk="typescript" region="solveRecaptchaV2Token" />

  </LangTabs.Tab>
</LangTabs>

> Trả về token reCAPTCHA — gửi nó làm `g-recaptcha-response` của trang.

Các phương thức dạng token thăm dò tối đa 120 giây theo mặc định trước khi hết thời gian (xem [Cấu hình](#configuration)).

---

## Các loại CAPTCHA được hỗ trợ

SDK chia các phương thức thành hai nhóm:

- **Phương thức token** (`*_token`, `solve_turnstile`, `solve_cloudflare`) — bạn cung cấp `website_url` / `website_key`, SDK thăm dò hạ tầng của chúng tôi và trả về `result["token"]` sẵn sàng để gửi.
- **Phương thức ảnh / tương tác** — bạn tự cung cấp ảnh thử thách, và SDK trả về `result["typed_solution"]` mô tả hành động cần click, kéo hoặc nhập.

Mọi tham số ảnh đều nhận kiểu `ImageInput` linh hoạt — đường dẫn tệp (`str`), `pathlib.Path`, `bytes` thô, hoặc một đối tượng tệp nhị phân đang mở.

<Snippet sdk="python" region="imageInputTypes" />

### reCAPTCHA v2 (token)

<MethodRef name="solve_recaptcha_v2_token" lang="python" />

<Snippet sdk="python" region="solveRecaptchaV2Token" />

> Trả về `result["token"]` — gửi nó làm `g-recaptcha-response` của trang.

### reCAPTCHA v3 (token)

<Snippet sdk="python" region="solveRecaptchaV3Token" />

> Trả về `result["token"]` — gửi nó làm `g-recaptcha-response` của trang.

### reCAPTCHA v2 (lưới ảnh)

Khi bạn đã có sẵn các ô của thử thách, hãy giải lưới trực tiếp và nhận về các chỉ số cần click.

<Snippet sdk="python" region="solveRecaptchaV2" />

> Trả về `result["typed_solution"]["grid"]["objects"]` — danh sách chỉ số ô cần click.

### Cloudflare Turnstile

<MethodRef name="solve_turnstile" lang="python" />

<LangTabs>
  <LangTabs.Tab label="Python">

<Snippet sdk="python" region="solveTurnstile" />

  </LangTabs.Tab>
  <LangTabs.Tab label="Node">

<Snippet sdk="typescript" region="solveTurnstile" />

  </LangTabs.Tab>
</LangTabs>

> Trả về token Turnstile — gửi nó làm `cf-turnstile-response` của form.

<TaskTypeRef captcha="cloudflare-turnstile" />

### Thử thách Cloudflare

Thử thách Cloudflare đầy đủ **bắt buộc** phải có proxy.

<Snippet sdk="python" region="solveCloudflare" />

> Trả về `result["token"]` — token clearance cho yêu cầu được bảo vệ.

### Popular CAPTCHA (thử thách ảnh kiểu hCaptcha)

`solve_popular_captcha` xử lý các biến thể ảnh tương tác; `solve_popular_captcha_token` trả về token trực tiếp.

<Snippet sdk="python" region="solvePopularCaptcha" />

> Biến thể ảnh trả về `result["typed_solution"]["grid"]["objects"]` (chỉ số ô cần click); biến thể token trả về `result["token"]`.

### GeeTest

<Snippet sdk="python" region="solveGeetest" />

> Trả về `result["typed_solution"]` — hành động cần thực hiện, có cấu trúc theo `geetest_type`.

### AWS WAF

<Snippet sdk="python" region="solveAwsWaf" />

> Trả về `result["typed_solution"]["grid"]["objects"]` — danh sách chỉ số ô cần click.

### Ảnh sang văn bản (OCR)

<Snippet sdk="python" region="solveOcr" />

> Trả về `result["typed_solution"]["text"]["texts"][0]` — văn bản đã nhận dạng để nhập vào.

### Ghép hình trượt

Truyền ảnh nền và mảnh ghép; bạn nhận lại độ lệch pixel theo chiều ngang để kéo trượt.

<Snippet sdk="python" region="solveSlideImage" />

> Trả về `result["typed_solution"]["slide"]["x"]` — độ lệch pixel theo chiều ngang để kéo mảnh ghép.

### TikTok

<Snippet sdk="python" region="solveTikTok" />

> Trả về `result["typed_solution"]` — hành động cần thực hiện, có cấu trúc theo `type`.

### Binance

<Snippet sdk="python" region="solveBinance" />

> Trả về `result["typed_solution"]` — hành động cần thực hiện, có cấu trúc theo `type`.

---

## Sử dụng bất đồng bộ

Với khối lượng công việc đồng thời cao (handler FastAPI, spider Scrapy, pipeline asyncio), hãy dùng `AsyncCaptchaSonic`. API của nó giống hệt bản đồng bộ, nhưng mọi phương thức giải đều có thể `await`. Dùng nó như một async context manager để kênh kết nối bên dưới được dọn dẹp tự động.

<Snippet sdk="python" region="asyncUsage" />

Client đồng bộ cũng hỗ trợ giao thức context manager:

<Snippet sdk="python" region="syncContextManager" />

---

## Hỗ trợ proxy

Các phương thức token nhận tham số `proxy` tùy chọn (bắt buộc với `solve_cloudflare`). Sử dụng URL proxy tiêu chuẩn:

<Snippet sdk="python" region="proxyUsage" />

> [!TIP]
> Cung cấp proxy giúp solver của chúng tôi phản chiếu vị trí địa lý và uy tín IP của yêu cầu bạn, từ đó nâng tỷ lệ thành công trên các trang có quy tắc chống bot nghiêm ngặt.

---

## Cấu hình

Mọi tùy chọn đều được truyền vào constructor của client và áp dụng cho cả client đồng bộ lẫn bất đồng bộ.

<Snippet sdk="python" region="clientConfiguration" />

| Tùy chọn | Mặc định | Mô tả |
| :--- | :--- | :--- |
| `transport` | `"grpc"` | Giao thức truyền dữ liệu. `"grpc"` gửi ảnh không tốn thêm chi phí base64; `"http"` (cần phần mở rộng `[http]`) gửi REST/JSON với ảnh mã hóa base64. |
| `url` | `api.captchasonic.com:443` | Ghi đè endpoint API (ví dụ cho máy chủ tự host hoặc staging). |
| `timeout` | `30.0` | Thời gian chờ mạng cho mỗi lệnh gọi, tính bằng giây. |
| `polling_interval` | `2.0` | Số giây giữa các lần thăm dò khi chờ một tác vụ token. |
| `polling_timeout` | `120.0` | Số giây tối đa chờ một tác vụ token trước khi ném lỗi. |
| `secure` | `True` | Dùng TLS cho kênh gRPC. |

Các lỗi gRPC tạm thời được tự động thử lại (tối đa 3 lần) với thời gian chờ tăng dần theo cấp số nhân, nên bạn chỉ cần xử lý các lỗi nghiệp vụ thực sự.

---

## Xử lý lỗi

Mọi lỗi của SDK đều kế thừa từ `SonicError`, nên bạn có thể bắt tất cả bằng một mệnh đề `except` hoặc rẽ nhánh theo lớp con cụ thể. Mỗi lỗi cũng mang một `error_id` dạng số.

<Snippet sdk="python" region="errorHandling" />

<ErrorIdTable />

---

## Hàm hỗ trợ tài khoản

<Snippet sdk="python" region="accountHelpers" />

Dùng `health_check()` như một probe sẵn sàng nhẹ trong các service, và `get_balance()` để kiểm tra điều kiện trước khi bắt đầu công việc tiêu tốn credit.

---

## Khắc phục sự cố

> [!TIP]
> **`ModuleNotFoundError` khi dùng truyền tải HTTP.** Client HTTP phụ thuộc vào `httpx`, là một phần mở rộng tùy chọn. Hãy cài bằng `pip install "captchasonic[http]"` và đặt `transport="http"`.

- **Tác vụ token báo lỗi sau khoảng 120 giây.** Đó là `polling_timeout`. Hãy tăng giá trị này cho các đích chậm, ví dụ `CaptchaSonic(key, polling_timeout=240.0)`.
- **`solve_cloudflare` lỗi ngay lập tức.** Tham số `proxy` là bắt buộc với thử thách Cloudflare — hãy cung cấp một URL proxy hoạt động.
- **Lỗi kết nối gRPC sau proxy/tường lửa doanh nghiệp.** gRPC cần HTTP/2 qua cổng 443. Nếu mạng của bạn chặn, hãy chuyển sang `transport="http"`.
- **Phương thức ảnh trả về chỉ số, không phải token.** Các phương thức tương tác (`solve_recaptcha_v2`, `solve_popular_captcha`, `solve_aws_waf`, `solve_geetest`, v.v.) trả về `result["typed_solution"]` mô tả hành động cần thực hiện; chỉ `*_token`, `solve_turnstile` và `solve_cloudflare` mới trả về `result["token"]`.

---

## Tài nguyên

- [Gói PyPI](https://pypi.org/project/captchasonic/)
- [Tham chiếu REST API](/docs/api)
