# Python

> Exemples Python pour YesCaptcha : consulter le solde, lire un captcha image, une classe cliente réutilisable (création de tâche, interrogation périodique (polling) toutes les 5 secondes), contrôle des tâches simultanées avec asyncio, et envoi de reCAPTCHA avec requests et Selenium.

Source: https://docs.yescaptcha.com/fr/samples/python/ · Last verified: 2026-10-15

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/samples/python/

Prérequis : Python 3.8 ou supérieur, et `pip install requests`. Définissez la variable d’environnement avant l’exécution :

```bash
export YESCAPTCHA_CLIENT_KEY=your_client_key
```

## Consulter le solde

Gratuit ; permet de vérifier que le ClientKey est correct :

get_balance.py

```python
"""Check the balance. getBalance is free and is a quick way to verify your clientKey."""
import os

import requests

CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]

r = requests.post(
    "https://api.yescaptcha.com/getBalance",
    json={"clientKey": CLIENT_KEY},
    timeout=30,
)
data = r.json()
if data.get("errorId"):
    # e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
    print("error:", data.get("errorCode"), data.get("errorDescription"))
else:
    print("balance (points):", data["balance"])
```

## Lire un captcha image

Le type synchrone `ImageToTextTaskOcrBase` renvoie le résultat en une seule requête. Image d’exemple : [captcha.jpg](https://docs.yescaptcha.com/samples/captcha.jpg).

quickstart.py

```python
"""First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase
(synchronous, 2 points per image).

Usage:
    export YESCAPTCHA_CLIENT_KEY=your_client_key
    python quickstart.py captcha.png
"""
import base64
import os
import sys

import requests

CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
image_path = sys.argv[1] if len(sys.argv) > 1 else "captcha.png"

with open(image_path, "rb") as f:
    body = base64.b64encode(f.read()).decode()  # no "data:" prefix

r = requests.post(
    "https://api.yescaptcha.com/createTask",
    json={
        "clientKey": CLIENT_KEY,
        "task": {"type": "ImageToTextTaskOcrBase", "body": body},
    },
    timeout=30,
)
data = r.json()
if data.get("errorId"):
    raise SystemExit(f"{data.get('errorCode')}: {data.get('errorDescription')}")
print("text:", data["solution"]["text"])
```

## Un client réutilisable

Copiez ce fichier dans votre projet ; il gère les types synchrones comme asynchrones :

yescaptcha.py

```python
"""A small client you can copy into your project: create tasks, poll results, check the balance.

    from yescaptcha import YesCaptcha
    client = YesCaptcha(os.environ["YESCAPTCHA_CLIENT_KEY"])
    solution = client.solve({
        "type": "NoCaptchaTaskProxyless",
        "websiteURL": "https://www.google.com/recaptcha/api2/demo",
        "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    })
    print(solution["gRecaptchaResponse"])
"""
import os
import time

import requests

class YesCaptchaError(Exception):
    def __init__(self, code, description):
        super().__init__(f"{code}: {description}")
        self.code = code
        self.description = description

class YesCaptcha:
    def __init__(self, client_key, endpoint="https://api.yescaptcha.com", poll_interval=5, timeout=180):
        self.client_key = client_key
        self.endpoint = endpoint.rstrip("/")
        self.poll_interval = poll_interval  # 5 s: polling the same taskId more often only returns "processing"
        self.timeout = timeout
        self.session = requests.Session()

    def call(self, method, payload=None):
        body = {"clientKey": self.client_key, **(payload or {})}
        data = self.session.post(f"{self.endpoint}/{method}", json=body, timeout=30).json()
        if data.get("errorId"):
            raise YesCaptchaError(data.get("errorCode"), data.get("errorDescription"))
        return data

    def balance(self):
        return self.call("getBalance")["balance"]

    def solve(self, task):
        created = self.call("createTask", {"task": task})
        if created.get("status") == "ready":  # synchronous types return the solution directly
            return created["solution"]
        task_id = created["taskId"]
        deadline = time.time() + self.timeout
        while time.time() < deadline:
            time.sleep(self.poll_interval)
            result = self.call("getTaskResult", {"taskId": task_id})
            if result.get("status") == "ready":
                return result["solution"]
        raise TimeoutError(f"task {task_id} not ready after {self.timeout}s")

if __name__ == "__main__":
    client = YesCaptcha(os.environ["YESCAPTCHA_CLIENT_KEY"])
    print("balance:", client.balance())
```

```python
from yescaptcha import YesCaptcha

client = YesCaptcha(os.environ["YESCAPTCHA_CLIENT_KEY"])
solution = client.solve({
    "type": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
})
print(solution["gRecaptchaResponse"])
```

En cas d’erreur, `YesCaptchaError` est levée ; `e.code` contient le code d’erreur (voir [Codes d’erreur](https://docs.yescaptcha.com/fr/api/errors.md)).

## Contrôler les tâches simultanées

Lorsque vous envoyez des tâches en lot, limitez le nombre de requêtes en cours de traitement en même temps, et patientez avant de réessayer si vous recevez `ERROR_THREADS_MAXIMUM` (nécessite `pip install aiohttp`). Voir [Limite de tâches simultanées et suspension automatique](https://docs.yescaptcha.com/fr/api/rate-limits.md) :

concurrency.py

```python
"""Limit concurrency: keep the number of requests waiting for a result below your limit, and back off
on ERROR_THREADS_MAXIMUM (rejected requests are not charged). Requires: pip install aiohttp"""
import asyncio
import os

import aiohttp

CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
LIMIT = 15  # below your concurrency limit
sem = asyncio.Semaphore(LIMIT)

async def solve(session, task):
    async with sem:  # at most LIMIT requests in progress at a time
        result = {}
        for attempt in range(5):
            async with session.post(
                "https://api.yescaptcha.com/createTask",
                json={"clientKey": CLIENT_KEY, "task": task},
            ) as resp:
                result = await resp.json()
            if result.get("errorCode") != "ERROR_THREADS_MAXIMUM":
                return result
            await asyncio.sleep(1 + attempt)  # over the limit: wait and retry
        return result

async def main(tasks):
    async with aiohttp.ClientSession() as session:
        return await asyncio.gather(*(solve(session, t) for t in tasks))

if __name__ == "__main__":
    print(asyncio.run(main([])))
```

## Envoyer un token reCAPTCHA

-   Envoyer directement avec requests : voir [Valider un reCAPTCHA avec un token](https://docs.yescaptcha.com/fr/guides/submit-recaptcha-token.md)
-   Remplir le token dans le navigateur avec Selenium : voir [Valider un reCAPTCHA avec un token](https://docs.yescaptcha.com/fr/guides/submit-recaptcha-token.md)
-   Simuler les clics sur les épreuves d’images avec Selenium : voir [Clics simulés pour la reconnaissance d’images reCAPTCHA v2](https://docs.yescaptcha.com/fr/guides/recaptcha-click-selenium.md), [Clics simulés pour la reconnaissance d’images hCaptcha](https://docs.yescaptcha.com/fr/guides/hcaptcha-click-selenium.md)