Das offizielle **CaptchaSonic-Python-SDK** macht jedes unterstützte CAPTCHA zu einem einzigen Funktionsaufruf. Es enthält einen synchronen (`CaptchaSonic`) und einen asynchronen (`AsyncCaptchaSonic`) Client, kommuniziert standardmäßig über **gRPC** mit unserer Infrastruktur (optional mit HTTP-Transport) und bietet vollständige Type-Hints, automatische Wiederholungen bei vorübergehenden Fehlern und eingebautes Abfragen für Token-Challenges.

---

## Installation

```bash
pip install captchasonic
```

Der gRPC-Transport ist standardmäßig enthalten. Wenn Sie zusätzlich den optionalen HTTP/JSON-Transport nutzen möchten, installieren Sie das Extra:

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

> [!TIP]
> Das SDK unterstützt **Python 3.10, 3.11, 3.12 und 3.13** und wird unter der MIT-Lizenz veröffentlicht.

---

## Authentifizierung

Sie benötigen einen CaptchaSonic-API-Schlüssel. Erstellen Sie ein Konto und holen Sie sich Ihren Schlüssel im [Dashboard](/app); laden Sie anschließend Ihr Guthaben unter [Guthaben aufladen](/docs/guides/add-funds) auf.

Übergeben Sie den Schlüssel als erstes positionelles Argument an den Client:

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

> [!WARNING]
> Behandeln Sie Ihren API-Schlüssel wie ein Passwort. Halten Sie ihn aus der Versionsverwaltung heraus — laden Sie ihn aus einer Umgebungsvariable oder einem Secrets-Manager, statt ihn fest einzutragen.

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

---

## Schnellstart

Die meisten Token-CAPTCHAs (reCAPTCHA, Turnstile, hCaptcha) werden mit einem einzigen Aufruf gelöst. Der Client fragt für Sie ab und gibt das Token zurück, sobald der Task bereit ist.

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

> Gibt das reCAPTCHA-Token zurück — übermitteln Sie es als `g-recaptcha-response` der Seite.

Token-Methoden fragen standardmäßig bis zu 120 Sekunden ab, bevor ein Timeout eintritt (siehe [Konfiguration](#configuration)).

---

## Unterstützte CAPTCHA-Typen

Das SDK teilt die Methoden in zwei Familien:

- **Token-Methoden** (`*_token`, `solve_turnstile`, `solve_cloudflare`) — Sie übergeben `website_url` / `website_key`, das SDK fragt unsere Infrastruktur ab und gibt ein sofort verwendbares `result["token"]` zurück.
- **Bild- / interaktive Methoden** — Sie übergeben die Challenge-Bilder selbst, und das SDK gibt ein `result["typed_solution"]` zurück, das beschreibt, worauf geklickt, was gezogen oder was eingegeben werden soll.

Alle Bildargumente akzeptieren den flexiblen Typ `ImageInput` — einen Dateipfad (`str`), einen `pathlib.Path`, rohe `bytes` oder ein geöffnetes binäres Dateiobjekt.

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

### reCAPTCHA v2 (Token)

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

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

> Gibt `result["token"]` zurück — übermitteln Sie es als `g-recaptcha-response` der Seite.

### reCAPTCHA v3 (Token)

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

> Gibt `result["token"]` zurück — übermitteln Sie es als `g-recaptcha-response` der Seite.

### reCAPTCHA v2 (Bildraster)

Wenn Sie die Challenge-Kacheln bereits haben, lösen Sie das Raster direkt und erhalten die anzuklickenden Indizes.

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

> Gibt `result["typed_solution"]["grid"]["objects"]` zurück — die Liste der anzuklickenden Kachel-Indizes.

### 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>

> Gibt das Turnstile-Token zurück — übermitteln Sie es als `cf-turnstile-response` des Formulars.

<TaskTypeRef captcha="cloudflare-turnstile" />

### Cloudflare Challenge

Die vollständige Cloudflare-Challenge **erfordert** einen Proxy.

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

> Gibt `result["token"]` zurück — das Clearance-Token für die geschützte Anfrage.

### Popular CAPTCHA (hCaptcha-artige Bild-Challenges)

`solve_popular_captcha` behandelt die interaktiven Bildvarianten; `solve_popular_captcha_token` gibt direkt ein Token zurück.

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

> Die Bildvariante gibt `result["typed_solution"]["grid"]["objects"]` zurück (anzuklickende Kachel-Indizes); die Token-Variante gibt `result["token"]` zurück.

### GeeTest

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

> Gibt `result["typed_solution"]` zurück — die auszuführende Aktion, abhängig von `geetest_type`.

### AWS WAF

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

> Gibt `result["typed_solution"]["grid"]["objects"]` zurück — die Liste der anzuklickenden Kachel-Indizes.

### Bild-zu-Text (OCR)

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

> Gibt `result["typed_solution"]["text"]["texts"][0]` zurück — den erkannten Text, der eingegeben werden soll.

### Schiebepuzzle

Übergeben Sie den Hintergrund und das Puzzleteil; Sie erhalten den horizontalen Pixelversatz zurück, um den Schieber zu bewegen.

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

> Gibt `result["typed_solution"]["slide"]["x"]` zurück — der horizontale Pixelversatz, um das Teil zu ziehen.

### TikTok

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

> Gibt `result["typed_solution"]` zurück — die auszuführende Aktion, abhängig von `type`.

### Binance

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

> Gibt `result["typed_solution"]` zurück — die auszuführende Aktion, abhängig von `type`.

---

## Async-Verwendung

Für Workloads mit hoher Parallelität (FastAPI-Handler, Scrapy-Spider, asyncio-Pipelines) verwenden Sie `AsyncCaptchaSonic`. Es spiegelt die synchrone API exakt, aber jede Lösungsmethode ist awaitable. Verwenden Sie es als asynchronen Kontextmanager, damit der zugrunde liegende Kanal automatisch aufgeräumt wird.

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

Der synchrone Client unterstützt ebenfalls das Kontextmanager-Protokoll:

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

---

## Proxy-Unterstützung

Token-Methoden akzeptieren ein optionales Argument `proxy` (für `solve_cloudflare` erforderlich). Verwenden Sie eine übliche Proxy-URL:

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

> [!TIP]
> Ein Proxy ermöglicht unserem Solver, den geografischen Standort und die IP-Reputation Ihrer Anfrage nachzubilden, was die Erfolgsquote bei Seiten mit strengen Anti-Bot-Regeln verbessert.

---

## Konfiguration

Alle Optionen werden an den Konstruktor des Clients übergeben und gelten sowohl für den synchronen als auch für den asynchronen Client.

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

| Option | Standard | Beschreibung |
| :--- | :--- | :--- |
| `transport` | `"grpc"` | Wire-Protokoll. `"grpc"` sendet Bilder ohne Base64-Overhead; `"http"` (erfordert das Extra `[http]`) sendet REST/JSON mit Base64-kodierten Bildern. |
| `url` | `api.captchasonic.com:443` | Überschreibt den API-Endpunkt (z. B. für selbst gehostete oder Staging-Umgebungen). |
| `timeout` | `30.0` | Netzwerk-Timeout pro Aufruf in Sekunden. |
| `polling_interval` | `2.0` | Sekunden zwischen den Abfragen, während auf einen Token-Task gewartet wird. |
| `polling_timeout` | `120.0` | Maximale Wartezeit in Sekunden auf einen Token-Task, bevor ein Fehler ausgelöst wird. |
| `secure` | `True` | TLS für den gRPC-Kanal verwenden. |

Vorübergehende gRPC-Fehler werden automatisch mit exponentiellem Backoff erneut versucht (bis zu 3 Versuche), sodass Sie nur echte Fachfehler behandeln müssen.

---

## Fehlerbehandlung

Alle SDK-Fehler erben von `SonicError`. Sie können daher alles mit einer einzigen `except`-Klausel abfangen oder je nach Unterklasse verzweigen. Jeder Fehler trägt zudem einen numerischen `error_id`.

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

<ErrorIdTable />

---

## Konto-Hilfsfunktionen

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

Verwenden Sie `health_check()` als leichtgewichtige Bereitschaftsprüfung in Diensten und `get_balance()`, um Jobs zu prüfen, bevor Sie Guthaben verbrauchen.

---

## Fehlersuche

> [!TIP]
> **`ModuleNotFoundError` bei Verwendung des HTTP-Transports.** Der HTTP-Client benötigt `httpx`, das ein optionales Extra ist. Installieren Sie es mit `pip install "captchasonic[http]"` und setzen Sie `transport="http"`.

- **Ein Token-Task bricht nach etwa 120 Sekunden ab.** Das ist der `polling_timeout`. Erhöhen Sie ihn für langsame Ziele, z. B. `CaptchaSonic(key, polling_timeout=240.0)`.
- **`solve_cloudflare` schlägt sofort fehl.** Das Argument `proxy` ist für die Cloudflare-Challenge erforderlich — übergeben Sie eine funktionierende Proxy-URL.
- **gRPC-Verbindungsfehler hinter einem Unternehmensproxy/einer Firewall.** gRPC benötigt HTTP/2 über Port 443. Blockiert Ihr Netzwerk dies, wechseln Sie auf `transport="http"`.
- **Bildmethoden liefern Indizes statt eines Tokens.** Interaktive Methoden (`solve_recaptcha_v2`, `solve_popular_captcha`, `solve_aws_waf`, `solve_geetest` usw.) geben `result["typed_solution"]` zurück, das die auszuführende Aktion beschreibt; nur `*_token`, `solve_turnstile` und `solve_cloudflare` liefern `result["token"]`.

---

## Ressourcen

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