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

---

## इंस्टॉलेशन

```bash
pip install captchasonic
```

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

```bash
pip install "captchasonic[http]"
```

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

---

## प्रमाणीकरण

आपको एक CaptchaSonic API key चाहिए। खाता बनाएँ और [dashboard](/app) से अपनी key लें, फिर [Add funds](/docs/guides/add-funds) से अपना बैलेंस भरें।

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

<Snippet sdk="python" region="authConstruct" />

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

<Snippet sdk="python" region="authEnvVar" />

---

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

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

<MethodRef name="solve_recaptcha_v2_token" lang="python" />

<LangTabs>
  <LangTabs.Tab label="Python">

<Snippet sdk="python" region="solveRecaptchaV2Token_quickstart" />

  </LangTabs.Tab>
  <LangTabs.Tab label="Node">

<Snippet sdk="typescript" region="solveRecaptchaV2Token" />

  </LangTabs.Tab>
</LangTabs>

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

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

---

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

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

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

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

<Snippet sdk="python" region="imageInputTypes" />

### reCAPTCHA v2 (टोकन)

<MethodRef name="solve_recaptcha_v2_token" lang="python" />

<Snippet sdk="python" region="solveRecaptchaV2Token" />

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

### reCAPTCHA v3 (टोकन)

<Snippet sdk="python" region="solveRecaptchaV3Token" />

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

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

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

<Snippet sdk="python" region="solveRecaptchaV2" />

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

### Cloudflare Turnstile

<MethodRef name="solve_turnstile" lang="python" />

<LangTabs>
  <LangTabs.Tab label="Python">

<Snippet sdk="python" region="solveTurnstile" />

  </LangTabs.Tab>
  <LangTabs.Tab label="Node">

<Snippet sdk="typescript" region="solveTurnstile" />

  </LangTabs.Tab>
</LangTabs>

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

<TaskTypeRef captcha="cloudflare-turnstile" />

### Cloudflare Challenge

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

<Snippet sdk="python" region="solveCloudflare" />

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

### Popular CAPTCHA (hCaptcha-शैली इमेज चुनौतियाँ)

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

<Snippet sdk="python" region="solvePopularCaptcha" />

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

### GeeTest

<Snippet sdk="python" region="solveGeetest" />

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

### AWS WAF

<Snippet sdk="python" region="solveAwsWaf" />

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

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

<Snippet sdk="python" region="solveOcr" />

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

### स्लाइड पज़ल

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

<Snippet sdk="python" region="solveSlideImage" />

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

### TikTok

<Snippet sdk="python" region="solveTikTok" />

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

### Binance

<Snippet sdk="python" region="solveBinance" />

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

---

## Async उपयोग

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

<Snippet sdk="python" region="asyncUsage" />

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

<Snippet sdk="python" region="syncContextManager" />

---

## Proxy समर्थन

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

<Snippet sdk="python" region="proxyUsage" />

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

---

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

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

<Snippet sdk="python" region="clientConfiguration" />

| विकल्प | डिफ़ॉल्ट | विवरण |
| :--- | :--- | :--- |
| `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` भी रखती है।

<Snippet sdk="python" region="errorHandling" />

<ErrorIdTable />

---

## खाता सहायक

<Snippet sdk="python" region="accountHelpers" />

सेवाओं में हल्के 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"]` लौटाती हैं।

---

## संसाधन

- [PyPI package](https://pypi.org/project/captchasonic/)
- [REST API reference](/docs/api)
