公式の[認証済みCaptchaSonicコミュニティノード](https://n8n.io/integrations/captchasonic/)を使って、**n8nワークフロー**内のCAPTCHA解決を自動化できます。ノードをキャンバスにドラッグし、CAPTCHAを指定すると、解決済みのトークンまたは回答が返ります。HTTPの個別実装も、画像のスクレイピングも、プロキシ設定も不要です。

> [!TIP]
> このノードは**20種類以上のCAPTCHAタイプ**に対応し、**単独のワークフローノード**としても、**n8nのAI Agentノードのツール**としても使えます。全一覧は[対応機能マトリクス](/docs/clients-sdks/capabilities)をご覧ください。

**リンク:** [npm](https://www.npmjs.com/package/n8n-nodes-captchasonic) · [GitHub](https://github.com/captchasonic/n8n-nodes-captchasonic) · [n8n.io 掲載ページ](https://n8n.io/integrations/captchasonic/)

---

## 前提条件

- 稼働中の**n8nインスタンス**（セルフホストまたはn8n Cloud）
- **CaptchaSonic APIキー**。[my.captchasonic.com](https://my.captchasonic.com)で取得し、[残高をチャージ](/docs/guides/add-funds)してください
- **Node.js 18以上**（セルフホストの場合のみ）

---

## インストール

1. n8nインスタンスを開き、**Settings → Community Nodes**に移動します。
2. **Install**をクリックし、次の名前を入力します:
   ```
   n8n-nodes-captchasonic
   ```
3. **セルフホスト:** インストール後にn8nを再起動します。**Cloud:** ノードは自動的に読み込まれます。
4. **確認** — ノードパレット（**+**をクリック）を開き、`CaptchaSonic`を検索して、ノードが表示されることを確認します。

> [!NOTE]
> このノードは[n8nによる認証](https://n8n.io/integrations/captchasonic/)を受けており、公式のインテグレーション一覧に掲載されています。

---

## 認証情報の設定

1. n8nで**Credentials → Add Credential**に移動し、**CaptchaSonic API**を検索します。
2. [ダッシュボード](https://my.captchasonic.com)から**APIキー**を貼り付けます。
3. **Save**をクリックします。認証情報は接続を自動でテストします。

これで、ワークフロー内のどのCaptchaSonicノードからも、この認証情報を使えます。

---

## クイックスタートのワークフロー

最もシンプルなワークフローは、トリガー → 解決 → 出力の3ステップです。

```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**（Ctrl/⌘ + V）を実行すると、ワークフローがすぐに読み込まれます。

---

## オペレーション一覧

### CAPTCHAを解決

主要なオペレーションです。CAPTCHAタイプを選び、必要なパラメーターを指定します。

#### トークン系タスク（ブラウザー自動化）

| CAPTCHAタイプ | 必須パラメーター | 戻り値 |
|---|---|---|
| **reCAPTCHA v2** | `websiteURL`, `websiteKey` | `gRecaptchaResponse` トークン |
| **reCAPTCHA v3** | `websiteURL`, `websiteKey`, `pageAction` | `gRecaptchaResponse` トークン |
| **Cloudflare Turnstile** | `websiteURL`, `websiteKey` | `token` |
| **hCaptcha** | `websiteURL`, `websiteKey` | `token` |
| **DataDome** | `websiteURL`, `captchaUrl` | `cookie` |

#### 認識系タスク（画像ベース）

| CAPTCHAタイプ | 必須パラメーター | 戻り値 |
|---|---|---|
| **Image-to-Text（OCR）** | `body`（base64画像） | `text` |
| **PopularCaptcha（画像グリッド）** | `images`, `question` | `solution` 配列 |
| **GeeTest v3** | `gt`, `challenge`, `websiteURL` | `challenge`, `validate`, `seccode` |
| **GeeTest v4** | `captchaId`, `websiteURL` | ソルバーの出力 |
| **AWS WAF** | `websiteURL`, `context`, `iv` | `cookie` |
| **TikTok** | `images` 配列 | `solution` |

> [!NOTE]
> 画像ベースのタスクでは、画像を**生のbase64文字列**（`data:image/…;base64,`の接頭辞なし）で指定してください。上流のノードが接頭辞を付ける場合は、**Function**ノードで取り除いてください。

### 残高を確認

現在のクレジット残高をUSDで返します。一括処理の前に、ガード条件として使えます。

---

## ワークフローのレシピ

### レシピ1: WebスクレイピングパイプラインでのreCAPTCHA v2

**トリガー → HTTP Request（ページを取得） → CaptchaSonic（reCAPTCHAを解決） → HTTP Request（フォームを送信）**

1. **Schedule Trigger**が1時間ごとに起動します。
2. **HTTP Request**が対象ページを取得し、**Function**ノードで`siteKey`を抽出します。
3. **CaptchaSonic**が`ReCaptchaV2TaskProxyLess`を使ってreCAPTCHAを解決します。
4. 2つ目の**HTTP Request**が、解決済みの`gRecaptchaResponse`を付けてフォームを送信します。

---

### レシピ2: 監視用のCloudflare Turnstile突破

**Schedule Trigger → CaptchaSonic（Turnstileを解決） → HTTP Request（保護されたAPIにアクセス）**

1. **Schedule Trigger**が15分ごとに起動します。
2. **CaptchaSonic**が`AntiTurnstileTaskProxyLess`を使ってTurnstileチャレンジを解決します。
3. **HTTP Request**が、解決済みトークンをCookieまたはヘッダーとして使い、保護されたエンドポイントを呼び出します。

---

### レシピ3: 画像からのテキスト抽出（OCR）の一括処理

**Spreadsheet Trigger → Loop Over Items → CaptchaSonic（OCR） → Google Sheets（結果を書き込み）**

1. **Google Sheets Trigger**が、画像URLを含む新しい行を検出します。
2. **Loop Over Items**が各行を順に処理します。
3. **HTTP Request**が画像をダウンロードし、**Function**がbase64に変換します。
4. **CaptchaSonic**が`ImageToTextTask`でOCRを実行します。
5. **Google Sheets**が抽出したテキストを行に書き戻します。

---

### レシピ4: 一括実行前の残高ガード

**Manual Trigger → CaptchaSonic（残高を取得） → IF（5ドル未満） → Stop / Continue**

1. **Manual Trigger**で一括処理を開始します。
2. `getBalance`オペレーションの**CaptchaSonic**ノードが`{ balance: 12.50 }`を返します。
3. **IF**ノードが`{{ $json.balance < 5 }}`を確認します。
4. **True側:** 「残高不足です。チャージしてください。」というメッセージの**Stop and Error**ノードに進みます。
5. **False側:** 通常の解決ループを続行します。

> [!TIP]
> 残高不足の経路に**Send Email**ノードを追加すると、ワークフローが静かに失敗する前に通知を受け取れます。

---

## エラー処理

### よくあるエラーと対処法

| エラー | 原因 | 対処 |
|---|---|---|
| `ERROR_WRONG_USER_KEY` | APIキーが無効 | **Credentials → CaptchaSonic API**でキーを入力し直します |
| `ERROR_ZERO_BALANCE` | クレジットがない | [残高をチャージ](/docs/guides/add-funds)するか、上の残高ガードのレシピを使います |
| `ERROR_CAPTCHA_UNSOLVABLE` | siteKey、URL、または画像が不正 | パラメーターが公開中のページと一致するか確認し、1回再試行します |
| `TIMEOUT` | 解決に時間がかかりすぎた | ノードのタイムアウト設定を増やし、CAPTCHAタイプが正しいか確認します |

### 再試行のパターン

CaptchaSonicノードの**エラー出力**を再試行ループにつなぎます:

**CaptchaSonic → （エラー） → Wait（5秒） → CaptchaSonic（再試行）**

Waitの後にIFノードを置き、再試行を3回までに制限して、無限ループを防ぎます。

### 残高ガードのパターン

一括処理の前には、必ず残高を確認してください。上の[レシピ4](#recipe-4-balance-guard-before-batch-execution)を参照してください。

---

## AIエージェントのツールとして使う

n8nの**AI Agent**ノードは、CaptchaSonicをツールとして呼び出せます。そのためエージェントは、会話やタスクの途中で、CAPTCHAを解決すべきかどうかを動的に判断します。

1. キャンバスに**CaptchaSonic**ノードを追加します。
2. **AI Agent**ノードで**Tools → Add Tool**に進み、CaptchaSonicノードを選びます。
3. これでエージェントは`solveCaptcha`と`getBalance`のオペレーションを使えるようになり、会話の文脈に応じて呼び出します。

> [!NOTE]
> Claude Code、Cursorなどのコードエージェントを使う純粋なワークフローの場合は、代わりに[MCPサーバーの設定](/docs/mcp/get-started)をご覧ください。エージェントのツールシステムに直接接続できます。

---

## ヒントとベストプラクティス

- できる限り**ProxyLessタスクタイプ**を使ってください。よりシンプルで高速です。
- 一括処理の前に**残高を先に確認**し、途中で止まる実行を避けてください。
- CAPTCHAタイプごとに適切な**タイムアウト値**を設定してください（トークン: 60秒、画像: 30秒）。
- 解決に失敗したときにアラート（Slack、メール）を送るため、n8nの**エラーワークフロー**を使ってください。
- テストモードでは結果を**ピン留め**し、ワークフローの構築中にクレジットを消費しないようにしてください。

---

## トラブルシューティング

| 症状 | 原因 | 解決策 |
|---|---|---|
| インストール後にノードがパレットに表示されない | n8nが再読み込みされていない | セルフホストの場合はn8nを再起動するか、ブラウザーを再読み込みします |
| 「Invalid credentials」と表示される | キーの期限切れまたは入力ミス | [ダッシュボード](https://my.captchasonic.com)でキーを再生成し、認証情報を更新します |
| タスクが「processing」のまま止まる | CAPTCHAタイプの不一致、またはサイトの変更 | パラメーターが公開中のページと一致するか確認するか、別のタスクタイプを試します |
| レート制限のエラーが出る | 同時リクエストが多すぎる | 解決の間に**Wait**ノード（1〜2秒）を追加します |

---

## リソース

- [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 掲載ページ](https://n8n.io/integrations/captchasonic/)
- [CaptchaSonic ダッシュボード](https://my.captchasonic.com)
- [REST API リファレンス](/docs/api)
- [対応機能マトリクス](/docs/clients-sdks/capabilities)
- [AIエージェントとMCP](/docs/clients-sdks/ai-agents)
