Matriz de capacidades
Fuente única de verdad — cada tipo de CAPTCHA de CaptchaSonic asignado a su método del SDK de Python, su método del SDK de Node.js, su taskType de REST y su campo de respuesta.
La Matriz de capacidades es la respuesta canónica a «¿qué resuelve CaptchaSonic y cómo lo llamo?». Cada fila vincula un CAPTCHA con su método de Python, su método de Node.js, su task.type de REST y el campo exacto que contiene la respuesta. Es la fuente única de verdad que leen la documentación, los SDK y los agentes de IA / clientes MCP externos.
TIP
Descarga la matriz en JSON para usarla en agentes, automatizaciones o tus propios paneles: capabilities.json. El JSON refleja src/data/capabilities.ts campo por campo.
Cómo leerla
- Familia —
tokendevuelve una cadena de token (que insertas en un campo de formulario oculto);imagedevuelve coordenadas o texto a partir de una imagen que proporcionas;interactivedevuelve una acción estructurada (índices de clic, desplazamientos de arrastre, etc.). - SDK de Python / SDK de Node.js — el nombre del método y la ruta con puntos bajo el objeto de respuesta donde está la respuesta.
not in SDKsignifica que el CAPTCHA solo es accesible hoy a través de la API REST. - taskType de REST — la cadena exacta que pasas como
task.typeaPOST /createTask. Se muestra una varianteproxylessaparte cuando la API la expone (p. ej.,TurnstileTaskProxyless). - Notas — advertencias fijadas (argumentos obligatorios, requisitos de proxy, semántica de subtipos).
Matriz
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 |
Recuento
- 13 filas en total — una por cada CAPTCHA documentado.
- 13 métodos del SDK de Python y 13 métodos del SDK de Node.js (uno por cada CAPTCHA).
- 5 de familia token, 4 de familia image y 4 de familia interactive.
Estos recuentos se leen en vivo del capabilities.ts generado, por lo que siguen al SDK y no pueden desfasarse de la matriz de arriba.
Garantías de estabilidad
- Añadir filas no rompe nada. Los nuevos CAPTCHA se añaden al final de
CAPABILITIESensrc/data/capabilities.ts. - Eliminar o renombrar un
sluges un cambio incompatible para cualquier agente que lo haya fijado. No lo haremos en silencio. - Los nombres de métodos y los campos de respuesta reflejan literalmente la documentación del SDK: si un método cambia de nombre, esta matriz se actualiza en la misma versión.
Para el contrato REST en bruto, consulta la referencia de la API REST. Para la instalación y el inicio rápido de extremo a extremo, consulta las páginas del SDK de Python y del SDK de Node.js.
Códigos de error
La matriz de arriba vincula cada CAPTCHA con su método y su campo de respuesta. La tabla siguiente es la referencia completa de los códigos numéricos errorId que todos los SDK y la API REST devuelven cuando una tarea falla.
| 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).