Use curl_cffi as an easycaptcha SDK transport

Integrate the curl_cffi backend without changing public SDK methods, and keep API transport settings separate from token-worker proxy settings.

Install only the transport you need

The SDK’s curl_cffi transport is available through easycaptcha-sdk[curl-cffi]. Import CurlCffiClient or AsyncCurlCffiClient from easycaptcha.backends.curl_cffi. The core package does not import every optional transport, so another application can use urllib without installing this dependency.

Use this backend when curl_cffi already fits your networking environment. Selecting it does not change the supported task types, grant more account concurrency, or make a submitted proof acceptable to a website.

Preserve the common job lifecycle

import os
from easycaptcha.backends.curl_cffi import CurlCffiClient

with CurlCffiClient(os.environ["EASYCAPTCHA_API_KEY"]) as client:
    job = client.create_job({
        "type": "hcaptcha_token",
        "sitekey": os.environ["HCAPTCHA_SITEKEY"],
        "url": os.environ["HCAPTCHA_PAGE_URL"],
    })
    print(job["task_id"], job["status"])

This example creates work and displays the initial state. It does not assume a token exists immediately. Persist the ID and look it up until completion or failure using the Python lifecycle example.

Both classes can accept an application-owned session. That application’s lifecycle must close the session when it is finished. The SDK closes sessions it creates itself. Match an async session with the async class instead of wrapping asynchronous networking in a synchronous call path.

Distinguish two separate proxy decisions

A transport proxy controls the request from your application to easycaptcha. A token request’s proxy field supplies networking information to the token worker. Configuring one does not automatically configure the other. Keep their credentials and troubleshooting records separate.

Review client logs and session configuration for copied cookies, secrets, and broad retry settings. An HTTP failure while creating a task can leave the outcome uncertain. Changing HTTP libraries does not make that POST safe to repeat without investigation.

Evaluate transport compatibility independently of solver outcomes: first prove that requests and errors are serialized correctly, then measure observed task acceptance. The proxy guide describes worker proxy fields, while the httpx guide shows another session-ownership pattern.