機能マトリクス
唯一の情報源です。CaptchaSonic が対応する各 CAPTCHA 種別を、Python SDK メソッド、Node.js SDK メソッド、REST taskType、戻り値フィールドに対応付けています。
機能マトリクス は「CaptchaSonic は何を解決でき、どのように呼び出すのか」に対する正式な答えです。各行は、CAPTCHA ごとに Python メソッド、Node.js メソッド、REST の task.type、そして回答が入っている正確なフィールドを対応付けています。ドキュメント、SDK、外部の AI エージェント / MCP クライアント はすべてこの唯一の情報源を参照しています。
TIP
エージェント、自動化、独自のダッシュボードで使えるように、マトリクスを JSON でダウンロードできます: capabilities.json。JSON の内容は src/data/capabilities.ts とフィールド単位で一致しています。
読み方
- ファミリー —
tokenは文字列トークンを返します(非表示のフォームフィールドに入れて使います)。imageは指定した画像から座標やテキストを返します。interactiveはクリックのインデックスやドラッグの移動量など、構造化されたアクションを返します。 - Python SDK / Node.js SDK — メソッド名と、レスポンスオブジェクト内で回答が入っているドット区切りのパスです。
not in SDKは、その CAPTCHA が現時点では REST API 経由でのみ利用できることを示します。 - REST taskType —
POST /createTaskにtask.typeとして渡す正確な文字列です。API が提供している場合は、別のproxylessバリアントも表示されます(例:TurnstileTaskProxyless)。 - 注記 — 固定された注意事項です(必須の引数、プロキシの要件、サブタイプの意味など)。
マトリクス
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 |
件数
- 全体で 13 行です。文書化された CAPTCHA 1 種類につき 1 行です。
- Python SDK メソッドは 13 件、Node.js SDK メソッドは 13 件です(いずれも CAPTCHA ごとに 1 つ)。
- token ファミリーが 5 件、image ファミリーが 4 件、interactive ファミリーが 4 件です。
これらの件数は生成された capabilities.ts から直接読み込まれるため、SDK と常に一致し、マトリクスとずれることはありません。
互換性の保証
- 行の追加 は非破壊的変更です。新しい CAPTCHA は
src/data/capabilities.tsのCAPABILITIESの末尾に追加されます。 slugの削除または改名 は、そのスラッグに固定しているエージェントにとって破壊的変更です。これを黙って行うことはありません。- メソッド名と戻り値フィールド は SDK ドキュメントと一字一句同じです。メソッド名が変わる場合は、同じリリースでこのマトリクスも更新されます。
REST の生の契約については REST API リファレンス をご覧ください。インストールとクイックスタートについては、Python SDK と Node.js SDK のページをご覧ください。
エラーコード
上のマトリクスは、各 CAPTCHA とそのメソッド・戻り値フィールドの対応を示します。以下の表は、タスクが失敗したときにすべての SDK と REST API が返す、数値の errorId コードの一覧です。
| 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).