Use the easycaptcha Python SDK with requests

Choose the requests transport, reuse sessions, preserve SDK error handling, and avoid treating a failed POST as permission to submit again.

Keep the application API and transport separate

Choose RequestsClient when your application already uses requests and you want that transport behind the SDK’s public methods. Install easycaptcha-sdk[requests], then import from easycaptcha.backends.requests. Backend imports are separate so a urllib-only installation does not need requests just to load the core package.

The SDK supplies job creation, retrieval, feedback, and balance methods. The requests subclass supplies HTTP. Your business logic should call the public methods instead of depending on the subclass’s internal fetch implementation.

Reuse a client for a worker lifetime

import os
from easycaptcha.backends.requests import RequestsClient

with RequestsClient(os.environ["EASYCAPTCHA_API_KEY"]) as client:
    balance = client.get_balance()
    available = int(balance["balance_microcents"])
    job = client.create_job({
        "type": "hcaptcha_token",
        "sitekey": os.environ["HCAPTCHA_SITEKEY"],
        "url": os.environ["HCAPTCHA_PAGE_URL"],
        "hold": 30,
    })
    task_id = job["task_id"]
    # Persist task_id and retrieve it until completed or failed.

A balance read is informative, not a reservation. Another task can consume credit between this read and submission. Handle a definitive insufficient-credit response even when the preceding balance appeared sufficient.

Review session configuration before supplying one

An application-owned session can centralize proxy or network settings. Review it for adapters that retry every HTTP method, headers copied from another service, and logging hooks that record credentials. A generic retry policy that is harmless for a lookup can duplicate paid task creation.

Do not carry a browser session’s cookies into an API-key integration. Keep the account password out of the client constructor. Use a distinct customer key for the installation so it can be revoked independently.

The async requests wrapper runs blocking work in a thread and serializes requests per client. It is useful for compatibility, but native async requirements point toward httpx. Test the actual session configuration you deploy, including timeout handling and an uncertain creation outcome. See task recovery before adding retries around public SDK calls.