आधिकारिक, [सत्यापित CaptchaSonic community node](https://n8n.io/integrations/captchasonic/) के साथ अपने **n8n workflows** में CAPTCHA solving को स्वचालित करें। node को अपने canvas पर खींचें, उसे एक CAPTCHA की ओर इंगित करें, और यह हल किया हुआ token या answer लौटाता है — कोई HTTP plumbing नहीं, कोई image scraping नहीं, कोई proxy सेटअप नहीं।

> [!TIP]
> यह node **20+ captcha types** समर्थित करता है और **स्टैंडअलोन workflow node** तथा **n8n के AI Agent node के लिए tool** दोनों के रूप में काम करता है। पूरी सूची के लिए [capability matrix](/docs/clients-sdks/capabilities) देखें।

**लिंक:** [npm](https://www.npmjs.com/package/n8n-nodes-captchasonic) · [GitHub](https://github.com/captchasonic/n8n-nodes-captchasonic) · [n8n.io listing](https://n8n.io/integrations/captchasonic/)

---

## आवश्यकताएँ

- एक चालू **n8n instance** (self-hosted या n8n Cloud)
- एक **CaptchaSonic API key** — [my.captchasonic.com](https://my.captchasonic.com) से प्राप्त करें, फिर [funds जोड़ें](/docs/guides/add-funds)
- **Node.js 18+** (केवल self-hosted के लिए)

---

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

1. अपना n8n instance खोलें और **Settings → Community Nodes** पर जाएँ।
2. **Install** पर क्लिक करें और दर्ज करें:
   ```
   n8n-nodes-captchasonic
   ```
3. **Self-hosted:** इंस्टॉल के बाद n8n को रीस्टार्ट करें। **Cloud:** node अपने आप लोड हो जाता है।
4. **सत्यापित करें** — node palette खोलें (**+** पर क्लिक करें), `CaptchaSonic` खोजें, और पुष्टि करें कि node दिखता है।

> [!NOTE]
> यह node [n8n द्वारा सत्यापित](https://n8n.io/integrations/captchasonic/) है और आधिकारिक integrations directory में सूचीबद्ध है।

---

## Credential सेटअप

1. n8n में, **Credentials → Add Credential** पर जाएँ और **CaptchaSonic API** खोजें।
2. [dashboard](https://my.captchasonic.com) से अपनी **API key** चिपकाएँ।
3. **Save** पर क्लिक करें — credential स्वचालित रूप से कनेक्शन की जाँच करता है।

अब यह credential आपके workflows में किसी भी CaptchaSonic node के लिए उपलब्ध है।

---

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

सबसे सरल workflow: trigger → solve → output।

```json
{
  "nodes": [
    {
      "name": "Manual Trigger",
      "type": "n8n-nodes-base.manualTrigger",
      "position": [250, 300]
    },
    {
      "name": "CaptchaSonic",
      "type": "n8n-nodes-captchasonic.captchaSonic",
      "position": [450, 300],
      "parameters": {
        "operation": "solveCaptcha",
        "captchaType": "ReCaptchaV2TaskProxyLess",
        "websiteURL": "https://example.com/login",
        "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
      }
    }
  ],
  "connections": {
    "Manual Trigger": {
      "main": [[ { "node": "CaptchaSonic", "type": "main", "index": 0 } ]]
    }
  }
}
```

> [!TIP]
> ऊपर का JSON कॉपी करें और **Import from clipboard** (खाली canvas पर Ctrl/⌘ + V) से workflow तुरंत लोड करें।

---

## Operations संदर्भ

### CAPTCHA हल करें

मुख्य operation। captcha type चुनें और आवश्यक parameters दें।

#### Token tasks (browser automation)

| Captcha Type | Required Parameters | Returns |
|---|---|---|
| **reCAPTCHA v2** | `websiteURL`, `websiteKey` | `gRecaptchaResponse` token |
| **reCAPTCHA v3** | `websiteURL`, `websiteKey`, `pageAction` | `gRecaptchaResponse` token |
| **Cloudflare Turnstile** | `websiteURL`, `websiteKey` | `token` |
| **hCaptcha** | `websiteURL`, `websiteKey` | `token` |
| **DataDome** | `websiteURL`, `captchaUrl` | `cookie` |

#### Recognition tasks (image-based)

| Captcha Type | Required Parameters | Returns |
|---|---|---|
| **Image-to-Text (OCR)** | `body` (base64 image) | `text` |
| **PopularCaptcha (image grid)** | `images`, `question` | `solution` array |
| **GeeTest v3** | `gt`, `challenge`, `websiteURL` | `challenge`, `validate`, `seccode` |
| **GeeTest v4** | `captchaId`, `websiteURL` | solver output |
| **AWS WAF** | `websiteURL`, `context`, `iv` | `cookie` |
| **TikTok** | `images` array | `solution` |

> [!NOTE]
> image-आधारित tasks के लिए image को **raw base64 string** के रूप में दें (`data:image/…;base64,` prefix के बिना)। यदि आपका upstream node prefix जोड़ता है, तो prefix हटाने के लिए **Function** node उपयोग करें।

### Balance जाँचें

USD में आपका वर्तमान credit balance लौटाता है। batch operations से पहले guard के रूप में उपयोग करें।

---

## Workflow recipes

### Recipe 1: web scraping pipeline में reCAPTCHA v2

**Trigger → HTTP Request (पृष्ठ लाएँ) → CaptchaSonic (reCAPTCHA हल करें) → HTTP Request (form सबमिट करें)**

1. **Schedule Trigger** हर घंटे चलता है।
2. **HTTP Request** लक्ष्य पृष्ठ लाता है और **Function** node से `siteKey` निकालता है।
3. **CaptchaSonic** `ReCaptchaV2TaskProxyLess` से reCAPTCHA हल करता है।
4. दूसरा **HTTP Request** हल किए गए `gRecaptchaResponse` के साथ form सबमिट करता है।

---

### Recipe 2: monitoring के लिए Cloudflare Turnstile bypass

**Schedule Trigger → CaptchaSonic (Turnstile हल करें) → HTTP Request (सुरक्षित API तक पहुँचें)**

1. **Schedule Trigger** हर 15 मिनट में चलता है।
2. **CaptchaSonic** `AntiTurnstileTaskProxyLess` से Turnstile challenge हल करता है।
3. **HTTP Request** हल किए गए token को cookie या header के रूप में उपयोग करके सुरक्षित endpoint को कॉल करता है।

---

### Recipe 3: batch image-to-text OCR

**Spreadsheet Trigger → Loop Over Items → CaptchaSonic (OCR) → Google Sheets (परिणाम लिखें)**

1. **Google Sheets Trigger** image URLs वाली नई rows का पता लगाता है।
2. **Loop Over Items** हर row पर चलता है।
3. **HTTP Request** image डाउनलोड करता है, **Function** उसे base64 में बदलता है।
4. **CaptchaSonic** `ImageToTextTask` से OCR चलाता है।
5. **Google Sheets** निकाले गए text को row में वापस लिखता है।

---

### Recipe 4: batch execution से पहले balance guard

**Manual Trigger → CaptchaSonic (balance प्राप्त करें) → IF (< $5) → Stop / Continue**

1. **Manual Trigger** batch शुरू करता है।
2. `getBalance` operation वाला **CaptchaSonic** node `{ balance: 12.50 }` लौटाता है।
3. **IF** node `{{ $json.balance < 5 }}` जाँचता है।
4. **True path:** "Low balance — please top up." संदेश के साथ **Stop and Error** node।
5. **False path:** मुख्य solve loop में आगे बढ़ता है।

> [!TIP]
> workflow चुपचाप विफल होने से पहले खुद को सूचित करने के लिए low-balance path पर **Send Email** node जोड़ें।

---

## Error handling

### सामान्य errors और समाधान

| Error | Cause | Fix |
|---|---|---|
| `ERROR_WRONG_USER_KEY` | अमान्य API key | **Credentials → CaptchaSonic API** में अपनी key फिर से दर्ज करें |
| `ERROR_ZERO_BALANCE` | कोई credit शेष नहीं | [funds जोड़ें](/docs/guides/add-funds), या ऊपर दी balance guard recipe उपयोग करें |
| `ERROR_CAPTCHA_UNSOLVABLE` | गलत siteKey, URL, या image | जाँचें कि parameters लाइव पृष्ठ से मेल खाते हैं; एक बार पुनः प्रयास करें |
| `TIMEOUT` | solve में बहुत समय लगा | node की timeout सेटिंग बढ़ाएँ; जाँचें कि captcha type सही है |

### Retry पैटर्न

CaptchaSonic node का **error output** एक retry loop से जोड़ें:

**CaptchaSonic → (error) → Wait (5 s) → CaptchaSonic (retry)**

अनंत loops से बचने के लिए Wait के बाद **IF** node का उपयोग करके retries को 3 पर सीमित करें।

### Balance guard पैटर्न

batch operations से पहले हमेशा balance जाँचें। ऊपर [Recipe 4](#recipe-4-balance-guard-before-batch-execution) देखें।

---

## AI agent tool के रूप में उपयोग

n8n का **AI Agent** node CaptchaSonic को tool के रूप में कॉल कर सकता है, ताकि agent बातचीत या कार्य के दौरान गतिशील रूप से तय करे कि CAPTCHAs कब हल करने हैं।

1. अपने canvas पर **CaptchaSonic** node जोड़ें।
2. **AI Agent** node में, **Tools** → **Add Tool** पर जाएँ → अपना CaptchaSonic node चुनें।
3. अब agent के पास `solveCaptcha` और `getBalance` operations तक पहुँच है, और बातचीत के संदर्भ की आवश्यकता होने पर वह उन्हें कॉल करेगा।

> [!NOTE]
> शुद्ध code-agent workflows (Claude Code, Cursor, आदि) के लिए, इसके बजाय [MCP server setup](/docs/mcp/get-started) देखें — यह सीधे agent के tool system से जुड़ता है।

---

## सुझाव और सर्वोत्तम प्रथाएँ

- जहाँ संभव हो **ProxyLess task types** उपयोग करें — ये सरल और तेज़ हैं।
- आंशिक रनों से बचने के लिए batch operations से पहले **पहले balance जाँचें**।
- हर captcha type के लिए उपयुक्त **timeout मान** सेट करें (tokens: 60 s, image: 30 s)।
- solves विफल होने पर अलर्ट (Slack, email) भेजने के लिए **n8n का error workflow** उपयोग करें।
- test mode में **results pin** करें ताकि workflow बनाते समय credits खर्च न हों।

---

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

| Symptom | Cause | Solution |
|---|---|---|
| install के बाद node palette में नहीं | n8n ने reload नहीं किया | n8n रीस्टार्ट करें (self-hosted) या browser रीफ़्रेश करें |
| "Invalid credentials" | key समाप्त हो गई या गलत टाइप हुई | [dashboard](https://my.captchasonic.com) में key फिर से बनाएँ और credential अपडेट करें |
| task "processing" पर अटका | Captcha type मेल नहीं खाता या साइट बदल गई | जाँचें कि parameters लाइव पृष्ठ से मेल खाते हैं; कोई अन्य task type आज़माएँ |
| Rate-limit errors | बहुत अधिक एक साथ requests | solves के बीच **Wait** node (1–2 s) जोड़ें |

---

## संसाधन

- [npm: n8n-nodes-captchasonic](https://www.npmjs.com/package/n8n-nodes-captchasonic)
- [GitHub: captchasonic/n8n-nodes-captchasonic](https://github.com/captchasonic/n8n-nodes-captchasonic)
- [n8n.io listing](https://n8n.io/integrations/captchasonic/)
- [CaptchaSonic dashboard](https://my.captchasonic.com)
- [REST API reference](/docs/api)
- [Capability matrix](/docs/clients-sdks/capabilities)
- [AI agents & MCP](/docs/clients-sdks/ai-agents)
