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_tokentokenreCAPTCHA v2 (token) — Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready).
solve_recaptcha_v2_token(…)returnssolution.tokenfrom 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 fieldimport { CaptchaSonic } from "captchasonic";
const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY);
const result = await solver.solveRecaptchaV2Token({
websiteURL: "https://example.com/login",
websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
console.log(result.solution.gRecaptchaResponse);
// 03AGdBq25SxXT... ← drop into the g-recaptcha-response fieldreCAPTCHA टोकन लौटाता है — इसे पेज के
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_tokentokenreCAPTCHA v2 (token) — Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready).
solve_recaptcha_v2_token(…)returnssolution.tokenresult = 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_turnstiletokenCloudflare Turnstile — Solve a Cloudflare Turnstile token challenge (async — polls until ready).
solve_turnstile(…)returnssolution.tokenresult = solver.solve_turnstile(
website_url="https://example.com",
website_key="0x4AAAAAAA...",
proxy="http://user:pass@host:port", # optional
)
token = result["token"]await solver.solveTurnstile({
websiteURL: "https://example.com",
websiteKey: "0x4AAAAAAA...",
proxy: "http://user:[email protected]:8080",
});REST task typeTurnstile टोकन लौटाता है — इसे फ़ॉर्म के
cf-turnstile-responseके रूप में सबमिट करें।
AntiTurnstileTask
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 टोकन।
Popular CAPTCHA (hCaptcha-शैली इमेज चुनौतियाँ)
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 भेजता है। |
url | api.captchasonic.com:443 | API endpoint ओवरराइड करें (जैसे self-hosted या staging के लिए)। |
timeout | 30.0 | प्रति कॉल नेटवर्क टाइमआउट, सेकंड में। |
polling_interval | 2.0 | टोकन टास्क की प्रतीक्षा के दौरान पोल के बीच सेकंड। |
polling_timeout | 120.0 | त्रुटि फेंकने से पहले टोकन टास्क के लिए अधिकतम प्रतीक्षा सेकंड। |
secure | True | gRPC चैनल के लिए 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}")
| 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).
खाता सहायक
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_cloudflareresult["token"]लौटाती हैं।