Le **SDK Python officiel de CaptchaSonic** transforme chaque CAPTCHA pris en charge en un seul appel de fonction. Il fournit un client synchrone (`CaptchaSonic`) et un client asynchrone (`AsyncCaptchaSonic`), communique avec notre infrastructure en **gRPC par défaut** (avec un transport HTTP optionnel), et inclut des annotations de types complètes, des relances automatiques pour les erreurs transitoires et une interrogation intégrée pour les défis à jeton.

---

## Installation

```bash
pip install captchasonic
```

Le transport gRPC est installé par défaut. Pour utiliser aussi le transport HTTP/JSON optionnel, installez l'extra :

```bash
pip install "captchasonic[http]"
```

> [!TIP]
> Le SDK prend en charge **Python 3.10, 3.11, 3.12 et 3.13** et est publié sous licence MIT.

---

## Authentification

Il vous faut une clé API CaptchaSonic. Créez un compte et récupérez votre clé depuis le [tableau de bord](/app), puis rechargez votre solde depuis [Ajouter des fonds](/docs/guides/add-funds).

Passez la clé en premier argument positionnel du client :

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

> [!WARNING]
> Traitez votre clé API comme un mot de passe. Ne la versionnez pas : chargez-la depuis une variable d'environnement ou un gestionnaire de secrets plutôt que de la coder en dur.

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

---

## Démarrage rapide

La plupart des CAPTCHA à jeton (reCAPTCHA, Turnstile, hCaptcha) se résolvent en un seul appel. Le client interroge le résultat pour vous et renvoie le jeton dès que la tâche est prête.

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

> Renvoie le jeton reCAPTCHA — soumettez-le comme `g-recaptcha-response` de la page.

Par défaut, les méthodes à jeton interrogent le résultat pendant 120 secondes au maximum avant d'expirer (voir [Configuration](#configuration)).

---

## Types de CAPTCHA pris en charge

Le SDK répartit les méthodes en deux familles :

- **Méthodes à jeton** (`*_token`, `solve_turnstile`, `solve_cloudflare`) — vous fournissez un `website_url` / `website_key`, le SDK interroge notre infrastructure et renvoie un `result["token"]` prêt à être soumis.
- **Méthodes image / interactives** — vous fournissez vous-même les images du défi, et le SDK renvoie un `result["typed_solution"]` décrivant ce qu'il faut cliquer, glisser ou saisir.

Tous les arguments d'image acceptent le type souple `ImageInput` — un chemin de fichier (`str`), un `pathlib.Path`, des `bytes` bruts ou un objet fichier binaire ouvert.

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

### reCAPTCHA v2 (jeton)

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

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

> Renvoie `result["token"]` — soumettez-le comme `g-recaptcha-response` de la page.

### reCAPTCHA v3 (jeton)

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

> Renvoie `result["token"]` — soumettez-le comme `g-recaptcha-response` de la page.

### reCAPTCHA v2 (grille d'images)

Lorsque vous avez déjà les tuiles du défi, résolvez directement la grille et recevez les indices à cliquer.

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

> Renvoie `result["typed_solution"]["grid"]["objects"]` — la liste des indices de tuiles à cliquer.

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

> Renvoie le jeton Turnstile — soumettez-le comme `cf-turnstile-response` du formulaire.

<TaskTypeRef captcha="cloudflare-turnstile" />

### Défi Cloudflare

Le défi Cloudflare complet **nécessite** un proxy.

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

> Renvoie `result["token"]` — le jeton de clearance pour la requête protégée.

### CAPTCHA populaires (défis d'images de style hCaptcha)

`solve_popular_captcha` gère les variantes d'images interactives ; `solve_popular_captcha_token` renvoie directement un jeton.

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

> La variante image renvoie `result["typed_solution"]["grid"]["objects"]` (indices des tuiles à cliquer) ; la variante jeton renvoie `result["token"]`.

### GeeTest

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

> Renvoie `result["typed_solution"]` — l'action à effectuer, dont la forme dépend de `geetest_type`.

### AWS WAF

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

> Renvoie `result["typed_solution"]["grid"]["objects"]` — la liste des indices de tuiles à cliquer.

### Image vers texte (OCR)

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

> Renvoie `result["typed_solution"]["text"]["texts"][0]` — le texte reconnu à saisir.

### Puzzle à glissement

Passez le fond et la pièce du puzzle ; vous recevez en retour le décalage horizontal en pixels.

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

> Renvoie `result["typed_solution"]["slide"]["x"]` — le décalage horizontal en pixels pour faire glisser la pièce.

### TikTok

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

> Renvoie `result["typed_solution"]` — l'action à effectuer, dont la forme dépend de `type`.

### Binance

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

> Renvoie `result["typed_solution"]` — l'action à effectuer, dont la forme dépend de `type`.

---

## Utilisation asynchrone

Pour les charges à forte concurrence (gestionnaires FastAPI, spiders Scrapy, pipelines asyncio), utilisez `AsyncCaptchaSonic`. Il reprend exactement l'API synchrone, mais chaque méthode de résolution est awaitable. Utilisez-le comme gestionnaire de contexte asynchrone afin que le canal sous-jacent soit nettoyé automatiquement.

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

Le client synchrone prend aussi en charge le protocole de gestionnaire de contexte :

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

---

## Prise en charge des proxys

Les méthodes à jeton acceptent un argument `proxy` optionnel (obligatoire pour `solve_cloudflare`). Utilisez une URL de proxy standard :

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

> [!TIP]
> Fournir un proxy permet à notre solveur de reproduire la localisation géographique et la réputation IP de votre requête, ce qui améliore les taux de réussite sur les sites aux règles anti-bot strictes.

---

## Configuration

Toutes les options sont passées au constructeur du client et s'appliquent aux clients synchrone et asynchrone.

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

| Option | Défaut | Description |
| :--- | :--- | :--- |
| `transport` | `"grpc"` | Protocole de transport. `"grpc"` envoie les images sans surcharge base64 ; `"http"` (nécessite l'extra `[http]`) envoie du REST/JSON avec des images encodées en base64. |
| `url` | `api.captchasonic.com:443` | Remplace le point d'accès de l'API (par exemple pour un environnement auto-hébergé ou de staging). |
| `timeout` | `30.0` | Délai réseau par appel, en secondes. |
| `polling_interval` | `2.0` | Secondes entre deux interrogations pendant l'attente d'une tâche à jeton. |
| `polling_timeout` | `120.0` | Durée maximale, en secondes, d'attente d'une tâche à jeton avant de lever une erreur. |
| `secure` | `True` | Utilise TLS pour le canal gRPC. |

Les erreurs gRPC transitoires sont relancées automatiquement (jusqu'à 3 tentatives) avec un backoff exponentiel ; vous n'avez donc à gérer que les vraies erreurs métier.

---

## Gestion des erreurs

Toutes les erreurs du SDK héritent de `SonicError`. Vous pouvez donc tout intercepter avec une seule clause `except` ou traiter chaque sous-classe séparément. Chaque erreur porte aussi un `error_id` numérique.

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

<ErrorIdTable />

---

## Fonctions utilitaires de compte

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

Utilisez `health_check()` comme sonde de disponibilité légère dans vos services, et `get_balance()` pour conditionner le lancement d'une tâche avant de dépenser des crédits.

---

## Dépannage

> [!TIP]
> **`ModuleNotFoundError` avec le transport HTTP.** Le client HTTP dépend de `httpx`, qui est une extra optionnelle. Installez-la avec `pip install "captchasonic[http]"` et définissez `transport="http"`.

- **Une tâche à jeton lève une erreur après environ 120 secondes.** C'est le `polling_timeout`. Augmentez-le pour les cibles lentes, par exemple `CaptchaSonic(key, polling_timeout=240.0)`.
- **`solve_cloudflare` échoue immédiatement.** L'argument `proxy` est obligatoire pour le défi Cloudflare — fournissez une URL de proxy fonctionnelle.
- **Erreurs de connexion gRPC derrière un proxy d'entreprise ou un pare-feu.** gRPC nécessite HTTP/2 sur le port 443. Si votre réseau le bloque, passez à `transport="http"`.
- **Les méthodes d'image renvoient des indices, pas un jeton.** Les méthodes interactives (`solve_recaptcha_v2`, `solve_popular_captcha`, `solve_aws_waf`, `solve_geetest`, etc.) renvoient `result["typed_solution"]`, qui décrit l'action à effectuer ; seules `*_token`, `solve_turnstile` et `solve_cloudflare` renvoient `result["token"]`.

---

## Ressources

- [Package PyPI](https://pypi.org/project/captchasonic/)
- [Référence de l'API REST](/docs/api)
