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

```bash
pip install captchasonic
```

Transport gRPC terpasang secara default. Untuk juga menggunakan transport HTTP/JSON opsional, instal extra-nya:

```bash
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](/app), lalu isi saldo dari [Tambah dana](/docs/guides/add-funds).

Berikan key sebagai argumen posisi pertama ke client:

<Snippet sdk="python" region="authConstruct" />

> [!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.

<Snippet sdk="python" region="authEnvVar" />

---

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

<MethodRef name="solve_recaptcha_v2_token" lang="python" />

<LangTabs>
  <LangTabs.Tab label="Python">

<Snippet sdk="python" region="solveRecaptchaV2Token_quickstart" />

  </LangTabs.Tab>
  <LangTabs.Tab label="Node">

<Snippet sdk="typescript" region="solveRecaptchaV2Token" />

  </LangTabs.Tab>
</LangTabs>

> 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](#configuration)).

---

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

<Snippet sdk="python" region="imageInputTypes" />

### reCAPTCHA v2 (token)

<MethodRef name="solve_recaptcha_v2_token" lang="python" />

<Snippet sdk="python" region="solveRecaptchaV2Token" />

> Mengembalikan `result["token"]` — kirimkan sebagai `g-recaptcha-response` pada halaman.

### reCAPTCHA v3 (token)

<Snippet sdk="python" region="solveRecaptchaV3Token" />

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

<Snippet sdk="python" region="solveRecaptchaV2" />

> Mengembalikan `result["typed_solution"]["grid"]["objects"]` — daftar indeks tile yang harus diklik.

### Cloudflare Turnstile

<MethodRef name="solve_turnstile" lang="python" />

<LangTabs>
  <LangTabs.Tab label="Python">

<Snippet sdk="python" region="solveTurnstile" />

  </LangTabs.Tab>
  <LangTabs.Tab label="Node">

<Snippet sdk="typescript" region="solveTurnstile" />

  </LangTabs.Tab>
</LangTabs>

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

<TaskTypeRef captcha="cloudflare-turnstile" />

### Cloudflare Challenge

Challenge Cloudflare lengkap **memerlukan** proxy.

<Snippet sdk="python" region="solveCloudflare" />

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

<Snippet sdk="python" region="solvePopularCaptcha" />

> Varian gambar mengembalikan `result["typed_solution"]["grid"]["objects"]` (indeks tile yang diklik); varian token mengembalikan `result["token"]`.

### GeeTest

<Snippet sdk="python" region="solveGeetest" />

> Mengembalikan `result["typed_solution"]` — aksi yang harus dilakukan, bentuknya mengikuti `geetest_type`.

### AWS WAF

<Snippet sdk="python" region="solveAwsWaf" />

> Mengembalikan `result["typed_solution"]["grid"]["objects"]` — daftar indeks tile yang harus diklik.

### Gambar-ke-teks (OCR)

<Snippet sdk="python" region="solveOcr" />

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

<Snippet sdk="python" region="solveSlideImage" />

> Mengembalikan `result["typed_solution"]["slide"]["x"]` — offset piksel horizontal untuk men-drag potongan.

### TikTok

<Snippet sdk="python" region="solveTikTok" />

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

### Binance

<Snippet sdk="python" region="solveBinance" />

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

<Snippet sdk="python" region="asyncUsage" />

Client sinkron juga mendukung protokol context manager:

<Snippet sdk="python" region="syncContextManager" />

---

## Dukungan Proxy

Metode token menerima argumen `proxy` opsional (wajib untuk `solve_cloudflare`). Gunakan URL proxy standar:

<Snippet sdk="python" region="proxyUsage" />

> [!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.

<Snippet sdk="python" region="clientConfiguration" />

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

<Snippet sdk="python" region="errorHandling" />

<ErrorIdTable />

---

## Helper Akun

<Snippet sdk="python" region="accountHelpers" />

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

- [Paket PyPI](https://pypi.org/project/captchasonic/)
- [Referensi REST API](/docs/api)
