captcha-solver-api 1.0.0__tar.gz → 1.0.1__tar.gz

{captcha_solver_api-1.0.0 → captcha_solver_api-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: captcha-solver-api
-Version: 1.0.0
+Version: 1.0.1
 Summary: Official Python SDK for solving reCAPTCHA v2/v3, Cloudflare Turnstile, GeeTest v3/v4, Yandex SmartCaptcha, Tencent, and image/click captchas via the Captcha Solver API
 Author: Captcha Solver Team
 License-Expression: MIT
@@ -110,7 +110,7 @@ client = CaptchaClient("your_api_key")
 
 ## Quick Start
 
-Solve a reCAPTCHA v2 in 4 lines.
+Solve a reCAPTCHA v2 with a task object and one `solve()` call.
 
 ```python
 from captcha_solver_api import CaptchaClient
@@ -156,8 +156,8 @@ Constructor.
 |---|---|---|---|
 | `client_key` | `str` | required | Your Captcha Solver API key. Raises `ValidationError` if empty. |
 | `base_url` | `str` | `https://api.captcha-solver.com` | API base URL. Override only for self-hosted/staging deployments. |
-| `timeout` | `int` | `120` | Default max seconds `solve()` waits for a solution before raising `CaptchaTimeoutError`. Overridable per call. |
-| `polling_interval` | `int` | `3` | Seconds between `getTaskResult` polls inside `solve()`. |
+| `timeout` | `int` | `120` | Polling window after task creation, in seconds. Overridable per call; each HTTP request has a separate 30-second timeout. |
+| `polling_interval` | `int` | `10` | Seconds before the first `getTaskResult` poll and between subsequent polls, matching the official 2Captcha Python SDK. |
 | `language_pool` | `Optional[str]` | `None` | Default worker pool (`"en"` or `"ru"`) applied to every call that doesn't pass its own `language_pool`. |
 
 Both clients hold a reusable connection pool (`requests.Session` / `httpx.AsyncClient`)
@@ -191,9 +191,9 @@ Raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
 ### `create_task(task, language_pool=None)`
 
 Submits `task` and returns its numeric task ID without waiting for a solution.
-Same parameters as `solve()`. Use this instead of `solve()` only if you need to
+Accepts `task` and `language_pool`; it does not accept `timeout`. Use this instead of `solve()` if you need to
 manage polling yourself (e.g. checking on many tasks from a different process).
-Raises `ApiError`, `NetworkError`.
+Raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
 
 ### `get_task_result(task_id)`
 
@@ -201,12 +201,12 @@ Fetches the current status of a task created with `create_task()`. Always
 returns a dict with a `status` key (`"processing"` or `"ready"`); when
 `"ready"`, also has a `solution` dict. This is a single poll, not a wait --
 call it repeatedly (as `solve()` does) until `status` is `"ready"`.
-Raises `ApiError`, `NetworkError`.
+Raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
 
 ### `get_balance()`
 
 Returns the account's current balance (`float`) in the account's currency.
-Raises `ApiError`, `NetworkError`.
+Raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
 
 ## Captcha Types
 
@@ -276,8 +276,10 @@ task = RecaptchaV2Task(
 Use this method to solve the Enterprise version of reCAPTCHA v2 and obtain a
 token for a page that uses `grecaptcha.enterprise`.
 
-`RecaptchaV2EnterpriseTaskProxyless` / `RecaptchaV2EnterpriseTask`. Same fields
-as reCAPTCHA v2, plus:
+`RecaptchaV2EnterpriseTaskProxyless` / `RecaptchaV2EnterpriseTask` accept
+`websiteURL`, `websiteKey`, `isInvisible`, `apiDomain`, `userAgent`, and `cookies`,
+plus `enterprisePayload`. Use `enterprisePayload={"s": "..."}` for the
+Enterprise `s` value; these classes do not accept `recaptchaDataSValue`.
 
 | Parameter | Required | Description |
 |---|---|---|
@@ -307,8 +309,8 @@ With proxy, use `RecaptchaV2EnterpriseTask` (same proxy fields as reCAPTCHA v2).
 Use this method to obtain a score-based reCAPTCHA v3 token for a specific site,
 action, and minimum score. This variant does not use a proxy.
 
-`RecaptchaV3TaskProxyless`. No proxy variant exists -- v3 is score-based and
-invisible, so there's no widget/session to pin to a proxy IP.
+`RecaptchaV3TaskProxyless`. This API supports v3 through the service's IPs;
+there is no corresponding task type for your own proxy.
 
 | Parameter | Required | Description |
 |---|---|---|
@@ -353,7 +355,10 @@ that the target page expects in `cf-turnstile-response`.
 | `pagedata` | no | Value of the `chlPageData` parameter, needed for some Cloudflare challenge pages beyond the basic widget. |
 | `userAgent` | no | User-Agent to solve with -- the returned token is tied to it, submit with the same one. |
 
-**Response:** `token` -- submit as `cf-turnstile-response`.
+**Response:** `token` -- submit as `cf-turnstile-response`. For Cloudflare
+Challenge pages, the solution also includes `userAgent`; use that User-Agent
+when submitting the token. Pass `action`, `data`, and `pagedata` when the page
+provides them. The API field is spelled `pagedata`, all lowercase.
 
 ```python
 from captcha_solver_api import CaptchaClient
@@ -425,7 +430,7 @@ pass the values collected from the target page before creating the task.
 | `version` | no | `3` (default) or `4`. |
 | `gt` | v3 only | Public key of the GeeTest widget. |
 | `challenge` | v3 only | Session-specific challenge value from the page -- must be freshly fetched for every request, it cannot be reused. |
-| `initParameters` | v4 only | Extra parameters from the page's `initGeetest` call; for v4 must contain `captcha_id`. |
+| `initParameters` | required for v4; optional for v3 | Extra initialization parameters; for v4 must contain `captcha_id`. |
 | `geetestApiServerSubdomain` | no | Custom GeeTest API subdomain, if the site uses one. |
 | `userAgent` | no | User-Agent to solve with. |
 | `risk_type` | no | Value of the `risk_type` parameter from the captcha-loading request, if present. Dynamic, single-use, and time-limited. |
@@ -598,6 +603,14 @@ it for every other call:
 result = client.solve(task, timeout=300)
 ```
 
+The [API requires at least 5 seconds between polls](https://captcha-solver.com/en/docs/how-it-works).
+The SDK defaults to 10 seconds, like the official 2Captcha Python SDK. `solve()`
+waits for `polling_interval` before its first poll and between polls.
+Its default 120-second polling window is independent of the API's five-minute
+task lifetime. A local timeout does not cancel a task or mean that the API
+failed to solve it. Use `create_task()` and keep its `task_id` if you need to
+check the same task later; calling `solve()` again creates a new task.
+
 ### Worker language pool
 
 Set a default `language_pool` once at construction instead of passing it to every call:
@@ -683,9 +696,10 @@ See the dedicated [examples documentation](https://github.com/captcha-solver-api
 sync/async example list, setup steps, expected results, and placeholder guidance.
 
 - **Image/click captchas** (`image_to_text.py`, `coordinates.py`,
-  `yandex_smartcaptcha_image.py`) run end-to-end with nothing but a valid
+  `yandex_smartcaptcha_image.py`) run after installing the dependencies and setting a valid
   `CAPTCHA_API_KEY` -- they read sample images bundled in
   [examples/assets](https://github.com/captcha-solver-api/python-sdk/tree/main/examples/assets), no target page needed.
+  `python-dotenv` is optional: install it only if you want the scripts to load a `.env` file.
 - **Token captchas** (`recaptcha_v2.py`, `recaptcha_v2_enterprise.py`, `recaptcha_v3.py`,
   `turnstile.py`, `yandex_smartcaptcha.py`, `geetest_v4.py`, `tencent.py`) use
   placeholder values (`https://example.com/...`, `YOUR_WEBSITE_KEY`, `YOUR_APP_ID`,
@@ -709,12 +723,11 @@ python examples/sync/image_to_text.py
 python examples/sync/coordinates.py
 ```
 
-**Verified against the live API** during development, using real target pages and
-real proxy credentials in place of the placeholders shown above: every captcha
-type in this SDK -- proxyless and with proxy -- returned a real, correctly-shaped
-solution when pointed at a genuine target. `geetest_v3.py`'s request shape was
-likewise confirmed correct when given a real, freshly-fetched `gt`/`challenge`
-pair.
+Live checks with real parameters have exercised all supported task types.
+Individual tasks may return `ERROR_CAPTCHA_UNSOLVABLE` or exceed the client's
+polling timeout. A `ready` response confirms that the service returned a
+solution; the target website must still accept the token with the matching
+page and session parameters.
 
 ## Requirements
 

{captcha_solver_api-1.0.0 → captcha_solver_api-1.0.1}/README.md

@@ -74,7 +74,7 @@ client = CaptchaClient("your_api_key")
 
 ## Quick Start
 
-Solve a reCAPTCHA v2 in 4 lines.
+Solve a reCAPTCHA v2 with a task object and one `solve()` call.
 
 ```python
 from captcha_solver_api import CaptchaClient
@@ -120,8 +120,8 @@ Constructor.
 |---|---|---|---|
 | `client_key` | `str` | required | Your Captcha Solver API key. Raises `ValidationError` if empty. |
 | `base_url` | `str` | `https://api.captcha-solver.com` | API base URL. Override only for self-hosted/staging deployments. |
-| `timeout` | `int` | `120` | Default max seconds `solve()` waits for a solution before raising `CaptchaTimeoutError`. Overridable per call. |
-| `polling_interval` | `int` | `3` | Seconds between `getTaskResult` polls inside `solve()`. |
+| `timeout` | `int` | `120` | Polling window after task creation, in seconds. Overridable per call; each HTTP request has a separate 30-second timeout. |
+| `polling_interval` | `int` | `10` | Seconds before the first `getTaskResult` poll and between subsequent polls, matching the official 2Captcha Python SDK. |
 | `language_pool` | `Optional[str]` | `None` | Default worker pool (`"en"` or `"ru"`) applied to every call that doesn't pass its own `language_pool`. |
 
 Both clients hold a reusable connection pool (`requests.Session` / `httpx.AsyncClient`)
@@ -155,9 +155,9 @@ Raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
 ### `create_task(task, language_pool=None)`
 
 Submits `task` and returns its numeric task ID without waiting for a solution.
-Same parameters as `solve()`. Use this instead of `solve()` only if you need to
+Accepts `task` and `language_pool`; it does not accept `timeout`. Use this instead of `solve()` if you need to
 manage polling yourself (e.g. checking on many tasks from a different process).
-Raises `ApiError`, `NetworkError`.
+Raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
 
 ### `get_task_result(task_id)`
 
@@ -165,12 +165,12 @@ Fetches the current status of a task created with `create_task()`. Always
 returns a dict with a `status` key (`"processing"` or `"ready"`); when
 `"ready"`, also has a `solution` dict. This is a single poll, not a wait --
 call it repeatedly (as `solve()` does) until `status` is `"ready"`.
-Raises `ApiError`, `NetworkError`.
+Raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
 
 ### `get_balance()`
 
 Returns the account's current balance (`float`) in the account's currency.
-Raises `ApiError`, `NetworkError`.
+Raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
 
 ## Captcha Types
 
@@ -240,8 +240,10 @@ task = RecaptchaV2Task(
 Use this method to solve the Enterprise version of reCAPTCHA v2 and obtain a
 token for a page that uses `grecaptcha.enterprise`.
 
-`RecaptchaV2EnterpriseTaskProxyless` / `RecaptchaV2EnterpriseTask`. Same fields
-as reCAPTCHA v2, plus:
+`RecaptchaV2EnterpriseTaskProxyless` / `RecaptchaV2EnterpriseTask` accept
+`websiteURL`, `websiteKey`, `isInvisible`, `apiDomain`, `userAgent`, and `cookies`,
+plus `enterprisePayload`. Use `enterprisePayload={"s": "..."}` for the
+Enterprise `s` value; these classes do not accept `recaptchaDataSValue`.
 
 | Parameter | Required | Description |
 |---|---|---|
@@ -271,8 +273,8 @@ With proxy, use `RecaptchaV2EnterpriseTask` (same proxy fields as reCAPTCHA v2).
 Use this method to obtain a score-based reCAPTCHA v3 token for a specific site,
 action, and minimum score. This variant does not use a proxy.
 
-`RecaptchaV3TaskProxyless`. No proxy variant exists -- v3 is score-based and
-invisible, so there's no widget/session to pin to a proxy IP.
+`RecaptchaV3TaskProxyless`. This API supports v3 through the service's IPs;
+there is no corresponding task type for your own proxy.
 
 | Parameter | Required | Description |
 |---|---|---|
@@ -317,7 +319,10 @@ that the target page expects in `cf-turnstile-response`.
 | `pagedata` | no | Value of the `chlPageData` parameter, needed for some Cloudflare challenge pages beyond the basic widget. |
 | `userAgent` | no | User-Agent to solve with -- the returned token is tied to it, submit with the same one. |
 
-**Response:** `token` -- submit as `cf-turnstile-response`.
+**Response:** `token` -- submit as `cf-turnstile-response`. For Cloudflare
+Challenge pages, the solution also includes `userAgent`; use that User-Agent
+when submitting the token. Pass `action`, `data`, and `pagedata` when the page
+provides them. The API field is spelled `pagedata`, all lowercase.
 
 ```python
 from captcha_solver_api import CaptchaClient
@@ -389,7 +394,7 @@ pass the values collected from the target page before creating the task.
 | `version` | no | `3` (default) or `4`. |
 | `gt` | v3 only | Public key of the GeeTest widget. |
 | `challenge` | v3 only | Session-specific challenge value from the page -- must be freshly fetched for every request, it cannot be reused. |
-| `initParameters` | v4 only | Extra parameters from the page's `initGeetest` call; for v4 must contain `captcha_id`. |
+| `initParameters` | required for v4; optional for v3 | Extra initialization parameters; for v4 must contain `captcha_id`. |
 | `geetestApiServerSubdomain` | no | Custom GeeTest API subdomain, if the site uses one. |
 | `userAgent` | no | User-Agent to solve with. |
 | `risk_type` | no | Value of the `risk_type` parameter from the captcha-loading request, if present. Dynamic, single-use, and time-limited. |
@@ -562,6 +567,14 @@ it for every other call:
 result = client.solve(task, timeout=300)
 ```
 
+The [API requires at least 5 seconds between polls](https://captcha-solver.com/en/docs/how-it-works).
+The SDK defaults to 10 seconds, like the official 2Captcha Python SDK. `solve()`
+waits for `polling_interval` before its first poll and between polls.
+Its default 120-second polling window is independent of the API's five-minute
+task lifetime. A local timeout does not cancel a task or mean that the API
+failed to solve it. Use `create_task()` and keep its `task_id` if you need to
+check the same task later; calling `solve()` again creates a new task.
+
 ### Worker language pool
 
 Set a default `language_pool` once at construction instead of passing it to every call:
@@ -647,9 +660,10 @@ See the dedicated [examples documentation](https://github.com/captcha-solver-api
 sync/async example list, setup steps, expected results, and placeholder guidance.
 
 - **Image/click captchas** (`image_to_text.py`, `coordinates.py`,
-  `yandex_smartcaptcha_image.py`) run end-to-end with nothing but a valid
+  `yandex_smartcaptcha_image.py`) run after installing the dependencies and setting a valid
   `CAPTCHA_API_KEY` -- they read sample images bundled in
   [examples/assets](https://github.com/captcha-solver-api/python-sdk/tree/main/examples/assets), no target page needed.
+  `python-dotenv` is optional: install it only if you want the scripts to load a `.env` file.
 - **Token captchas** (`recaptcha_v2.py`, `recaptcha_v2_enterprise.py`, `recaptcha_v3.py`,
   `turnstile.py`, `yandex_smartcaptcha.py`, `geetest_v4.py`, `tencent.py`) use
   placeholder values (`https://example.com/...`, `YOUR_WEBSITE_KEY`, `YOUR_APP_ID`,
@@ -673,12 +687,11 @@ python examples/sync/image_to_text.py
 python examples/sync/coordinates.py
 ```
 
-**Verified against the live API** during development, using real target pages and
-real proxy credentials in place of the placeholders shown above: every captcha
-type in this SDK -- proxyless and with proxy -- returned a real, correctly-shaped
-solution when pointed at a genuine target. `geetest_v3.py`'s request shape was
-likewise confirmed correct when given a real, freshly-fetched `gt`/`challenge`
-pair.
+Live checks with real parameters have exercised all supported task types.
+Individual tasks may return `ERROR_CAPTCHA_UNSOLVABLE` or exceed the client's
+polling timeout. A `ready` response confirms that the service returned a
+solution; the target website must still accept the token with the matching
+page and session parameters.
 
 ## Requirements
 

captcha_solver_api-1.0.1/captcha_solver_api/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.1"

{captcha_solver_api-1.0.0 → captcha_solver_api-1.0.1}/captcha_solver_api/async_client.py

@@ -42,7 +42,7 @@ class AsyncCaptchaClient:
         client_key: str,
         base_url: str = "https://api.captcha-solver.com",
         timeout: int = 120,
-        polling_interval: int = 3,
+        polling_interval: int = 10,
         language_pool: Optional[str] = None,
     ) -> None:
         """
@@ -52,8 +52,9 @@ class AsyncCaptchaClient:
                 deployments.
             timeout: Default max seconds `solve()` waits for a solution before
                 raising `CaptchaTimeoutError`. Can be overridden per call.
-            polling_interval: Seconds to wait between `getTaskResult` polls
-                inside `solve()`.
+            polling_interval: Seconds to wait before the first `getTaskResult`
+                poll and between subsequent polls inside `solve()`. Defaults
+                to 10 seconds, matching the official 2Captcha Python SDK.
             language_pool: Default worker pool selector (e.g. `"en"` or `"ru"`)
                 applied to every `create_task()`/`solve()` call that doesn't pass
                 its own `language_pool`. Leave unset to use the account's default
@@ -174,6 +175,7 @@ class AsyncCaptchaClient:
         Raises:
             ApiError: The API reports an error for the task.
             NetworkError: The request failed at the transport level.
+            CaptchaTimeoutError: The HTTP request timed out.
         """
         payload = {
             "clientKey": self.client_key,
@@ -196,6 +198,7 @@ class AsyncCaptchaClient:
         Raises:
             ApiError: The API key is invalid or the account cannot be resolved.
             NetworkError: The request failed at the transport level.
+            CaptchaTimeoutError: The HTTP request timed out.
         """
         payload = {"clientKey": self.client_key}
         data = await self._request("getBalance", payload)
@@ -235,14 +238,16 @@ class AsyncCaptchaClient:
 
         task_id = await self.create_task(task, language_pool=language_pool)
 
-        deadline = time.time() + (timeout if timeout is not None else self.timeout)
+        deadline = time.monotonic() + (timeout if timeout is not None else self.timeout)
 
-        while time.time() < deadline:
+        while time.monotonic() < deadline:
+            remaining = deadline - time.monotonic()
+            await asyncio.sleep(min(self.polling_interval, max(0, remaining)))
+            if time.monotonic() >= deadline:
+                break
             result = await self.get_task_result(task_id)
 
             if result.get("status") == "ready":
                 return result["solution"]
 
-            await asyncio.sleep(self.polling_interval)
-
         raise CaptchaTimeoutError("Task solving timed out.")

{captcha_solver_api-1.0.0 → captcha_solver_api-1.0.1}/captcha_solver_api/client.py

@@ -31,7 +31,7 @@ class CaptchaClient:
         client_key: str,
         base_url: str = "https://api.captcha-solver.com",
         timeout: int = 120,
-        polling_interval: int = 3,
+        polling_interval: int = 10,
         language_pool: Optional[str] = None,
     ) -> None:
         """
@@ -41,8 +41,9 @@ class CaptchaClient:
                 deployments.
             timeout: Default max seconds `solve()` waits for a solution before
                 raising `CaptchaTimeoutError`. Can be overridden per call.
-            polling_interval: Seconds to wait between `getTaskResult` polls
-                inside `solve()`.
+            polling_interval: Seconds to wait before the first `getTaskResult`
+                poll and between subsequent polls inside `solve()`. Defaults
+                to 10 seconds, matching the official 2Captcha Python SDK.
             language_pool: Default worker pool selector (e.g. `"en"` or `"ru"`)
                 applied to every `create_task()`/`solve()` call that doesn't pass
                 its own `language_pool`. Leave unset to use the account's default
@@ -160,6 +161,7 @@ class CaptchaClient:
         Raises:
             ApiError: The API reports an error for this task (e.g. it expired).
             NetworkError: The request failed at the transport level.
+            CaptchaTimeoutError: The HTTP request timed out.
         """
         payload = {
             "clientKey": self.client_key,
@@ -180,6 +182,7 @@ class CaptchaClient:
         Raises:
             ApiError: The API key is invalid or the account can't be resolved.
             NetworkError: The request failed at the transport level.
+            CaptchaTimeoutError: The HTTP request timed out.
         """
         payload = {"clientKey": self.client_key}
         data = self._request("getBalance", payload)
@@ -217,14 +220,16 @@ class CaptchaClient:
 
         task_id = self.create_task(task, language_pool=language_pool)
 
-        deadline = time.time() + (timeout if timeout is not None else self.timeout)
+        deadline = time.monotonic() + (timeout if timeout is not None else self.timeout)
 
-        while time.time() < deadline:
+        while time.monotonic() < deadline:
+            remaining = deadline - time.monotonic()
+            time.sleep(min(self.polling_interval, max(0, remaining)))
+            if time.monotonic() >= deadline:
+                break
             result = self.get_task_result(task_id)
 
             if result.get("status") == "ready":
                 return result["solution"]
 
-            time.sleep(self.polling_interval)
-
         raise CaptchaTimeoutError("Task solving timed out.")

{captcha_solver_api-1.0.0 → captcha_solver_api-1.0.1}/captcha_solver_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: captcha-solver-api
-Version: 1.0.0
+Version: 1.0.1
 Summary: Official Python SDK for solving reCAPTCHA v2/v3, Cloudflare Turnstile, GeeTest v3/v4, Yandex SmartCaptcha, Tencent, and image/click captchas via the Captcha Solver API
 Author: Captcha Solver Team
 License-Expression: MIT
@@ -110,7 +110,7 @@ client = CaptchaClient("your_api_key")
 
 ## Quick Start
 
-Solve a reCAPTCHA v2 in 4 lines.
+Solve a reCAPTCHA v2 with a task object and one `solve()` call.
 
 ```python
 from captcha_solver_api import CaptchaClient
@@ -156,8 +156,8 @@ Constructor.
 |---|---|---|---|
 | `client_key` | `str` | required | Your Captcha Solver API key. Raises `ValidationError` if empty. |
 | `base_url` | `str` | `https://api.captcha-solver.com` | API base URL. Override only for self-hosted/staging deployments. |
-| `timeout` | `int` | `120` | Default max seconds `solve()` waits for a solution before raising `CaptchaTimeoutError`. Overridable per call. |
-| `polling_interval` | `int` | `3` | Seconds between `getTaskResult` polls inside `solve()`. |
+| `timeout` | `int` | `120` | Polling window after task creation, in seconds. Overridable per call; each HTTP request has a separate 30-second timeout. |
+| `polling_interval` | `int` | `10` | Seconds before the first `getTaskResult` poll and between subsequent polls, matching the official 2Captcha Python SDK. |
 | `language_pool` | `Optional[str]` | `None` | Default worker pool (`"en"` or `"ru"`) applied to every call that doesn't pass its own `language_pool`. |
 
 Both clients hold a reusable connection pool (`requests.Session` / `httpx.AsyncClient`)
@@ -191,9 +191,9 @@ Raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
 ### `create_task(task, language_pool=None)`
 
 Submits `task` and returns its numeric task ID without waiting for a solution.
-Same parameters as `solve()`. Use this instead of `solve()` only if you need to
+Accepts `task` and `language_pool`; it does not accept `timeout`. Use this instead of `solve()` if you need to
 manage polling yourself (e.g. checking on many tasks from a different process).
-Raises `ApiError`, `NetworkError`.
+Raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
 
 ### `get_task_result(task_id)`
 
@@ -201,12 +201,12 @@ Fetches the current status of a task created with `create_task()`. Always
 returns a dict with a `status` key (`"processing"` or `"ready"`); when
 `"ready"`, also has a `solution` dict. This is a single poll, not a wait --
 call it repeatedly (as `solve()` does) until `status` is `"ready"`.
-Raises `ApiError`, `NetworkError`.
+Raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
 
 ### `get_balance()`
 
 Returns the account's current balance (`float`) in the account's currency.
-Raises `ApiError`, `NetworkError`.
+Raises `ApiError`, `CaptchaTimeoutError`, or `NetworkError`.
 
 ## Captcha Types
 
@@ -276,8 +276,10 @@ task = RecaptchaV2Task(
 Use this method to solve the Enterprise version of reCAPTCHA v2 and obtain a
 token for a page that uses `grecaptcha.enterprise`.
 
-`RecaptchaV2EnterpriseTaskProxyless` / `RecaptchaV2EnterpriseTask`. Same fields
-as reCAPTCHA v2, plus:
+`RecaptchaV2EnterpriseTaskProxyless` / `RecaptchaV2EnterpriseTask` accept
+`websiteURL`, `websiteKey`, `isInvisible`, `apiDomain`, `userAgent`, and `cookies`,
+plus `enterprisePayload`. Use `enterprisePayload={"s": "..."}` for the
+Enterprise `s` value; these classes do not accept `recaptchaDataSValue`.
 
 | Parameter | Required | Description |
 |---|---|---|
@@ -307,8 +309,8 @@ With proxy, use `RecaptchaV2EnterpriseTask` (same proxy fields as reCAPTCHA v2).
 Use this method to obtain a score-based reCAPTCHA v3 token for a specific site,
 action, and minimum score. This variant does not use a proxy.
 
-`RecaptchaV3TaskProxyless`. No proxy variant exists -- v3 is score-based and
-invisible, so there's no widget/session to pin to a proxy IP.
+`RecaptchaV3TaskProxyless`. This API supports v3 through the service's IPs;
+there is no corresponding task type for your own proxy.
 
 | Parameter | Required | Description |
 |---|---|---|
@@ -353,7 +355,10 @@ that the target page expects in `cf-turnstile-response`.
 | `pagedata` | no | Value of the `chlPageData` parameter, needed for some Cloudflare challenge pages beyond the basic widget. |
 | `userAgent` | no | User-Agent to solve with -- the returned token is tied to it, submit with the same one. |
 
-**Response:** `token` -- submit as `cf-turnstile-response`.
+**Response:** `token` -- submit as `cf-turnstile-response`. For Cloudflare
+Challenge pages, the solution also includes `userAgent`; use that User-Agent
+when submitting the token. Pass `action`, `data`, and `pagedata` when the page
+provides them. The API field is spelled `pagedata`, all lowercase.
 
 ```python
 from captcha_solver_api import CaptchaClient
@@ -425,7 +430,7 @@ pass the values collected from the target page before creating the task.
 | `version` | no | `3` (default) or `4`. |
 | `gt` | v3 only | Public key of the GeeTest widget. |
 | `challenge` | v3 only | Session-specific challenge value from the page -- must be freshly fetched for every request, it cannot be reused. |
-| `initParameters` | v4 only | Extra parameters from the page's `initGeetest` call; for v4 must contain `captcha_id`. |
+| `initParameters` | required for v4; optional for v3 | Extra initialization parameters; for v4 must contain `captcha_id`. |
 | `geetestApiServerSubdomain` | no | Custom GeeTest API subdomain, if the site uses one. |
 | `userAgent` | no | User-Agent to solve with. |
 | `risk_type` | no | Value of the `risk_type` parameter from the captcha-loading request, if present. Dynamic, single-use, and time-limited. |
@@ -598,6 +603,14 @@ it for every other call:
 result = client.solve(task, timeout=300)
 ```
 
+The [API requires at least 5 seconds between polls](https://captcha-solver.com/en/docs/how-it-works).
+The SDK defaults to 10 seconds, like the official 2Captcha Python SDK. `solve()`
+waits for `polling_interval` before its first poll and between polls.
+Its default 120-second polling window is independent of the API's five-minute
+task lifetime. A local timeout does not cancel a task or mean that the API
+failed to solve it. Use `create_task()` and keep its `task_id` if you need to
+check the same task later; calling `solve()` again creates a new task.
+
 ### Worker language pool
 
 Set a default `language_pool` once at construction instead of passing it to every call:
@@ -683,9 +696,10 @@ See the dedicated [examples documentation](https://github.com/captcha-solver-api
 sync/async example list, setup steps, expected results, and placeholder guidance.
 
 - **Image/click captchas** (`image_to_text.py`, `coordinates.py`,
-  `yandex_smartcaptcha_image.py`) run end-to-end with nothing but a valid
+  `yandex_smartcaptcha_image.py`) run after installing the dependencies and setting a valid
   `CAPTCHA_API_KEY` -- they read sample images bundled in
   [examples/assets](https://github.com/captcha-solver-api/python-sdk/tree/main/examples/assets), no target page needed.
+  `python-dotenv` is optional: install it only if you want the scripts to load a `.env` file.
 - **Token captchas** (`recaptcha_v2.py`, `recaptcha_v2_enterprise.py`, `recaptcha_v3.py`,
   `turnstile.py`, `yandex_smartcaptcha.py`, `geetest_v4.py`, `tencent.py`) use
   placeholder values (`https://example.com/...`, `YOUR_WEBSITE_KEY`, `YOUR_APP_ID`,
@@ -709,12 +723,11 @@ python examples/sync/image_to_text.py
 python examples/sync/coordinates.py
 ```
 
-**Verified against the live API** during development, using real target pages and
-real proxy credentials in place of the placeholders shown above: every captcha
-type in this SDK -- proxyless and with proxy -- returned a real, correctly-shaped
-solution when pointed at a genuine target. `geetest_v3.py`'s request shape was
-likewise confirmed correct when given a real, freshly-fetched `gt`/`challenge`
-pair.
+Live checks with real parameters have exercised all supported task types.
+Individual tasks may return `ERROR_CAPTCHA_UNSOLVABLE` or exceed the client's
+polling timeout. A `ready` response confirms that the service returned a
+solution; the target website must still accept the token with the matching
+page and session parameters.
 
 ## Requirements
 

{captcha_solver_api-1.0.0 → captcha_solver_api-1.0.1}/captcha_solver_api.egg-info/SOURCES.txt

@@ -12,4 +12,5 @@ captcha_solver_api.egg-info/PKG-INFO
 captcha_solver_api.egg-info/SOURCES.txt
 captcha_solver_api.egg-info/dependency_links.txt
 captcha_solver_api.egg-info/requires.txt
-captcha_solver_api.egg-info/top_level.txt
+captcha_solver_api.egg-info/top_level.txt
+tests/test_polling.py

captcha_solver_api-1.0.1/tests/test_polling.py

@@ -0,0 +1,89 @@
+"""The documented polling schedule applies to both clients, including the first poll."""
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+import captcha_solver_api.client as sync_module
+import captcha_solver_api.async_client as async_module
+from captcha_solver_api import CaptchaClient, AsyncCaptchaClient, CaptchaTimeoutError
+from captcha_solver_api.tasks import RecaptchaV2TaskProxyless
+
+
+class Clock:
+    def __init__(self):
+        self.now = 0
+
+    def monotonic(self):
+        return self.now
+
+    def sleep(self, seconds):
+        self.now += seconds
+
+
+CASES = [
+    (None, 25, [10, 20], False),
+    (2, 20, [2, 4], False),
+    (None, 3, [], True),
+    (5, 7, [5], True),
+]
+
+
+@pytest.mark.parametrize('interval,timeout,expected_polls,times_out', CASES)
+def test_sync_polling_schedule(monkeypatch, interval, timeout, expected_polls, times_out):
+    clock = Clock()
+    polls = []
+    monkeypatch.setattr(sync_module, 'time', clock)
+
+    def request(endpoint, payload):
+        if endpoint == 'createTask':
+            assert clock.now == 0
+            return {'errorId': 0, 'taskId': 100}
+        assert payload['taskId'] == 100
+        polls.append(clock.now)
+        if len(polls) == 2:
+            return {'errorId': 0, 'status': 'ready', 'solution': {'token': 'done'}}
+        return {'errorId': 0, 'status': 'processing'}
+
+    options = {} if interval is None else {'polling_interval': interval}
+    with CaptchaClient('test-key', **options) as client:
+        monkeypatch.setattr(client, '_request', request)
+        task = RecaptchaV2TaskProxyless('https://example.com', 'site-key')
+        if times_out:
+            with pytest.raises(CaptchaTimeoutError):
+                client.solve(task, timeout=timeout)
+            assert clock.now == timeout
+        else:
+            assert client.solve(task, timeout=timeout) == {'token': 'done'}
+    assert polls == expected_polls
+
+
+@pytest.mark.parametrize('interval,timeout,expected_polls,times_out', CASES)
+async def test_async_polling_schedule(monkeypatch, interval, timeout, expected_polls, times_out):
+    clock = Clock()
+    polls = []
+    monkeypatch.setattr(async_module, 'time', clock)
+    monkeypatch.setattr(async_module, 'asyncio', SimpleNamespace(sleep=AsyncMock(side_effect=clock.sleep)))
+
+    async def request(endpoint, payload):
+        if endpoint == 'createTask':
+            assert clock.now == 0
+            return {'errorId': 0, 'taskId': 100}
+        assert payload['taskId'] == 100
+        polls.append(clock.now)
+        if len(polls) == 2:
+            return {'errorId': 0, 'status': 'ready', 'solution': {'token': 'done'}}
+        return {'errorId': 0, 'status': 'processing'}
+
+    options = {} if interval is None else {'polling_interval': interval}
+    async with AsyncCaptchaClient('test-key', **options) as client:
+        monkeypatch.setattr(client, '_request', request)
+        task = RecaptchaV2TaskProxyless('https://example.com', 'site-key')
+        if times_out:
+            with pytest.raises(CaptchaTimeoutError):
+                await client.solve(task, timeout=timeout)
+            assert clock.now == timeout
+        else:
+            assert await client.solve(task, timeout=timeout) == {'token': 'done'}
+    assert polls == expected_polls

captcha_solver_api-1.0.0/captcha_solver_api/_version.py

@@ -1 +0,0 @@
-__version__ = "1.0.0"