Skip to main content

AZcaptcha Python SDK

Official Python client for AZcaptcha — image captchas, reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile, FunCaptcha, GeeTest and more.

  • Sync (Azcaptcha) and async (AsyncAzcaptcha) clients.
  • 2Captcha-compatible method surface, so existing scripts migrate by changing the key and host.
  • Typed exceptions for every API error code (spec-v1.0.0).
  • Polling with the contract delays and per-type deadlines built in.
  • Zero runtime dependencies (stdlib urllib), Python 3.9+.

Install

pip install azcaptcha

Quickstart

from azcaptcha import Azcaptcha

client = Azcaptcha("YOUR_API_KEY")

# reCAPTCHA v2
token = client.solve_recaptcha_v2(
    sitekey="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    pageurl="https://example.com/login",
)
print(token)

# Image captcha (bytes, base64 string, data: URI or file path)
answer = client.solve_image("captcha.png")

# hCaptcha / Turnstile
token = client.solve_hcaptcha("SITEKEY", "https://example.com/")
token = client.solve_turnstile("0x4AAAAAAA...", "https://example.com/")

Low-level (2Captcha style)

task_id = client.submit("userrecaptcha", googlekey="SITEKEY", pageurl="https://example.com/")
token = client.wait_result(task_id, timeout=300)  # polls 1s then every 5s

Modern JSON API

task_id = client.create_task(
    "RecaptchaV2TaskProxyless",
    websiteURL="https://example.com/login",
    websiteKey="SITEKEY",
)
solution = client.wait_task_result(task_id)
print(solution["gRecaptchaResponse"])

Async

import asyncio
from azcaptcha import AsyncAzcaptcha

async def main():
    client = AsyncAzcaptcha("YOUR_API_KEY")
    tokens = await asyncio.gather(
        client.solve_turnstile("0x4AAA...", "https://a.example/"),
        client.solve_hcaptcha("SITEKEY", "https://b.example/"),
    )

asyncio.run(main())

Proxies

Pass any accepted spelling as proxy=; the SDK normalises it and never sends the scheme upstream (NS_ERROR_UNKNOWN_PROXY_HOST risk):

client.solve_recaptcha_v2(sitekey, pageurl,
                          proxy="socks5://user:pass@1.2.3.4:1080")
client.solve_recaptcha_v2(sitekey, pageurl,
                          proxy="1.2.3.4:1080:user:pass")

proxytype defaults from the scheme (http/https → HTTP, socks4, socks5); override with proxytype="SOCKS5".

Errors

Every API code maps to a typed exception; retryable mirrors the shared taxonomy:

from azcaptcha import BalanceError, CapacityError, ResultError

try:
    token = client.solve_turnstile(sitekey, pageurl)
except BalanceError:
    ...
except CapacityError:      # ERROR_NO_SLOT_AVAILABLE — retry with backoff
    ...
except ResultError:        # unsolvable / timeout / expired
    ...

wait_result retries only codes marked retryable (slot pressure, thread limit) and backs off 10s ×1.5 up to 60s. Non-retryable codes raise immediately.

Timeouts

Defaults follow server settings: image 120s, hCaptcha 120s, Turnstile 180s, reCAPTCHA and others 300s. Override per call: solve(..., timeout=600) or solve_turnstile(..., timeout=90).

Reporting bad solutions

client.report_bad(task_id)

Soft id

soft_id defaults to 0 (omitted). Once AZcaptcha assigns one it ships in the next release and is sent automatically for upstream attribution.

License

MIT — see LICENSE.

Metadata

Release files for azcaptcha 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for azcaptcha 1.0.0
File Size Uploaded Provenance Actions
azcaptcha-1.0.0.tar.gz 13.8 kB With provenance Details for azcaptcha-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for azcaptcha 1.0.0
File Interpreter ABI Platform Actions
azcaptcha-1.0.0-py3-none-any.whl Python 3 none any Details for azcaptcha-1.0.0-py3-none-any.whl

Total release size: 25.2 kB

Release files / azcaptcha-1.0.0.tar.gz

Download URL azcaptcha-1.0.0.tar.gz
Size 13.8 kB
Tags Source
SHA-256 checksum
How to use checksums
82776162c6b486c1fd9ea5a2bac81d5cc79dab82bfb5b31e27607f2dab670ed1
BLAKE2b-256 checksum
How to use checksums
3e300b6046647b75681d14bbf333a8e273445b295d0f4301c4fe99642330d21c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / azcaptcha-1.0.0-py3-none-any.whl

Download URL azcaptcha-1.0.0-py3-none-any.whl
Size 11.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
83262292b176d7b766534086a6a232d8d591796dfd34b51294213b40e4c779f0
BLAKE2b-256 checksum
How to use checksums
226b2435f277c198e6d7d72b30107a0b4b4dcd21d3163ad48d09acfcafd03ea5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for azcaptcha 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for azcaptcha-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page