Skip to content
CaptchaSonic

Python SDK

आधिकारिक CaptchaSonic SDK से Python में CAPTCHA हल करें — gRPC + HTTP ट्रांसपोर्ट, async-ready, पूरी तरह टाइप्ड।

आधिकारिक CaptchaSonic Python SDK हर समर्थित CAPTCHA को एक ही फ़ंक्शन कॉल में बदल देता है। इसमें synchronous (CaptchaSonic) और asynchronous (AsyncCaptchaSonic) दोनों क्लाइंट आते हैं, यह डिफ़ॉल्ट रूप से gRPC पर हमारे इंफ़्रास्ट्रक्चर से बात करता है (वैकल्पिक HTTP ट्रांसपोर्ट के साथ), और इसमें पूरे type hints, अस्थायी त्रुटियों के लिए स्वचालित retry, और टोकन-शैली चुनौतियों के लिए बिल्ट-इन पोलिंग शामिल है।


इंस्टॉलेशन

pip install captchasonic

gRPC ट्रांसपोर्ट डिफ़ॉल्ट रूप से इंस्टॉल होता है। वैकल्पिक HTTP/JSON ट्रांसपोर्ट भी उपयोग करने के लिए extra इंस्टॉल करें:

pip install "captchasonic[http]"

TIP

SDK Python 3.10, 3.11, 3.12 और 3.13 को समर्थित करता है और MIT लाइसेंस के तहत प्रकाशित है।


प्रमाणीकरण

आपको एक CaptchaSonic API key चाहिए। खाता बनाएँ और dashboard से अपनी key लें, फिर Add funds से अपना बैलेंस भरें।

Key को क्लाइंट के पहले positional आर्गुमेंट के रूप में पास करें:

from captchasonic import CaptchaSonic

solver = CaptchaSonic("YOUR_API_KEY")

WARNING

अपनी API key को पासवर्ड की तरह समझें। उसे सोर्स कंट्रोल से दूर रखें — hard-code करने के बजाय एनवायरनमेंट वेरिएबल या secrets manager से लोड करें।

import os
from captchasonic import CaptchaSonic

solver = CaptchaSonic(os.environ["CAPTCHASONIC_API_KEY"])

त्वरित शुरुआत

अधिकांश टोकन-शैली CAPTCHA (reCAPTCHA, Turnstile, hCaptcha) एक ही कॉल से हल होते हैं। टास्क तैयार होने पर क्लाइंट आपके लिए पोल करता है और टोकन लौटाता है।

solve_recaptcha_v2_tokentoken
Verified v1.0.0· 2026-05-28

reCAPTCHA v2 (token) — Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready).

signaturesolve_recaptcha_v2_token(…)returnssolution.token
from captchasonic import CaptchaSonic

solver = CaptchaSonic("YOUR_API_KEY")

result = solver.solve_recaptcha_v2_token(
    website_url="https://example.com/login",
    website_key="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
)

print(result["token"])
# 03AGdBq25SxXT...  ← drop this into the g-recaptcha-response field

reCAPTCHA टोकन लौटाता है — इसे पेज के g-recaptcha-response के रूप में सबमिट करें।

टोकन-शैली मेथड डिफ़ॉल्ट रूप से टाइमआउट से पहले 120 सेकंड तक पोल करती हैं (देखें कॉन्फ़िगरेशन)।


समर्थित CAPTCHA प्रकार

SDK मेथड को दो परिवारों में बाँटता है:

  • टोकन मेथड (*_token, solve_turnstile, solve_cloudflare) — आप website_url / website_key देते हैं, SDK हमारे इंफ़्रास्ट्रक्चर को पोल करता है और सबमिट करने के लिए तैयार result["token"] लौटाता है।
  • इमेज / interactive मेथड — चुनौती की इमेज आप स्वयं देते हैं, और SDK एक result["typed_solution"] लौटाता है जो बताता है कि क्या क्लिक, ड्रैग या टाइप करना है।

सभी इमेज आर्गुमेंट लचीले ImageInput टाइप को स्वीकार करते हैं — फ़ाइल पाथ (str), pathlib.Path, कच्चे bytes, या खुला बाइनरी फ़ाइल ऑब्जेक्ट।

from pathlib import Path

# Any of these work as an item in an `images=[...]` list:
Path("captcha.png")        # pathlib.Path
"./captcha.png"            # str path
open("captcha.png", "rb").read()  # bytes

reCAPTCHA v2 (टोकन)

solve_recaptcha_v2_tokentoken
Verified v1.0.0· 2026-05-28

reCAPTCHA v2 (token) — Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready).

signaturesolve_recaptcha_v2_token(…)returnssolution.token
result = solver.solve_recaptcha_v2_token(
    website_url="https://example.com",
    website_key="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    proxy="http://user:pass@host:port",  # optional
)
token = result["token"]

result["token"] लौटाता है — इसे पेज के g-recaptcha-response के रूप में सबमिट करें।

reCAPTCHA v3 (टोकन)

result = solver.solve_recaptcha_v3_token(
    website_url="https://example.com",
    website_key="6Lc_aCMTAAAAAB...",
    proxy="http://user:pass@host:port",  # optional
)
token = result["token"]

result["token"] लौटाता है — इसे पेज के g-recaptcha-response के रूप में सबमिट करें।

reCAPTCHA v2 (इमेज ग्रिड)

जब आपके पास चुनौती की टाइलें पहले से हों, तो ग्रिड को सीधे हल करें और क्लिक करने के लिए इंडेक्स प्राप्त करें।

result = solver.solve_recaptcha_v2(
    images=[Path("tile.png")],         # ImageInput list
    question="traffic lights",          # label or /m/... entity id
    question_type="44",                # "split_33" | "33" | "44"
)
to_click = result["typed_solution"]["grid"]["objects"]  # list[int]

result["typed_solution"]["grid"]["objects"] लौटाता है — क्लिक करने के लिए टाइल इंडेक्स की सूची।

Cloudflare Turnstile

solve_turnstiletoken
Verified v1.0.0· 2026-05-28

Cloudflare Turnstile — Solve a Cloudflare Turnstile token challenge (async — polls until ready).

signaturesolve_turnstile(…)returnssolution.token
result = solver.solve_turnstile(
    website_url="https://example.com",
    website_key="0x4AAAAAAA...",
    proxy="http://user:pass@host:port",  # optional
)
token = result["token"]

Turnstile टोकन लौटाता है — इसे फ़ॉर्म के cf-turnstile-response के रूप में सबमिट करें।

REST task typeAntiTurnstileTask

Cloudflare Challenge

पूर्ण Cloudflare चुनौती के लिए proxy आवश्यक है।

result = solver.solve_cloudflare(
    website_url="https://example.com",
    website_key="0x4AAAAAAA...",
    proxy="http://user:pass@host:port",  # required
)
token = result["token"]

result["token"] लौटाता है — संरक्षित अनुरोध के लिए clearance टोकन।

solve_popular_captcha interactive इमेज वेरिएंट संभालता है; solve_popular_captcha_token सीधे टोकन लौटाता है।

# Image / interactive variant
result = solver.solve_popular_captcha(
    images=[Path("challenge.png")],
    question="Select all traffic lights",
    question_type="grid",  # "objectClassify" | "objectClick" | "objectDrag" | "grid"
)
to_click = result["typed_solution"]["grid"]["objects"]  # list[int]

# Token variant
result = solver.solve_popular_captcha_token(
    website_url="https://example.com",
    website_key="00000000-0000-0000-0000-000000000000",
    proxy="http://user:pass@host:port",  # optional
)
token = result["token"]

इमेज वेरिएंट result["typed_solution"]["grid"]["objects"] (क्लिक करने के लिए टाइल इंडेक्स) लौटाता है; टोकन वेरिएंट result["token"] लौटाता है।

GeeTest

result = solver.solve_geetest(
    geetest_type="nine",  # "nine" | "click" | "slide" | "match" | "winlinze"
    question="Select all bicycles",  # required for "nine" and "click"
    images=[Path("tile.png")],        # required for "nine", "click", "slide"
)
solution = result["typed_solution"]  # structure varies by geetest_type

result["typed_solution"] लौटाता है — करने वाली क्रिया, जो geetest_type द्वारा तय होती है।

AWS WAF

result = solver.solve_aws_waf(
    images=[Path("grid.png")],
    question="grid:vehicles:cars",
)
to_click = result["typed_solution"]["grid"]["objects"]  # list[int]

result["typed_solution"]["grid"]["objects"] लौटाता है — क्लिक करने के लिए टाइल इंडेक्स की सूची।

इमेज-से-टेक्स्ट (OCR)

result = solver.solve_ocr(
    images=[Path("captcha.png")],
    module="common",       # "common" | "mtcaptcha" | "bls" | "morocco"
    numeric=False,         # expect only digits
    case_sensitive=True,   # preserve letter case
    min_length=4,
    max_length=8,
)
text = result["typed_solution"]["text"]["texts"][0]  # str

result["typed_solution"]["text"]["texts"][0] लौटाता है — पहचाना गया टेक्स्ट जिसे टाइप करना है।

स्लाइड पज़ल

बैकग्राउंड और पज़ल पीस दें; आपको स्लाइड करने के लिए क्षैतिज पिक्सल ऑफ़सेट मिलता है।

result = solver.solve_slide_image(
    images=[Path("background.png"), Path("piece.png")],
)
offset_x = result["typed_solution"]["slide"]["x"]  # float (pixels)

result["typed_solution"]["slide"]["x"] लौटाता है — पीस को ड्रैग करने के लिए क्षैतिज पिक्सल ऑफ़सेट।

TikTok

result = solver.solve_tiktok(
    type="whirl",  # "click" | "whirl" | "slide"
    images=[Path("outer.png")],
    examples=[Path("inner.png")],  # required for "whirl" and "slide"
)
solution = result["typed_solution"]

result["typed_solution"] लौटाता है — करने वाली क्रिया, जो type द्वारा तय होती है।

Binance

result = solver.solve_binance(
    type="grid",  # "grid" | "slide"
    question="Select all bicycles",  # required for "grid"
    images=[Path("grid.png")],
)
solution = result["typed_solution"]

result["typed_solution"] लौटाता है — करने वाली क्रिया, जो type द्वारा तय होती है।


Async उपयोग

उच्च-समवर्ती कार्यभार (FastAPI handlers, Scrapy spiders, asyncio pipelines) के लिए AsyncCaptchaSonic उपयोग करें। यह synchronous API को बिल्कुल वैसा ही दर्शाता है, लेकिन हर solve मेथड awaitable है। इसे async context manager के रूप में उपयोग करें ताकि अंतर्निहित चैनल अपने-आप साफ़ हो जाए।

import asyncio
from captchasonic import AsyncCaptchaSonic

async def main():
    async with AsyncCaptchaSonic("YOUR_API_KEY") as solver:
        result = await solver.solve_turnstile(
            website_url="https://example.com",
            website_key="0x4AAAAAAA...",
        )
        print(result["token"])

asyncio.run(main())

Synchronous क्लाइंट भी context-manager प्रोटोकॉल समर्थित करता है:

with CaptchaSonic("YOUR_API_KEY") as solver:
    result = solver.solve_ocr(images=[Path("captcha.png")])
    print(result["typed_solution"]["text"]["texts"][0])

Proxy समर्थन

टोकन मेथड वैकल्पिक proxy आर्गुमेंट स्वीकार करती हैं (solve_cloudflare के लिए आवश्यक)। मानक proxy URL का उपयोग करें:

proxy = "http://user:pass@host:port"

result = solver.solve_recaptcha_v2_token(
    website_url="https://example.com",
    website_key="6Le-...",
    proxy=proxy,
)

TIP

proxy देने से हमारा solver आपके अनुरोध के भौगोलिक स्थान और IP प्रतिष्ठा को मिरर कर सकता है, जिससे सख्त anti-bot नियम वाली साइटों पर सफलता दर बेहतर होती है।


कॉन्फ़िगरेशन

सभी विकल्प क्लाइंट constructor को पास होते हैं और sync तथा async, दोनों क्लाइंट पर लागू होते हैं।

solver = CaptchaSonic(
    "YOUR_API_KEY",
    transport="grpc",                # "grpc" (default) or "http"
    url="api.captchasonic.com:443",  # endpoint override (optional)
    timeout=30.0,                    # per-call timeout, seconds
    polling_interval=2.0,            # seconds between task polls
    polling_timeout=120.0,           # max wait for a token task, seconds
    secure=True,                     # use TLS for gRPC
)
विकल्पडिफ़ॉल्टविवरण
transport"grpc"वायर प्रोटोकॉल। "grpc" इमेज शून्य base64 ओवरहेड के साथ भेजता है; "http" ([http] extra आवश्यक) base64-एन्कोडेड इमेज के साथ REST/JSON भेजता है।
urlapi.captchasonic.com:443API endpoint ओवरराइड करें (जैसे self-hosted या staging के लिए)।
timeout30.0प्रति कॉल नेटवर्क टाइमआउट, सेकंड में।
polling_interval2.0टोकन टास्क की प्रतीक्षा के दौरान पोल के बीच सेकंड।
polling_timeout120.0त्रुटि फेंकने से पहले टोकन टास्क के लिए अधिकतम प्रतीक्षा सेकंड।
secureTruegRPC चैनल के लिए TLS उपयोग करें।

अस्थायी gRPC त्रुटियों पर exponential backoff के साथ स्वचालित retry होता है (अधिकतम 3 प्रयास), इसलिए आपको केवल वास्तविक व्यावसायिक त्रुटियाँ संभालनी होती हैं।


एरर हैंडलिंग

सभी SDK त्रुटियाँ SonicError से inherit होती हैं, इसलिए आप एक except क्लॉज़ से सब कुछ पकड़ सकते हैं या विशिष्ट subclass पर शाखा बना सकते हैं। हर त्रुटि एक संख्यात्मक error_id भी रखती है।

from captchasonic.exceptions import (
    SonicError,
    InvalidApiKeyError,
    InsufficientBalanceError,
)

try:
    result = solver.solve_turnstile(
        website_url="https://example.com",
        website_key="0x4AAAAAAA...",
    )
except InsufficientBalanceError:
    print("Top up your balance to continue.")
except InvalidApiKeyError:
    print("Check your API key.")
except SonicError as err:
    print(f"Solve failed (error_id={err.error_id}): {err}")
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).


खाता सहायक

balance = solver.get_balance()  # current balance in USD (float)
print(f"Balance: ${balance:.2f}")

health = solver.health_check()  # HealthCheckResponse — verifies connectivity

सेवाओं में हल्के readiness probe के रूप में health_check() उपयोग करें, और क्रेडिट खर्च करने से पहले जॉब को गेट करने के लिए get_balance() उपयोग करें।


समस्या-निवारण

TIP

HTTP ट्रांसपोर्ट उपयोग करते समय ModuleNotFoundError। HTTP क्लाइंट httpx पर निर्भर है, जो एक वैकल्पिक extra है। pip install "captchasonic[http]" से इंस्टॉल करें और transport="http" सेट करें।

  • टोकन टास्क लगभग 120 सेकंड बाद त्रुटि फेंकता है। यह polling_timeout है। धीमी साइटों के लिए इसे बढ़ाएँ, जैसे CaptchaSonic(key, polling_timeout=240.0)।
  • solve_cloudflare तुरंत विफल होता है। Cloudflare चुनौती के लिए proxy आर्गुमेंट आवश्यक है — एक कार्यशील proxy URL दें।
  • कॉर्पोरेट proxy/firewall के पीछे gRPC कनेक्शन त्रुटियाँ। gRPC को पोर्ट 443 पर HTTP/2 चाहिए। यदि आपका नेटवर्क इसे ब्लॉक करता है, तो transport="http" पर स्विच करें।
  • इमेज मेथड टोकन के बजाय इंडेक्स लौटाती हैं। Interactive मेथड (solve_recaptcha_v2, solve_popular_captcha, solve_aws_waf, solve_geetest आदि) करने वाली क्रिया बताने वाला result["typed_solution"] लौटाती हैं; केवल *_token, solve_turnstile और solve_cloudflare result["token"] लौटाती हैं।

संसाधन