CaptchaSonic for n8n | CaptchaSonic Docs

Automate CAPTCHA solving in your n8n workflows with the official, verified CaptchaSonic community node. Drag the node onto your canvas, point it at a CAPTCHA, and it returns a solved token or answer — no HTTP plumbing, no image scraping, no proxy setup.

TIP

The node supports 20+ captcha types and works both as a standalone workflow node and as a tool for n8n's AI Agent node. See the capability matrix for the full list.

Links: npm · GitHub · n8n.io listing

Prerequisites

A running n8n instance (self-hosted or n8n Cloud)
A CaptchaSonic API key — get one from my.captchasonic.com, then add funds
Node.js 18+ (self-hosted only)

Installation

Open your n8n instance and go to Settings → Community Nodes.
Click Install and enter:
```
n8n-nodes-captchasonic
```
Self-hosted: restart n8n after install. Cloud: the node loads automatically.
Verify — open the node palette (click +), search CaptchaSonic, and confirm the node appears.

NOTE

The node is verified by n8n and listed in the official integrations directory.

Credential setup

In n8n, go to Credentials → Add Credential and search for CaptchaSonic API.
Paste your API key from the dashboard.
Click Save — the credential tests the connection automatically.

The credential is now available to any CaptchaSonic node in your workflows.

Quick start workflow

The simplest possible workflow: trigger → solve → output.

{
  "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

Copy the JSON above and Import from clipboard (Ctrl/⌘ + V on a blank canvas) to load the workflow instantly.

Operations reference

Solve CAPTCHA

The primary operation. Select the captcha type and supply the required 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

For image-based tasks, supply the image as a raw base64 string (without the data:image/…;base64, prefix). Use the Function node to strip the prefix if your upstream node adds it.

Check balance

Returns your current credit balance in USD. Use it as a guard before batch operations.

Workflow recipes

Recipe 1: reCAPTCHA v2 in a web scraping pipeline

Trigger → HTTP Request (get page) → CaptchaSonic (solve reCAPTCHA) → HTTP Request (submit form)

Schedule Trigger fires every hour.
HTTP Request fetches the target page and extracts the siteKey with a Function node.
CaptchaSonic solves the reCAPTCHA using ReCaptchaV2TaskProxyLess.
A second HTTP Request submits the form with the solved gRecaptchaResponse.

Recipe 2: Cloudflare Turnstile bypass for monitoring

Schedule Trigger → CaptchaSonic (solve Turnstile) → HTTP Request (access protected API)

Schedule Trigger fires every 15 minutes.
CaptchaSonic solves the Turnstile challenge with AntiTurnstileTaskProxyLess.
HTTP Request calls the protected endpoint using the solved token as a cookie or header.

Recipe 3: Batch image-to-text OCR

Spreadsheet Trigger → Loop Over Items → CaptchaSonic (OCR) → Google Sheets (write results)

Google Sheets Trigger detects new rows with image URLs.
Loop Over Items iterates through each row.
HTTP Request downloads the image, Function converts it to base64.
CaptchaSonic runs OCR with ImageToTextTask.
Google Sheets writes the extracted text back to the row.

Recipe 4: Balance guard before batch execution

Manual Trigger → CaptchaSonic (get balance) → IF (< $5) → Stop / Continue

Manual Trigger starts the batch.
CaptchaSonic node with getBalance operation returns { balance: 12.50 }.
IF node checks {{ $json.balance < 5 }}.
True path: Stop and Error node with a message "Low balance — please top up."
False path: continues to the main solve loop.

TIP

Add a Send Email node on the low-balance path to alert yourself before the workflow fails silently.

Error handling

Common errors and fixes

Error	Cause	Fix
`ERROR_WRONG_USER_KEY`	Invalid API key	Re-enter your key in Credentials → CaptchaSonic API
`ERROR_ZERO_BALANCE`	No credits remaining	Add funds, or use the balance guard recipe above
`ERROR_CAPTCHA_UNSOLVABLE`	Bad siteKey, URL, or image	Verify the parameters match the live page; retry once
`TIMEOUT`	Solve took too long	Increase the node's timeout setting; check the captcha type is correct

Retry pattern

Wire the CaptchaSonic node's error output into a retry loop:

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

Use the IF node after the Wait to cap retries at 3 to avoid infinite loops.

Balance guard pattern

Always check balance before batch operations. See Recipe 4 above.

Using as AI agent tool

n8n's AI Agent node can call CaptchaSonic as a tool, so the agent dynamically decides when to solve CAPTCHAs during a conversation or task.

Add a CaptchaSonic node to your canvas.
In the AI Agent node, go to Tools → Add Tool → select your CaptchaSonic node.
The agent now has access to the solveCaptcha and getBalance operations and will invoke them when the conversation context requires it.

NOTE

For pure code-agent workflows (Claude Code, Cursor, etc.), see the MCP server setup instead — it connects directly to the agent's tool system.

Tips & best practices

Use ProxyLess task types when possible — they're simpler and faster.
Check balance first before batch operations to avoid partial runs.
Set timeout values appropriate to each captcha type (tokens: 60 s, image: 30 s).
Use n8n's error workflow to send alerts (Slack, email) when solves fail.
Pin results in test mode so you don't burn credits while building your workflow.

Troubleshooting

Symptom	Cause	Solution
Node not in palette after install	n8n didn't reload	Restart n8n (self-hosted) or refresh the browser
"Invalid credentials"	Key expired or mistyped	Regenerate key in the dashboard and update the credential
Task stuck on "processing"	Captcha type mismatch or site changed	Verify parameters match the live page; try a different task type
Rate-limit errors	Too many concurrent requests	Add a Wait node (1–2 s) between solves