SDK Python
Résolvez des CAPTCHA en Python avec le SDK officiel CaptchaSonic — transport gRPC + HTTP, prêt pour l'asynchrone, entièrement typé.
Le SDK Python officiel de CaptchaSonic transforme chaque CAPTCHA pris en charge en un seul appel de fonction. Il fournit un client synchrone (CaptchaSonic) et un client asynchrone (AsyncCaptchaSonic), communique avec notre infrastructure en gRPC par défaut (avec un transport HTTP optionnel), et inclut des annotations de types complètes, des relances automatiques pour les erreurs transitoires et une interrogation intégrée pour les défis à jeton.
Installation
pip install captchasonic
Le transport gRPC est installé par défaut. Pour utiliser aussi le transport HTTP/JSON optionnel, installez l'extra :
pip install "captchasonic[http]"
TIP
Le SDK prend en charge Python 3.10, 3.11, 3.12 et 3.13 et est publié sous licence MIT.
Authentification
Il vous faut une clé API CaptchaSonic. Créez un compte et récupérez votre clé depuis le tableau de bord, puis rechargez votre solde depuis Ajouter des fonds.
Passez la clé en premier argument positionnel du client :
from captchasonic import CaptchaSonic
solver = CaptchaSonic("YOUR_API_KEY")
WARNING
Traitez votre clé API comme un mot de passe. Ne la versionnez pas : chargez-la depuis une variable d'environnement ou un gestionnaire de secrets plutôt que de la coder en dur.
import os
from captchasonic import CaptchaSonic
solver = CaptchaSonic(os.environ["CAPTCHASONIC_API_KEY"])
Démarrage rapide
La plupart des CAPTCHA à jeton (reCAPTCHA, Turnstile, hCaptcha) se résolvent en un seul appel. Le client interroge le résultat pour vous et renvoie le jeton dès que la tâche est prête.
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 fieldRenvoie le jeton reCAPTCHA — soumettez-le comme
g-recaptcha-responsede la page.
Par défaut, les méthodes à jeton interrogent le résultat pendant 120 secondes au maximum avant d'expirer (voir Configuration).
Types de CAPTCHA pris en charge
Le SDK répartit les méthodes en deux familles :
- Méthodes à jeton (
*_token,solve_turnstile,solve_cloudflare) — vous fournissez unwebsite_url/website_key, le SDK interroge notre infrastructure et renvoie unresult["token"]prêt à être soumis. - Méthodes image / interactives — vous fournissez vous-même les images du défi, et le SDK renvoie un
result["typed_solution"]décrivant ce qu'il faut cliquer, glisser ou saisir.
Tous les arguments d'image acceptent le type souple ImageInput — un chemin de fichier (str), un pathlib.Path, des bytes bruts ou un objet fichier binaire ouvert.
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 (jeton)
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"]
Renvoie
result["token"]— soumettez-le commeg-recaptcha-responsede la page.
reCAPTCHA v3 (jeton)
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"]
Renvoie
result["token"]— soumettez-le commeg-recaptcha-responsede la page.
reCAPTCHA v2 (grille d'images)
Lorsque vous avez déjà les tuiles du défi, résolvez directement la grille et recevez les indices à cliquer.
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]
Renvoie
result["typed_solution"]["grid"]["objects"]— la liste des indices de tuiles à cliquer.
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 typeRenvoie le jeton Turnstile — soumettez-le comme
cf-turnstile-responsedu formulaire.
AntiTurnstileTask
Défi Cloudflare
Le défi Cloudflare complet nécessite un proxy.
result = solver.solve_cloudflare(
website_url="https://example.com",
website_key="0x4AAAAAAA...",
proxy="http://user:pass@host:port", # required
)
token = result["token"]
Renvoie
result["token"]— le jeton de clearance pour la requête protégée.
CAPTCHA populaires (défis d'images de style hCaptcha)
solve_popular_captcha gère les variantes d'images interactives ; solve_popular_captcha_token renvoie directement un jeton.
# 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"]
La variante image renvoie
result["typed_solution"]["grid"]["objects"](indices des tuiles à cliquer) ; la variante jeton renvoieresult["token"].
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
Renvoie
result["typed_solution"]— l'action à effectuer, dont la forme dépend degeetest_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]
Renvoie
result["typed_solution"]["grid"]["objects"]— la liste des indices de tuiles à cliquer.
Image vers texte (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
Renvoie
result["typed_solution"]["text"]["texts"][0]— le texte reconnu à saisir.
Puzzle à glissement
Passez le fond et la pièce du puzzle ; vous recevez en retour le décalage horizontal en pixels.
result = solver.solve_slide_image(
images=[Path("background.png"), Path("piece.png")],
)
offset_x = result["typed_solution"]["slide"]["x"] # float (pixels)
Renvoie
result["typed_solution"]["slide"]["x"]— le décalage horizontal en pixels pour faire glisser la pièce.
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"]
Renvoie
result["typed_solution"]— l'action à effectuer, dont la forme dépend detype.
Binance
result = solver.solve_binance(
type="grid", # "grid" | "slide"
question="Select all bicycles", # required for "grid"
images=[Path("grid.png")],
)
solution = result["typed_solution"]
Renvoie
result["typed_solution"]— l'action à effectuer, dont la forme dépend detype.
Utilisation asynchrone
Pour les charges à forte concurrence (gestionnaires FastAPI, spiders Scrapy, pipelines asyncio), utilisez AsyncCaptchaSonic. Il reprend exactement l'API synchrone, mais chaque méthode de résolution est awaitable. Utilisez-le comme gestionnaire de contexte asynchrone afin que le canal sous-jacent soit nettoyé automatiquement.
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())
Le client synchrone prend aussi en charge le protocole de gestionnaire de contexte :
with CaptchaSonic("YOUR_API_KEY") as solver:
result = solver.solve_ocr(images=[Path("captcha.png")])
print(result["typed_solution"]["text"]["texts"][0])
Prise en charge des proxys
Les méthodes à jeton acceptent un argument proxy optionnel (obligatoire pour solve_cloudflare). Utilisez une URL de proxy standard :
proxy = "http://user:pass@host:port"
result = solver.solve_recaptcha_v2_token(
website_url="https://example.com",
website_key="6Le-...",
proxy=proxy,
)
TIP
Fournir un proxy permet à notre solveur de reproduire la localisation géographique et la réputation IP de votre requête, ce qui améliore les taux de réussite sur les sites aux règles anti-bot strictes.
Configuration
Toutes les options sont passées au constructeur du client et s'appliquent aux clients synchrone et asynchrone.
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 | Défaut | Description |
|---|---|---|
transport | "grpc" | Protocole de transport. "grpc" envoie les images sans surcharge base64 ; "http" (nécessite l'extra [http]) envoie du REST/JSON avec des images encodées en base64. |
url | api.captchasonic.com:443 | Remplace le point d'accès de l'API (par exemple pour un environnement auto-hébergé ou de staging). |
timeout | 30.0 | Délai réseau par appel, en secondes. |
polling_interval | 2.0 | Secondes entre deux interrogations pendant l'attente d'une tâche à jeton. |
polling_timeout | 120.0 | Durée maximale, en secondes, d'attente d'une tâche à jeton avant de lever une erreur. |
secure | True | Utilise TLS pour le canal gRPC. |
Les erreurs gRPC transitoires sont relancées automatiquement (jusqu'à 3 tentatives) avec un backoff exponentiel ; vous n'avez donc à gérer que les vraies erreurs métier.
Gestion des erreurs
Toutes les erreurs du SDK héritent de SonicError. Vous pouvez donc tout intercepter avec une seule clause except ou traiter chaque sous-classe séparément. Chaque erreur porte aussi un error_id numérique.
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).
Fonctions utilitaires de compte
balance = solver.get_balance() # current balance in USD (float)
print(f"Balance: ${balance:.2f}")
health = solver.health_check() # HealthCheckResponse — verifies connectivity
Utilisez health_check() comme sonde de disponibilité légère dans vos services, et get_balance() pour conditionner le lancement d'une tâche avant de dépenser des crédits.
Dépannage
TIP
ModuleNotFoundError avec le transport HTTP. Le client HTTP dépend de httpx, qui est une extra optionnelle. Installez-la avec pip install "captchasonic[http]" et définissez transport="http".
- Une tâche à jeton lève une erreur après environ 120 secondes. C'est le
polling_timeout. Augmentez-le pour les cibles lentes, par exempleCaptchaSonic(key, polling_timeout=240.0). solve_cloudflareéchoue immédiatement. L'argumentproxyest obligatoire pour le défi Cloudflare — fournissez une URL de proxy fonctionnelle.- Erreurs de connexion gRPC derrière un proxy d'entreprise ou un pare-feu. gRPC nécessite HTTP/2 sur le port 443. Si votre réseau le bloque, passez à
transport="http". - Les méthodes d'image renvoient des indices, pas un jeton. Les méthodes interactives (
solve_recaptcha_v2,solve_popular_captcha,solve_aws_waf,solve_geetest, etc.) renvoientresult["typed_solution"], qui décrit l'action à effectuer ; seules*_token,solve_turnstileetsolve_cloudflarerenvoientresult["token"].