Skip to content
CaptchaSonic

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

Mengembalikan token reCAPTCHA — kirimkan sebagai g-recaptcha-response pada 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 memberikan website_url / website_key, SDK melakukan polling ke infrastruktur kami dan mengembalikan result["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_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"]

Mengembalikan result["token"] — kirimkan sebagai g-recaptcha-response pada 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 sebagai g-recaptcha-response pada 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_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"]

Mengembalikan token Turnstile — kirimkan sebagai cf-turnstile-response pada form.

REST task typeAntiTurnstileTask

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.

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

Mengembalikan result["typed_solution"] — aksi yang harus dilakukan, bentuknya mengikuti 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]

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

Mengembalikan result["typed_solution"] — aksi yang harus dilakukan, bentuknya mengikuti type.


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
)
OpsiDefaultDeskripsi
transport"grpc"Protokol kabel. "grpc" mengirim gambar tanpa overhead base64; "http" (memerlukan extra [http]) mengirim REST/JSON dengan gambar ber-encode base64.
urlapi.captchasonic.com:443Mengganti endpoint API (mis. untuk self-hosted atau staging).
timeout30.0Batas waktu jaringan per panggilan, dalam detik.
polling_interval2.0Jeda antar polling detik saat menunggu task token.
polling_timeout120.0Waktu tunggu maksimum dalam detik untuk task token sebelum error dilempar.
secureTrueGunakan 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}")
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).


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_cloudflare langsung gagal. Argumen proxy wajib 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.) mengembalikan result["typed_solution"] yang menjelaskan aksi yang harus diambil; hanya *_token, solve_turnstile, dan solve_cloudflare yang mengembalikan result["token"].

Sumber Daya