Skip to content
CaptchaSonic

Python-SDK

CAPTCHAs in Python mit dem offiziellen CaptchaSonic-SDK lösen — gRPC- und HTTP-Transport, async-fähig, vollständig typisiert.

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

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:

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; laden Sie anschließend Ihr Guthaben unter Guthaben aufladen auf.

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

from captchasonic import CaptchaSonic

solver = CaptchaSonic("YOUR_API_KEY")

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.

import os
from captchasonic import CaptchaSonic

solver = CaptchaSonic(os.environ["CAPTCHASONIC_API_KEY"])

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.

solve_recaptcha_v2_tokentoken
Verified v1.0.0· 2026-05-28

reCAPTCHA v2 (token) — Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready).

signaturesolve_recaptcha_v2_token(…)returnssolution.token
from captchasonic import CaptchaSonic

solver = CaptchaSonic("YOUR_API_KEY")

result = solver.solve_recaptcha_v2_token(
    website_url="https://example.com/login",
    website_key="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
)

print(result["token"])
# 03AGdBq25SxXT...  ← drop this into the g-recaptcha-response field

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


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.

from pathlib import Path

# Any of these work as an item in an `images=[...]` list:
Path("captcha.png")        # pathlib.Path
"./captcha.png"            # str path
open("captcha.png", "rb").read()  # bytes

reCAPTCHA v2 (Token)

solve_recaptcha_v2_tokentoken
Verified v1.0.0· 2026-05-28

reCAPTCHA v2 (token) — Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready).

signaturesolve_recaptcha_v2_token(…)returnssolution.token
result = solver.solve_recaptcha_v2_token(
    website_url="https://example.com",
    website_key="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    proxy="http://user:pass@host:port",  # optional
)
token = result["token"]

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

reCAPTCHA v3 (Token)

result = solver.solve_recaptcha_v3_token(
    website_url="https://example.com",
    website_key="6Lc_aCMTAAAAAB...",
    proxy="http://user:pass@host:port",  # optional
)
token = result["token"]

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.

result = solver.solve_recaptcha_v2(
    images=[Path("tile.png")],         # ImageInput list
    question="traffic lights",          # label or /m/... entity id
    question_type="44",                # "split_33" | "33" | "44"
)
to_click = result["typed_solution"]["grid"]["objects"]  # list[int]

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

Cloudflare Turnstile

solve_turnstiletoken
Verified v1.0.0· 2026-05-28

Cloudflare Turnstile — Solve a Cloudflare Turnstile token challenge (async — polls until ready).

signaturesolve_turnstile(…)returnssolution.token
result = solver.solve_turnstile(
    website_url="https://example.com",
    website_key="0x4AAAAAAA...",
    proxy="http://user:pass@host:port",  # optional
)
token = result["token"]

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

REST task typeAntiTurnstileTask

Cloudflare Challenge

Die vollständige Cloudflare-Challenge erfordert einen Proxy.

result = solver.solve_cloudflare(
    website_url="https://example.com",
    website_key="0x4AAAAAAA...",
    proxy="http://user:pass@host:port",  # required
)
token = result["token"]

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

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

# Image / interactive variant
result = solver.solve_popular_captcha(
    images=[Path("challenge.png")],
    question="Select all traffic lights",
    question_type="grid",  # "objectClassify" | "objectClick" | "objectDrag" | "grid"
)
to_click = result["typed_solution"]["grid"]["objects"]  # list[int]

# Token variant
result = solver.solve_popular_captcha_token(
    website_url="https://example.com",
    website_key="00000000-0000-0000-0000-000000000000",
    proxy="http://user:pass@host:port",  # optional
)
token = result["token"]

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

GeeTest

result = solver.solve_geetest(
    geetest_type="nine",  # "nine" | "click" | "slide" | "match" | "winlinze"
    question="Select all bicycles",  # required for "nine" and "click"
    images=[Path("tile.png")],        # required for "nine", "click", "slide"
)
solution = result["typed_solution"]  # structure varies by geetest_type

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

AWS WAF

result = solver.solve_aws_waf(
    images=[Path("grid.png")],
    question="grid:vehicles:cars",
)
to_click = result["typed_solution"]["grid"]["objects"]  # list[int]

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

Bild-zu-Text (OCR)

result = solver.solve_ocr(
    images=[Path("captcha.png")],
    module="common",       # "common" | "mtcaptcha" | "bls" | "morocco"
    numeric=False,         # expect only digits
    case_sensitive=True,   # preserve letter case
    min_length=4,
    max_length=8,
)
text = result["typed_solution"]["text"]["texts"][0]  # str

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.

result = solver.solve_slide_image(
    images=[Path("background.png"), Path("piece.png")],
)
offset_x = result["typed_solution"]["slide"]["x"]  # float (pixels)

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

TikTok

result = solver.solve_tiktok(
    type="whirl",  # "click" | "whirl" | "slide"
    images=[Path("outer.png")],
    examples=[Path("inner.png")],  # required for "whirl" and "slide"
)
solution = result["typed_solution"]

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

Binance

result = solver.solve_binance(
    type="grid",  # "grid" | "slide"
    question="Select all bicycles",  # required for "grid"
    images=[Path("grid.png")],
)
solution = result["typed_solution"]

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.

import asyncio
from captchasonic import AsyncCaptchaSonic

async def main():
    async with AsyncCaptchaSonic("YOUR_API_KEY") as solver:
        result = await solver.solve_turnstile(
            website_url="https://example.com",
            website_key="0x4AAAAAAA...",
        )
        print(result["token"])

asyncio.run(main())

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

with CaptchaSonic("YOUR_API_KEY") as solver:
    result = solver.solve_ocr(images=[Path("captcha.png")])
    print(result["typed_solution"]["text"]["texts"][0])

Proxy-Unterstützung

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

proxy = "http://user:pass@host:port"

result = solver.solve_recaptcha_v2_token(
    website_url="https://example.com",
    website_key="6Le-...",
    proxy=proxy,
)

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.

solver = CaptchaSonic(
    "YOUR_API_KEY",
    transport="grpc",                # "grpc" (default) or "http"
    url="api.captchasonic.com:443",  # endpoint override (optional)
    timeout=30.0,                    # per-call timeout, seconds
    polling_interval=2.0,            # seconds between task polls
    polling_timeout=120.0,           # max wait for a token task, seconds
    secure=True,                     # use TLS for gRPC
)
OptionStandardBeschreibung
transport"grpc"Wire-Protokoll. "grpc" sendet Bilder ohne Base64-Overhead; "http" (erfordert das Extra [http]) sendet REST/JSON mit Base64-kodierten Bildern.
urlapi.captchasonic.com:443Überschreibt den API-Endpunkt (z. B. für selbst gehostete oder Staging-Umgebungen).
timeout30.0Netzwerk-Timeout pro Aufruf in Sekunden.
polling_interval2.0Sekunden zwischen den Abfragen, während auf einen Token-Task gewartet wird.
polling_timeout120.0Maximale Wartezeit in Sekunden auf einen Token-Task, bevor ein Fehler ausgelöst wird.
secureTrueTLS 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.

from captchasonic.exceptions import (
    SonicError,
    InvalidApiKeyError,
    InsufficientBalanceError,
)

try:
    result = solver.solve_turnstile(
        website_url="https://example.com",
        website_key="0x4AAAAAAA...",
    )
except InsufficientBalanceError:
    print("Top up your balance to continue.")
except InvalidApiKeyError:
    print("Check your API key.")
except SonicError as err:
    print(f"Solve failed (error_id={err.error_id}): {err}")
errors7 canonical `errorId` codes
idPython exceptionNode errorNameMeaningAction
0SonicErrorSonicErrorBase class for every SDK error — catches anything below.Inspect `error.errorId` (Node) / `err.error_id` (Python) and branch.
1InvalidApiKeyErrorInvalidApiKeyErrorAPI key is missing, malformed, or revoked.Verify the key in your dashboard.
2InsufficientBalanceErrorInsufficientBalanceErrorAccount balance can't cover the task.Add funds.
3DailyLimitExceededErrorDailyLimitExceededErrorDaily quota exhausted.Wait for the daily reset or upgrade your plan.
4MinuteLimitExceededErrorMinuteLimitExceededErrorPer-minute rate limit hit.Slow down requests / add exponential backoff.
5QuotaExceededErrorQuotaExceededErrorPlan quota exhausted.Upgrade your plan.
6PlanExpiredErrorPlanExpiredErrorSubscription has expired.Renew your subscription.

Every concrete row inherits from SonicError — catch it once to handle all SDK failures, or branch on errorId / exception subclass for granular control. Transient gRPC errors are retried automatically with exponential backoff (up to 3 attempts).


Konto-Hilfsfunktionen

balance = solver.get_balance()  # current balance in USD (float)
print(f"Balance: ${balance:.2f}")

health = solver.health_check()  # HealthCheckResponse — verifies connectivity

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