SDK Python
Selesaikan CAPTCHA dari Python dengan SDK resmi CaptchaSonic — transport gRPC + HTTP, siap async, bertipe penuh.
SDK Python CaptchaSonic resmi mengubah setiap CAPTCHA yang didukung menjadi satu pemanggilan fungsi. SDK ini menyediakan client sinkron (CaptchaSonic) dan asinkron (AsyncCaptchaSonic), berkomunikasi dengan infrastruktur kami melalui gRPC secara default (dengan transport HTTP opsional), serta menyertakan type hint lengkap, percobaan ulang otomatis untuk error sementara, dan polling bawaan untuk tantangan berbasis token.
Instalasi
pip install captchasonic
Transport gRPC terpasang secara default. Untuk juga menggunakan transport HTTP/JSON opsional, instal extra-nya:
pip install "captchasonic[http]"
TIP
SDK ini mendukung Python 3.10, 3.11, 3.12, dan 3.13 serta dipublikasikan di bawah lisensi MIT.
Autentikasi
Anda memerlukan API key CaptchaSonic. Buat akun dan ambil key Anda dari dashboard, lalu isi saldo dari Tambah dana.
Berikan key sebagai argumen posisi pertama ke client:
from captchasonic import CaptchaSonic
solver = CaptchaSonic("YOUR_API_KEY")
WARNING
Perlakukan API key Anda seperti kata sandi. Jangan simpan di source control — muat dari variabel environment atau secrets manager, jangan tulis langsung di kode.
import os
from captchasonic import CaptchaSonic
solver = CaptchaSonic(os.environ["CAPTCHASONIC_API_KEY"])
Mulai Cepat
Sebagian besar CAPTCHA berbasis token (reCAPTCHA, Turnstile, hCaptcha) diselesaikan dengan satu pemanggilan. Client melakukan polling untuk Anda dan mengembalikan token setelah task siap.
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 fieldMengembalikan token reCAPTCHA — kirimkan sebagai
g-recaptcha-responsepada halaman.
Metode berbasis token melakukan polling hingga 120 detik secara default sebelum kehabisan waktu (lihat Konfigurasi).
Jenis CAPTCHA yang Didukung
SDK membagi metode menjadi dua keluarga:
- Metode token (
*_token,solve_turnstile,solve_cloudflare) — Anda memberikanwebsite_url/website_key, SDK melakukan polling ke infrastruktur kami dan mengembalikanresult["token"]yang siap dikirim. - Metode gambar / interaktif — Anda memberikan gambar tantangan sendiri, dan SDK mengembalikan
result["typed_solution"]yang menjelaskan apa yang harus diklik, di-drag, atau diketik.
Semua argumen gambar menerima tipe fleksibel ImageInput — path file (str), pathlib.Path, bytes mentah, atau objek file biner yang terbuka.
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"]
Mengembalikan
result["token"]— kirimkan sebagaig-recaptcha-responsepada halaman.
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"]
Mengembalikan
result["token"]— kirimkan sebagaig-recaptcha-responsepada halaman.
reCAPTCHA v2 (grid gambar)
Jika Anda sudah memiliki tile tantangan, selesaikan grid secara langsung dan terima indeks yang harus diklik.
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]
Mengembalikan
result["typed_solution"]["grid"]["objects"]— daftar indeks tile yang harus diklik.
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 typeMengembalikan token Turnstile — kirimkan sebagai
cf-turnstile-responsepada form.
AntiTurnstileTask
Cloudflare Challenge
Challenge Cloudflare lengkap memerlukan proxy.
result = solver.solve_cloudflare(
website_url="https://example.com",
website_key="0x4AAAAAAA...",
proxy="http://user:pass@host:port", # required
)
token = result["token"]
Mengembalikan
result["token"]— token clearance untuk permintaan yang dilindungi.
Popular CAPTCHA (tantangan gambar gaya hCaptcha)
solve_popular_captcha menangani varian gambar interaktif; solve_popular_captcha_token mengembalikan token secara langsung.
# 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"]
Varian gambar mengembalikan
result["typed_solution"]["grid"]["objects"](indeks tile yang diklik); varian token mengembalikanresult["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
Mengembalikan
result["typed_solution"]— aksi yang harus dilakukan, bentuknya mengikutigeetest_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]
Mengembalikan
result["typed_solution"]["grid"]["objects"]— daftar indeks tile yang harus diklik.
Gambar-ke-teks (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
Mengembalikan
result["typed_solution"]["text"]["texts"][0]— teks yang dikenali untuk diketik.
Puzzle slide
Berikan background dan potongan puzzle; Anda akan mendapatkan offset piksel horizontal untuk digeser.
result = solver.solve_slide_image(
images=[Path("background.png"), Path("piece.png")],
)
offset_x = result["typed_solution"]["slide"]["x"] # float (pixels)
Mengembalikan
result["typed_solution"]["slide"]["x"]— offset piksel horizontal untuk men-drag potongan.
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"]
Mengembalikan
result["typed_solution"]— aksi yang harus dilakukan, bentuknya mengikutitype.
Binance
result = solver.solve_binance(
type="grid", # "grid" | "slide"
question="Select all bicycles", # required for "grid"
images=[Path("grid.png")],
)
solution = result["typed_solution"]
Mengembalikan
result["typed_solution"]— aksi yang harus dilakukan, bentuknya mengikutitype.
Penggunaan Async
Untuk beban kerja konkurensi tinggi (handler FastAPI, spider Scrapy, pipeline asyncio) gunakan AsyncCaptchaSonic. API-nya identik dengan versi sinkron, tetapi setiap metode solve dapat di-await. Gunakan sebagai async context manager agar channel yang mendasarinya dibersihkan secara otomatis.
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())
Client sinkron juga mendukung protokol context manager:
with CaptchaSonic("YOUR_API_KEY") as solver:
result = solver.solve_ocr(images=[Path("captcha.png")])
print(result["typed_solution"]["text"]["texts"][0])
Dukungan Proxy
Metode token menerima argumen proxy opsional (wajib untuk solve_cloudflare). Gunakan URL proxy standar:
proxy = "http://user:pass@host:port"
result = solver.solve_recaptcha_v2_token(
website_url="https://example.com",
website_key="6Le-...",
proxy=proxy,
)
TIP
Dengan menyertakan proxy, solver kami dapat mencerminkan lokasi geografis dan reputasi IP permintaan Anda, sehingga meningkatkan tingkat keberhasilan pada situs dengan aturan anti-bot yang ketat.
Konfigurasi
Semua opsi diberikan ke constructor client dan berlaku untuk client sinkron maupun async.
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
)
| Opsi | Default | Deskripsi |
|---|---|---|
transport | "grpc" | Protokol kabel. "grpc" mengirim gambar tanpa overhead base64; "http" (memerlukan extra [http]) mengirim REST/JSON dengan gambar ber-encode base64. |
url | api.captchasonic.com:443 | Mengganti endpoint API (mis. untuk self-hosted atau staging). |
timeout | 30.0 | Batas waktu jaringan per panggilan, dalam detik. |
polling_interval | 2.0 | Jeda antar polling detik saat menunggu task token. |
polling_timeout | 120.0 | Waktu tunggu maksimum dalam detik untuk task token sebelum error dilempar. |
secure | True | Gunakan TLS untuk channel gRPC. |
Error gRPC sementara dicoba ulang secara otomatis (hingga 3 percobaan) dengan exponential backoff, sehingga Anda hanya perlu menangani error bisnis yang sebenarnya.
Penanganan Error
Semua error SDK mewarisi dari SonicError, sehingga Anda dapat menangkap semuanya dengan satu klausa except atau bercabang pada subclass tertentu. Setiap error juga membawa error_id numerik.
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).
Helper Akun
balance = solver.get_balance() # current balance in USD (float)
print(f"Balance: ${balance:.2f}")
health = solver.health_check() # HealthCheckResponse — verifies connectivity
Gunakan health_check() sebagai probe kesiapan yang ringan di layanan dan get_balance() untuk membatasi job sebelum Anda mulai menggunakan kredit.
Pemecahan Masalah
TIP
ModuleNotFoundError saat menggunakan transport HTTP. Client HTTP bergantung pada httpx, yang merupakan extra opsional. Instal dengan pip install "captchasonic[http]" dan atur transport="http".
- Task token melempar error setelah sekitar 120 detik. Itu adalah
polling_timeout. Tingkatkan untuk target yang lambat, mis.CaptchaSonic(key, polling_timeout=240.0). solve_cloudflarelangsung gagal. Argumenproxywajib untuk challenge Cloudflare — berikan URL proxy yang berfungsi.- Error koneksi gRPC di balik proxy/firewall perusahaan. gRPC memerlukan HTTP/2 melalui port 443. Jika jaringan Anda memblokirnya, ganti ke
transport="http". - Metode gambar mengembalikan indeks, bukan token. Metode interaktif (
solve_recaptcha_v2,solve_popular_captcha,solve_aws_waf,solve_geetest, dll.) mengembalikanresult["typed_solution"]yang menjelaskan aksi yang harus diambil; hanya*_token,solve_turnstile, dansolve_cloudflareyang mengembalikanresult["token"].