Skip to content
CaptchaSonic

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

Renvoie le jeton reCAPTCHA — soumettez-le comme g-recaptcha-response de 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 un website_url / website_key, le SDK interroge notre infrastructure et renvoie un result["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_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"]

Renvoie result["token"] — soumettez-le comme g-recaptcha-response de 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 comme g-recaptcha-response de 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_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"]

Renvoie le jeton Turnstile — soumettez-le comme cf-turnstile-response du formulaire.

REST task typeAntiTurnstileTask

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.

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 renvoie result["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 de 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]

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 de 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"]

Renvoie result["typed_solution"] — l'action à effectuer, dont la forme dépend de type.


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
)
OptionDéfautDescription
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.
urlapi.captchasonic.com:443Remplace le point d'accès de l'API (par exemple pour un environnement auto-hébergé ou de staging).
timeout30.0Délai réseau par appel, en secondes.
polling_interval2.0Secondes entre deux interrogations pendant l'attente d'une tâche à jeton.
polling_timeout120.0Durée maximale, en secondes, d'attente d'une tâche à jeton avant de lever une erreur.
secureTrueUtilise 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}")
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).


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 exemple CaptchaSonic(key, polling_timeout=240.0).
  • solve_cloudflare échoue immédiatement. L'argument proxy est 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.) renvoient result["typed_solution"], qui décrit l'action à effectuer ; seules *_token, solve_turnstile et solve_cloudflare renvoient result["token"].

Ressources