Matrice des capacités
Source unique de vérité — chaque type de CAPTCHA CaptchaSonic associé à sa méthode du SDK Python, sa méthode du SDK Node.js, son taskType REST et son champ de retour.
La Matrice des capacités répond de façon canonique à la question « que résout CaptchaSonic, et comment l'appeler ? ». Chaque ligne associe un CAPTCHA à sa méthode Python, sa méthode Node.js, son task.type REST et le champ exact qui contient la réponse. C'est la source unique de vérité que lisent la documentation, les SDK et les agents IA / clients MCP externes.
TIP
Téléchargez la matrice au format JSON pour vos agents, vos automatisations ou vos propres tableaux de bord : capabilities.json. Le JSON reprend src/data/capabilities.ts champ par champ.
Comment la lire
- Famille —
tokenrenvoie un jeton sous forme de chaîne (à placer dans un champ de formulaire masqué) ;imagerenvoie des coordonnées ou du texte extraits d'une image que vous fournissez ;interactiverenvoie une action structurée (indices de clic, déplacements de glisser, etc.). - SDK Python / SDK Node.js — le nom de la méthode et le chemin pointé sous l'objet de réponse où se trouve la réponse.
not in SDKsignifie que le CAPTCHA n'est accessible aujourd'hui que via l'API REST. - taskType REST — la chaîne exacte à passer comme
task.typedansPOST /createTask. Une varianteproxylessdistincte est indiquée lorsque l'API en propose une (par exempleTurnstileTaskProxyless). - Notes — mises en garde fixes (arguments obligatoires, exigences de proxy, sémantique des sous-types).
Matrice
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 |
Chiffres
- 13 lignes au total — une par CAPTCHA documenté.
- 13 méthodes du SDK Python et 13 méthodes du SDK Node.js (une chacune par CAPTCHA).
- 5 de la famille token, 4 de la famille image, 4 de la famille interactive.
Ces chiffres sont lus en direct depuis le fichier capabilities.ts généré : ils suivent le SDK et ne peuvent pas diverger de la matrice ci-dessus.
Garanties de stabilité
- L'ajout de lignes n'est pas un changement cassant. Les nouveaux CAPTCHA s'ajoutent en bas de
CAPABILITIESdanssrc/data/capabilities.ts. - La suppression ou le renommage d'un
slugest un changement cassant pour tout agent qui s'y est rattaché. Nous ne le ferons jamais silencieusement. - Les noms de méthodes et les champs de retour reprennent fidèlement la documentation des SDK — si une méthode est renommée, cette matrice est mise à jour dans la même version.
Pour le contrat REST brut, consultez la référence de l'API REST. Pour l'installation et le démarrage rapide, consultez les pages SDK Python et SDK Node.js.
Codes d'erreur
La matrice ci-dessus associe chaque CAPTCHA à sa méthode et à son champ de retour. Le tableau ci-dessous est la référence centralisée correspondante pour les codes numériques errorId que chaque SDK et l'API REST renvoient lorsqu'une tâche échoue.
| 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).