기능 매트릭스
단일 기준 자료 — 모든 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당 한 행입니다.
- Python SDK 메서드 **13**개, Node.js SDK 메서드 **13**개(CAPTCHA당 각 하나씩)입니다.
- token 패밀리 **5**개, image 패밀리 **4**개, interactive 패밀리 **4**개입니다.
이 개수는 생성된 capabilities.ts에서 실시간으로 읽히므로, 위 매트릭스와 어긋날 수 없습니다.
안정성 보장
- 행 추가는 호환성을 깨지 않습니다. 새 CAPTCHA는
src/data/capabilities.ts의CAPABILITIES맨 아래에 추가됩니다. slug제거 또는 이름 변경은 해당 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).