Skip to content
CaptchaSonic

機能マトリクス

唯一の情報源です。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)。
  • 注記 — 固定された注意事項です(必須の引数、プロキシの要件、サブタイプの意味など)。

マトリクス

13 capabilities
5 token4 image4 interactive
capabilities.json
token

Token solvers5

Submit website_url + website_key. The SDK polls our infrastructure and returns a ready-to-submit token (~6–12s typical).

CaptchaPythonNode.jsREST task type
reCAPTCHA v2 (token)
Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready).
solve_recaptcha_v2_token
solution.token
solveRecaptchaV2Token
solution.token
RecaptchaV2Task
+ RecaptchaV2TaskProxyless
reCAPTCHA v3 (token)
Solve a reCAPTCHA v3 token challenge via browser automation (async — polls until ready).
solve_recaptcha_v3_token
solution.token
solveRecaptchaV3Token
solution.token
RecaptchaV3Task
+ RecaptchaV3TaskProxyless
Cloudflare Turnstile
Solve a Cloudflare Turnstile token challenge (async — polls until ready).
solve_turnstile
solution.token
solveTurnstile
solution.token
AntiTurnstileTask
Cloudflare Challenge
Solve a Cloudflare challenge via browser automation (async — polls until ready).
solve_cloudflare
solution.token
proxy
solveCloudflare
solution.token
proxy
AntiCloudflareTask
PopularCaptcha (token)
Solve a popular CAPTCHA token challenge via browser automation (async — polls until ready).
solve_popular_captcha_token
solution.token
solvePopularCaptchaToken
solution.token
PopularTask
+ PopularTaskProxyless
image

Image solvers4

You supply the challenge images; the SDK returns a typed_solution payload describing what to do (tile indices, text, slide offset).

CaptchaPythonNode.jsREST task type
reCAPTCHA v2 (image grid)
Solve a reCAPTCHA v2 image classification challenge.
solve_recaptcha_v2
typed_solution.grid.objects
solveRecaptchaV2
typedSolution.grid.objects
RecaptchaV2Classification
AWS WAF
Solve an AWS WAF image challenge.
solve_aws_waf
typed_solution.grid.objects
solveAwsWaf
typedSolution.grid.objects
AwsWafClassification
Image-to-text (OCR)
Solve an OCR / image-to-text task.
solve_ocr
typed_solution.text.texts[0]
solveOcr
typedSolution.text.texts[0]
ImageToTextTask
Slide puzzle
Solve a slide CAPTCHA using local alpha/contour detection (no AI).
solve_slide_image
typed_solution.slide.x
solveSlideImage
typedSolution.slide.x
SlideImage
interactive

Interactive solvers4

Images plus extra metadata for slide / click / whirl variants. Return shape varies by sub-type.

CaptchaPythonNode.jsREST task type
PopularCaptcha
Solve a popular CAPTCHA image classification challenge (grid/bbox/drag).
solve_popular_captcha
typed_solution.grid.objects
solvePopularCaptcha
typedSolution.grid.objects
PopularCaptchaImage
GeeTest
Solve a Geetest CAPTCHA challenge.
solve_geetest
typed_solution
solveGeetest
typedSolution
GeetestClassification
TikTok
Solve a TikTok CAPTCHA challenge.
solve_tiktok
typed_solution
solveTikTok
typedSolution
TikTokClassification
Binance
Solve a Binance CAPTCHA challenge.
solve_binance
typed_solution
solveBinance
typedSolution
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 コードの一覧です。

errors7 canonical `errorId` codes
idPython exceptionNode errorNameMeaningAction
0SonicErrorSonicErrorBase class for every SDK error — catches anything below.Inspect `error.errorId` (Node) / `err.error_id` (Python) and branch.
1InvalidApiKeyErrorInvalidApiKeyErrorAPI key is missing, malformed, or revoked.Verify the key in your dashboard.
2InsufficientBalanceErrorInsufficientBalanceErrorAccount balance can't cover the task.Add funds.
3DailyLimitExceededErrorDailyLimitExceededErrorDaily quota exhausted.Wait for the daily reset or upgrade your plan.
4MinuteLimitExceededErrorMinuteLimitExceededErrorPer-minute rate limit hit.Slow down requests / add exponential backoff.
5QuotaExceededErrorQuotaExceededErrorPlan quota exhausted.Upgrade your plan.
6PlanExpiredErrorPlanExpiredErrorSubscription 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).