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_tokentokenreCAPTCHA v2 (token) — Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready).
solve_recaptcha_v2_token(…)returnssolution.tokenfrom 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 fieldimport { CaptchaSonic } from "captchasonic";
const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY);
const result = await solver.solveRecaptchaV2Token({
websiteURL: "https://example.com/login",
websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
console.log(result.solution.gRecaptchaResponse);
// 03AGdBq25SxXT... ← drop into the g-recaptcha-response fieldGibt das reCAPTCHA-Token zurück — übermitteln Sie es als
g-recaptcha-responseder 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 übergebenwebsite_url/website_key, das SDK fragt unsere Infrastruktur ab und gibt ein sofort verwendbaresresult["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_tokentokenreCAPTCHA v2 (token) — Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready).
solve_recaptcha_v2_token(…)returnssolution.tokenresult = 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 alsg-recaptcha-responseder 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 alsg-recaptcha-responseder 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_turnstiletokenCloudflare Turnstile — Solve a Cloudflare Turnstile token challenge (async — polls until ready).
solve_turnstile(…)returnssolution.tokenresult = solver.solve_turnstile(
website_url="https://example.com",
website_key="0x4AAAAAAA...",
proxy="http://user:pass@host:port", # optional
)
token = result["token"]await solver.solveTurnstile({
websiteURL: "https://example.com",
websiteKey: "0x4AAAAAAA...",
proxy: "http://user:[email protected]:8080",
});REST task typeGibt das Turnstile-Token zurück — übermitteln Sie es als
cf-turnstile-responsedes Formulars.
AntiTurnstileTask
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.
Popular CAPTCHA (hCaptcha-artige Bild-Challenges)
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 gibtresult["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 vongeetest_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 vontype.
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 vontype.
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
)
| 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.
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}")
| id | Python exception | Node errorName | Meaning | Action |
|---|---|---|---|---|
0 | SonicError | SonicError | Base class for every SDK error — catches anything below. | Inspect `error.errorId` (Node) / `err.error_id` (Python) and branch. |
1 | InvalidApiKeyError | InvalidApiKeyError | API key is missing, malformed, or revoked. | Verify the key in your dashboard. |
2 | InsufficientBalanceError | InsufficientBalanceError | Account balance can't cover the task. | Add funds. |
3 | DailyLimitExceededError | DailyLimitExceededError | Daily quota exhausted. | Wait for the daily reset or upgrade your plan. |
4 | MinuteLimitExceededError | MinuteLimitExceededError | Per-minute rate limit hit. | Slow down requests / add exponential backoff. |
5 | QuotaExceededError | QuotaExceededError | Plan quota exhausted. | Upgrade your plan. |
6 | PlanExpiredError | PlanExpiredError | Subscription 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_cloudflareschlägt sofort fehl. Das Argumentproxyist 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_geetestusw.) gebenresult["typed_solution"]zurück, das die auszuführende Aktion beschreibt; nur*_token,solve_turnstileundsolve_cloudflareliefernresult["token"].