Ma trận khả năng
Nguồn chuẩn duy nhất — mọi loại captcha của CaptchaSonic được ánh xạ tới phương thức Python SDK, phương thức Node.js SDK, REST taskType và trường trả về.
Ma trận khả năng là câu trả lời chuẩn cho câu hỏi "CaptchaSonic giải được những gì, và tôi gọi nó như thế nào?". Mỗi dòng ghim một captcha vào phương thức Python, phương thức Node.js, task.type của REST và trường chính xác chứa đáp án. Đây là nguồn chuẩn duy nhất mà tài liệu, các SDK và AI agent / MCP client bên ngoài đều đọc từ đó.
TIP
Tải ma trận dưới dạng JSON để dùng trong agent, tự động hóa hoặc dashboard riêng của bạn: capabilities.json. Tệp JSON phản chiếu src/data/capabilities.ts theo từng trường.
Cách đọc
- Family —
tokentrả về một chuỗi token (đưa vào trường form ẩn);imagetrả về tọa độ hoặc văn bản từ ảnh bạn cung cấp;interactivetrả về một hành động có cấu trúc (chỉ số nhấp, độ lệch kéo, v.v.). - Python SDK / Node.js SDK — tên phương thức và đường dẫn có dấu chấm trong đối tượng phản hồi nơi chứa đáp án.
not in SDKnghĩa là captcha đó hiện chỉ dùng được qua REST API. - REST taskType — chuỗi chính xác bạn truyền làm
task.typechoPOST /createTask. Biến thểproxylessriêng được hiển thị khi API có hỗ trợ (ví dụTurnstileTaskProxyless). - Ghi chú — các lưu ý cố định (tham số bắt buộc, yêu cầu proxy, ý nghĩa subtype).
Ma trận
Token solvers5
Submit website_url + website_key. The SDK polls our infrastructure and returns a ready-to-submit token (~6–12s typical).
| Captcha | Python | Node.js | REST task type |
|---|---|---|---|
| reCAPTCHA v2 (token) Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready). | solve_recaptcha_v2_tokensolution.token | solveRecaptchaV2Tokensolution.token | RecaptchaV2Task+ RecaptchaV2TaskProxyless |
| reCAPTCHA v3 (token) Solve a reCAPTCHA v3 token challenge via browser automation (async — polls until ready). | solve_recaptcha_v3_tokensolution.token | solveRecaptchaV3Tokensolution.token | RecaptchaV3Task+ RecaptchaV3TaskProxyless |
| Cloudflare Turnstile Solve a Cloudflare Turnstile token challenge (async — polls until ready). | solve_turnstilesolution.token | solveTurnstilesolution.token | AntiTurnstileTask |
| Cloudflare Challenge Solve a Cloudflare challenge via browser automation (async — polls until ready). | solve_cloudflaresolution.tokenproxy | solveCloudflaresolution.tokenproxy | AntiCloudflareTask |
| PopularCaptcha (token) Solve a popular CAPTCHA token challenge via browser automation (async — polls until ready). | solve_popular_captcha_tokensolution.token | solvePopularCaptchaTokensolution.token | PopularTask+ PopularTaskProxyless |
Image solvers4
You supply the challenge images; the SDK returns a typed_solution payload describing what to do (tile indices, text, slide offset).
| Captcha | Python | Node.js | REST task type |
|---|---|---|---|
| reCAPTCHA v2 (image grid) Solve a reCAPTCHA v2 image classification challenge. | solve_recaptcha_v2typed_solution.grid.objects | solveRecaptchaV2typedSolution.grid.objects | RecaptchaV2Classification |
| AWS WAF Solve an AWS WAF image challenge. | solve_aws_waftyped_solution.grid.objects | solveAwsWaftypedSolution.grid.objects | AwsWafClassification |
| Image-to-text (OCR) Solve an OCR / image-to-text task. | solve_ocrtyped_solution.text.texts[0] | solveOcrtypedSolution.text.texts[0] | ImageToTextTask |
| Slide puzzle Solve a slide CAPTCHA using local alpha/contour detection (no AI). | solve_slide_imagetyped_solution.slide.x | solveSlideImagetypedSolution.slide.x | SlideImage |
Interactive solvers4
Images plus extra metadata for slide / click / whirl variants. Return shape varies by sub-type.
| Captcha | Python | Node.js | REST task type |
|---|---|---|---|
| PopularCaptcha Solve a popular CAPTCHA image classification challenge (grid/bbox/drag). | solve_popular_captchatyped_solution.grid.objects | solvePopularCaptchatypedSolution.grid.objects | PopularCaptchaImage |
| GeeTest Solve a Geetest CAPTCHA challenge. | solve_geetesttyped_solution | solveGeetesttypedSolution | GeetestClassification |
| TikTok Solve a TikTok CAPTCHA challenge. | solve_tiktoktyped_solution | solveTikToktypedSolution | TikTokClassification |
| Binance Solve a Binance CAPTCHA challenge. | solve_binancetyped_solution | solveBinancetypedSolution | BinanceSlideTask |
Số liệu
- 13 dòng tổng cộng — mỗi captcha có tài liệu một dòng.
- 13 phương thức Python SDK và 13 phương thức Node.js SDK (mỗi captcha một phương thức).
- 5 thuộc họ token, 4 thuộc họ image, 4 thuộc họ interactive.
Các số liệu này được đọc trực tiếp từ capabilities.ts đã được sinh ra, nên luôn khớp với SDK và không lệch khỏi ma trận ở trên.
Cam kết ổn định
- Thêm dòng không gây lỗi tương thích. Captcha mới được thêm vào cuối
CAPABILITIEStrongsrc/data/capabilities.ts. - Xóa hoặc đổi tên
sluglà thay đổi phá vỡ tương thích đối với mọi agent đã ghim vào nó. Chúng tôi sẽ không làm việc này âm thầm. - Tên phương thức và trường trả về phản chiếu nguyên văn tài liệu SDK — nếu một phương thức đổi tên, ma trận này sẽ được cập nhật trong cùng bản phát hành.
Để xem hợp đồng REST thô, hãy xem tham chiếu REST API. Để cài đặt và bắt đầu nhanh từ đầu đến cuối, xem các trang Python SDK và Node.js SDK.
Mã lỗi
Ma trận ở trên ghim mỗi captcha với phương thức và trường trả về của nó. Bảng dưới đây là tài liệu tham chiếu tổng hợp tương ứng cho các mã errorId dạng số mà mọi SDK và REST API trả về khi một tác vụ thất bại.
| id | Python exception | Node errorName | Meaning | Action |
|---|---|---|---|---|
0 | SonicError | SonicError | Base class for every SDK error — catches anything below. | Inspect `error.errorId` (Node) / `err.error_id` (Python) and branch. |
1 | InvalidApiKeyError | InvalidApiKeyError | API key is missing, malformed, or revoked. | Verify the key in your dashboard. |
2 | InsufficientBalanceError | InsufficientBalanceError | Account balance can't cover the task. | Add funds. |
3 | DailyLimitExceededError | DailyLimitExceededError | Daily quota exhausted. | Wait for the daily reset or upgrade your plan. |
4 | MinuteLimitExceededError | MinuteLimitExceededError | Per-minute rate limit hit. | Slow down requests / add exponential backoff. |
5 | QuotaExceededError | QuotaExceededError | Plan quota exhausted. | Upgrade your plan. |
6 | PlanExpiredError | PlanExpiredError | Subscription has expired. | Renew your subscription. |
Every concrete row inherits from SonicError — catch it once to handle all SDK failures, or branch on errorId / exception subclass for granular control. Transient gRPC errors are retried automatically with exponential backoff (up to 3 attempts).