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_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 fieldreCAPTCHA token'ını döndürür — sayfanın
g-recaptcha-responsealanı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_keydeğerlerini verirsiniz; SDK altyapımızı sorgular ve gönderime hazırresult["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_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"]
result["token"]döndürür — sayfanıng-recaptcha-responsealanı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ıng-recaptcha-responsealanı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_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 typeTurnstile token'ını döndürür — formun
cf-turnstile-responsealanına gönderin.
AntiTurnstileTask
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'ı.
Popular CAPTCHA (hCaptcha benzeri görsel challenge'lar)
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_typedeğ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,typedeğ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,typedeğ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çenek | Varsayılan | Açı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. |
url | api.captchasonic.com:443 | API uç noktasını geçersiz kıl (ör. kendi barındırdığınız veya staging ortamı için). |
timeout | 30.0 | Çağrı başına ağ zaman aşımı, saniye cinsinden. |
polling_interval | 2.0 | Token görevi beklenirken sorgular arasındaki saniye. |
polling_timeout | 120.0 | Hata fırlatmadan önce token görevi için beklenecek en fazla saniye. |
secure | True | gRPC 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}")
| 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).
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_timeoutdeğeridir. Yavaş hedefler için artırın, ör.CaptchaSonic(key, polling_timeout=240.0). solve_cloudflarehemen başarısız oluyor. Cloudflare challenge'ı içinproxyargü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_geetestvb.) yapılacak eylemi anlatanresult["typed_solution"]döndürür; yalnızca*_token,solve_turnstilevesolve_cloudflareresult["token"]döndürür.