Funktionsmatrix
Einzige Referenz — jeder CaptchaSonic-CAPTCHA-Typ zugeordnet zu seiner Python-SDK-Methode, Node.js-SDK-Methode, REST-taskType und dem Rückgabefeld.
Die Funktionsmatrix ist die maßgebliche Antwort auf die Frage „Was löst CaptchaSonic, und wie rufe ich es auf?“. Jede Zeile ordnet einen CAPTCHA-Typ seiner Python-Methode, seiner Node.js-Methode, dem REST-task.type und dem genauen Feld zu, in dem die Antwort steht. Sie ist die einzige Referenz, auf die sich die Dokumentation, die SDKs und externe KI-Agenten / MCP-Clients stützen.
TIP
Laden Sie die Matrix als JSON herunter für Agenten, Automatisierungen oder eigene Dashboards: capabilities.json. Das JSON spiegelt src/data/capabilities.ts Feld für Feld.
So lesen Sie die Matrix
- Familie —
tokenliefert eine Token-Zeichenkette (die Sie in ein verborgenes Formularfeld einfügen);imageliefert Koordinaten oder Text aus einem von Ihnen übergebenen Bild;interactiveliefert eine strukturierte Aktion (Klick-Indizes, Ziehdistanzen usw.). - Python SDK / Node.js SDK — der Methodenname und der Pfad mit Punkten im Antwortobjekt, unter dem die Antwort steht.
not in SDKbedeutet, dass der CAPTCHA-Typ derzeit nur über die REST-API erreichbar ist. - REST taskType — die exakte Zeichenkette, die Sie als
task.typeanPOST /createTaskübergeben. Eine separateproxyless-Variante wird angezeigt, wenn die API eine solche bereitstellt (z. B.TurnstileTaskProxyless). - Hinweise — festgehaltene Einschränkungen (Pflichtargumente, Proxy-Anforderungen, Bedeutung der Untertypen).
Matrix
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 |
Anzahl
- 13 Zeilen insgesamt — eine pro dokumentiertem CAPTCHA-Typ.
- 13 Python-SDK-Methoden und 13 Node.js-SDK-Methoden (je eine pro CAPTCHA-Typ).
- 5 Token-Familie, 4 Bild-Familie, 4 interaktive Familie.
Diese Zahlen werden live aus der generierten Datei capabilities.ts gelesen und bleiben daher synchron mit dem SDK; sie können nicht von der obigen Matrix abweichen.
Stabilitätsgarantien
- Neue Zeilen hinzufügen ist nicht breaking. Neue CAPTCHA-Typen werden am Ende von
CAPABILITIESinsrc/data/capabilities.tsangefügt. - Das Entfernen oder Umbenennen eines
slugist eine breaking change für jeden Agenten, der sich darauf festgelegt hat. Wir tun dies nicht stillschweigend. - Methodennamen und Rückgabefelder entsprechen wortgleich den SDK-Dokumenten — ändert sich ein Methodenname, wird diese Matrix im selben Release aktualisiert.
Die REST-Schnittstelle im Detail finden Sie in der REST-API-Referenz. Für die Installation und den Schnellstart von Anfang bis Ende lesen Sie die Seiten zum Python-SDK und zum Node.js-SDK.
Fehlercodes
Die Matrix oben ordnet jeden CAPTCHA-Typ seiner Methode und seinem Rückgabefeld zu. Die folgende Tabelle ist die passende Übersicht der numerischen errorId-Codes, die alle SDKs und die REST-API bei einem fehlgeschlagenen Task zurückgeben.
| 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).