公式の **CaptchaSonic Python SDK** を使うと、対応しているすべての CAPTCHA を 1 回の関数呼び出しで解決できます。同期クライアント（`CaptchaSonic`）と非同期クライアント（`AsyncCaptchaSonic`）の両方を備えています。既定では **gRPC** で当社のインフラと通信し、オプションで HTTP トランスポートも利用できます。型ヒントを完全に備え、一時的なエラーには自動で再試行し、トークン型のチャレンジには組み込みのポーリングを使います。

---

## インストール

```bash
pip install captchasonic
```

gRPC トランスポートは標準でインストールされます。オプションの HTTP/JSON トランスポートも使う場合は、追加パッケージをインストールしてください。

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

> [!TIP]
> この SDK は **Python 3.10、3.11、3.12、3.13** に対応しており、MIT ライセンスで公開されています。

---

## 認証

CaptchaSonic の API キーが必要です。アカウントを作成し、[ダッシュボード](/app) からキーを取得してください。その後、[残高の追加](/docs/guides/add-funds) から残高をチャージしてください。

キーをクライアントの最初の位置引数として渡します。

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

> [!WARNING]
> API キーはパスワードと同じように扱ってください。ソース管理に含めないようにしてください。直接書き込まず、環境変数またはシークレットマネージャーから読み込んでください。

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

---

## クイックスタート

ほとんどのトークン型 CAPTCHA（reCAPTCHA、Turnstile、hCaptcha）は、1 回の呼び出しで解決できます。クライアントがポーリングを代行し、タスクの準備ができるとトークンを返します。

<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 のメソッドは、次の 2 つのファミリーに分かれます。

- **トークンメソッド**（`*_token`、`solve_turnstile`、`solve_cloudflare`）— `website_url` / `website_key` を指定すると、SDK が当社のインフラをポーリングし、そのまま送信できる `result["token"]` を返します。
- **画像 / インタラクティブメソッド** — チャレンジの画像は自分で渡します。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 の完全なチャレンジには、プロキシが **必須** です。

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

> `result["token"]` を返します。保護されたリクエストに使うクリアランストークンです。

### Popular CAPTCHA（hCaptcha 形式の画像チャレンジ）

`solve_popular_captcha` はインタラクティブな画像バリアントを扱います。`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` によって形式が決まります。

---

## 非同期での利用

高い同時実行が必要なワークロード（FastAPI のハンドラー、Scrapy のスパイダー、asyncio のパイプライン）では、`AsyncCaptchaSonic` を使ってください。同期 API と完全に同じ構造ですが、すべての解決メソッドは await 可能です。非同期のコンテキストマネージャーとして使うと、基盤のチャネルが自動的にクリーンアップされます。

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

同期クライアントもコンテキストマネージャーのプロトコルに対応しています。

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

---

## プロキシのサポート

トークンメソッドは、任意の `proxy` 引数を受け付けます（`solve_cloudflare` では必須です）。標準のプロキシ URL を使ってください。

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

> [!TIP]
> プロキシを指定すると、当社のソルバーがリクエストの地理的な位置と IP の評判を反映できるため、厳しいボット対策を行うサイトでの成功率が向上します。

---

## 設定

すべてのオプションはクライアントのコンストラクターに渡します。同期クライアントと非同期クライアントの両方に適用されます。

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

| Option | Default | Description |
| :--- | :--- | :--- |
| `transport` | `"grpc"` | 通信プロトコルです。`"grpc"` は Base64 のオーバーヘッドなしで画像を送信します。`"http"`（`[http]` の追加パッケージが必要）は、Base64 エンコードした画像を REST/JSON で送信します。 |
| `url` | `api.captchasonic.com:443` | API のエンドポイントを上書きします（セルフホスト環境やステージング環境向け）。 |
| `timeout` | `30.0` | 1 回の呼び出しのネットワークタイムアウトです（秒）。 |
| `polling_interval` | `2.0` | トークンタスクの待機中に、ポーリングする間隔（秒）です。 |
| `polling_timeout` | `120.0` | 例外を送出するまでにトークンタスクを待つ最大秒数です。 |
| `secure` | `True` | gRPC チャネルで TLS を使用します。 |

一時的な gRPC エラーは、指数バックオフで自動的に再試行されます（最大 3 回）。そのため、扱う必要があるのは実際のビジネスエラーだけです。

---

## エラー処理

SDK のエラーはすべて `SonicError` を継承しています。そのため、1 つの `except` 節ですべてを捕捉することも、特定のサブクラスで分岐することもできます。各エラーは数値の `error_id` も持ちます。

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

<ErrorIdTable />

---

## アカウントのヘルパー

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

サービス内で軽量な準備確認には `health_check()` を使い、クレジットを使い始める前にジョブを制御するには `get_balance()` を使ってください。

---

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

> [!TIP]
> **HTTP トランスポート使用時に `ModuleNotFoundError` が出る。** HTTP クライアントは `httpx` に依存していますが、これはオプションの追加パッケージです。`pip install "captchasonic[http]"` でインストールし、`transport="http"` を設定してください。

- **トークンタスクが約 120 秒後にエラーになる。** これは `polling_timeout` によるものです。動作の遅いサイトでは値を大きくしてください（例: `CaptchaSonic(key, polling_timeout=240.0)`）。
- **`solve_cloudflare` がすぐに失敗する。** Cloudflare のチャレンジには `proxy` 引数が必須です。有効なプロキシ URL を指定してください。
- **企業のプロキシやファイアウォールの背後で gRPC の接続エラーが出る。** gRPC はポート 443 上の HTTP/2 を必要とします。ネットワークでブロックされている場合は、`transport="http"` に切り替えてください。
- **画像メソッドがトークンではなくインデックスを返す。** インタラクティブなメソッド（`solve_recaptcha_v2`、`solve_popular_captcha`、`solve_aws_waf`、`solve_geetest` など）は、実行すべきアクションを示す `result["typed_solution"]` を返します。`result["token"]` を返すのは `*_token`、`solve_turnstile`、`solve_cloudflare` だけです。

---

## リソース

- [PyPI パッケージ](https://pypi.org/project/captchasonic/)
- [REST API リファレンス](/docs/api)
