Skip to content
CaptchaSonic

Python SDK

Resmi CaptchaSonic SDK'sı ile Python'dan CAPTCHA çözün — gRPC + HTTP taşıma, asenkron destekli, tam tipli.

Resmi CaptchaSonic Python SDK'sı, desteklenen her CAPTCHA'yı tek bir fonksiyon çağrısına dönüştürür. Hem senkron (CaptchaSonic) hem de asenkron (AsyncCaptchaSonic) istemciyle birlikte gelir, altyapımızla varsayılan olarak gRPC üzerinden iletişim kurar (isteğe bağlı HTTP taşımasıyla), tam tip ipuçları, geçici hatalar için otomatik yeniden deneme ve token tipi sorular için yerleşik sorgulama içerir.


Kurulum

pip install captchasonic

gRPC taşıması varsayılan olarak kurulur. İsteğe bağlı HTTP/JSON taşımasını da kullanmak için ek paketi kurun:

pip install "captchasonic[http]"

TIP

SDK Python 3.10, 3.11, 3.12 ve 3.13 sürümlerini destekler ve MIT lisansı altında yayımlanır.


Kimlik Doğrulama

Bir CaptchaSonic API anahtarına ihtiyacınız var. Bir hesap oluşturun, anahtarınızı panelden alın, ardından bakiyenizi Bakiye ekle sayfasından yükleyin.

Anahtarı istemciye ilk konumsal argüman olarak geçin:

from captchasonic import CaptchaSonic

solver = CaptchaSonic("YOUR_API_KEY")

WARNING

API anahtarınızı bir parola gibi değerlendirin. Kaynak kontrolünün dışında tutun — sabit kodlamak yerine bir ortam değişkeninden veya bir gizli bilgi yöneticisinden yükleyin.

import os
from captchasonic import CaptchaSonic

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

Hızlı Başlangıç

Çoğu token tipi CAPTCHA (reCAPTCHA, Turnstile, hCaptcha) tek bir çağrıyla çözülür. İstemci sizin için sorgular ve görev hazır olduğunda token'ı döndürür.

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

reCAPTCHA token'ını döndürür — sayfanın g-recaptcha-response alanına gönderin.

Token tipi metotlar varsayılan olarak zaman aşımına uğramadan önce 120 saniyeye kadar sorgular (bkz. Yapılandırma).


Desteklenen CAPTCHA Türleri

SDK metotları iki aileye ayırır:

  • Token metotları (*_token, solve_turnstile, solve_cloudflare) — website_url / website_key değerlerini verirsiniz; SDK altyapımızı sorgular ve gönderime hazır result["token"] değerini döndürür.
  • Görsel / etkileşimli metotlar — challenge görsellerini kendiniz verirsiniz; SDK neye tıklanacağını, sürükleneceğini veya yazılacağını anlatan bir result["typed_solution"] döndürür.

Tüm görsel argümanları esnek ImageInput tipini kabul eder — bir dosya yolu (str), bir pathlib.Path, ham bytes veya açık bir ikili dosya nesnesi.

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

result["token"] döndürür — sayfanın g-recaptcha-response alanına gönderin.

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

result["token"] döndürür — sayfanın g-recaptcha-response alanına gönderin.

reCAPTCHA v2 (görsel ızgara)

Challenge karolarına zaten sahipseniz ızgarayı doğrudan çözün ve tıklanacak indeksleri alın.

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]

result["typed_solution"]["grid"]["objects"] döndürür — tıklanacak karo indekslerinin listesi.

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

Turnstile token'ını döndürür — formun cf-turnstile-response alanına gönderin.

REST task typeAntiTurnstileTask

Cloudflare Challenge

Tam Cloudflare challenge'ı bir proxy gerektirir.

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

result["token"] döndürür — korumalı istek için yetkilendirme (clearance) token'ı.

solve_popular_captcha etkileşimli görsel varyantlarını yönetir; solve_popular_captcha_token doğrudan bir token döndürür.

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

Görsel varyantı result["typed_solution"]["grid"]["objects"] döndürür (tıklanacak karo indeksleri); token varyantı result["token"] döndürür.

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

result["typed_solution"] döndürür — yapılacak eylem, geetest_type değerine göre şekillenir.

AWS WAF

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

result["typed_solution"]["grid"]["objects"] döndürür — tıklanacak karo indekslerinin listesi.

Görselden metne (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

result["typed_solution"]["text"]["texts"][0] döndürür — yazılacak tanınmış metin.

Kaydırmalı bulmaca

Arka planı ve bulmaca parçasını verin; kaydırılacak yatay piksel ofsetini geri alırsınız.

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

result["typed_solution"]["slide"]["x"] döndürür — parçayı sürüklemek için yatay piksel ofseti.

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

result["typed_solution"] döndürür — yapılacak eylem, type değerine göre şekillenir.

Binance

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

result["typed_solution"] döndürür — yapılacak eylem, type değerine göre şekillenir.


Asenkron Kullanım

Yüksek eşzamanlılık iş yükleri için (FastAPI işleyicileri, Scrapy örümcekleri, asyncio hatları) AsyncCaptchaSonic kullanın. Senkron API'yi birebir yansıtır, ancak her çözme metodu beklenebilir (await) durumdadır. Altta yatan kanalın otomatik olarak temizlenmesi için bunu asenkron bir bağlam yöneticisi olarak kullanın.

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

Senkron istemci de bağlam yöneticisi protokolünü destekler:

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

Proxy Desteği

Token metotları isteğe bağlı bir proxy argümanı kabul eder (solve_cloudflare için zorunludur). Standart bir proxy URL'si kullanın:

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

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

TIP

Bir proxy vermek, çözücümüzün isteğinizin coğrafi konumunu ve IP itibarını yansıtmasını sağlar; bu da katı anti-bot kuralları olan sitelerde başarı oranlarını artırır.


Yapılandırma

Tüm seçenekler istemci kurucusuna geçirilir ve hem senkron hem asenkron istemcilere uygulanır.

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
)
SeçenekVarsayılanAçıklama
transport"grpc"Tel protokolü. "grpc" görselleri sıfır base64 ek yüküyle gönderir; "http" ([http] ek paketi gerektirir) base64 kodlanmış görsellerle REST/JSON gönderir.
urlapi.captchasonic.com:443API uç noktasını geçersiz kıl (ör. kendi barındırdığınız veya staging ortamı için).
timeout30.0Çağrı başına ağ zaman aşımı, saniye cinsinden.
polling_interval2.0Token görevi beklenirken sorgular arasındaki saniye.
polling_timeout120.0Hata fırlatmadan önce token görevi için beklenecek en fazla saniye.
secureTruegRPC kanalı için TLS kullan.

Geçici gRPC hataları üssel geri çekilmeyle otomatik olarak yeniden denenir (en fazla 3 deneme); bu yüzden yalnızca gerçek iş hatalarını ele almanız gerekir.


Hata Yönetimi

Tüm SDK hataları SonicError sınıfından türer; böylece her şeyi tek bir except bloğuyla yakalayabilir ya da belirli alt sınıfa göre dallanabilirsiniz. Her hata ayrıca sayısal bir error_id taşır.

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


Hesap Yardımcıları

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

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

Servislerde hafif bir hazırlık kontrolü olarak health_check() kullanın; kredi harcamaya başlamadan önce işleri kapılamak için get_balance() kullanın.


Sorun Giderme

TIP

HTTP taşımasını kullanırken ModuleNotFoundError. HTTP istemcisi, isteğe bağlı bir ek olan httpx'e bağlıdır. pip install "captchasonic[http]" ile kurun ve transport="http" ayarlayın.

  • Bir token görevi yaklaşık 120 saniye sonra hata fırlatıyor. Bu, polling_timeout değeridir. Yavaş hedefler için artırın, ör. CaptchaSonic(key, polling_timeout=240.0).
  • solve_cloudflare hemen başarısız oluyor. Cloudflare challenge'ı için proxy argümanı zorunludur — çalışan bir proxy URL'si verin.
  • Kurumsal proxy/güvenlik duvarı arkasında gRPC bağlantı hataları. gRPC, 443 numaralı bağlantı noktası üzerinden HTTP/2 gerektirir. Ağınız bunu engelliyorsa transport="http" seçeneğine geçin.
  • Görsel metotlar token değil indeks döndürüyor. Etkileşimli metotlar (solve_recaptcha_v2, solve_popular_captcha, solve_aws_waf, solve_geetest vb.) yapılacak eylemi anlatan result["typed_solution"] döndürür; yalnızca *_token, solve_turnstile ve solve_cloudflare result["token"] döndürür.

Kaynaklar