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

```bash
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:

```bash
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](/app) alın, ardından bakiyenizi [Bakiye ekle](/docs/guides/add-funds) sayfasından yükleyin.

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

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

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

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

---

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

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

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

---

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

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

### reCAPTCHA v2 (token)

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

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

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

### reCAPTCHA v3 (token)

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

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

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

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

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

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

<TaskTypeRef captcha="cloudflare-turnstile" />

### Cloudflare Challenge

Tam Cloudflare challenge'ı bir proxy **gerektirir**.

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

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

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

> 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

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

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

### AWS WAF

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

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

### Görselden metne (OCR)

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

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

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

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

### TikTok

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

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

### Binance

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

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

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

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

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

---

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

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

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

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

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

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

<ErrorIdTable />

---

## Hesap Yardımcıları

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

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

- [PyPI paketi](https://pypi.org/project/captchasonic/)
- [REST API başvurusu](/docs/api)
