Python SDK

The CaptchaSonic Python SDK provides a simple, thread-safe, and asynchronous-ready client for interacting with our AI solving infrastructure. It handles task lifecycle management, polling, and error normalization out of the box.

---

Installation

Install the package via pip:

pip install captchasonic

---

Quick Start

Solve a reCAPTCHA v2 in just a few lines of code.

from captchasonic import CaptchaSonicClient

# 1. Initialize with your secret API key
client = CaptchaSonicClient("YOUR_API_KEY")

# 2. Submit a task
# Supports reCAPTCHA, hCaptcha, GeeTest, Turnstile, and Image-to-Text
task_id = client.create_task({
    "type": "RecaptchaV2TaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
})

print(f"Task ID: {task_id}")

# 3. Fetch the result (automatically waits for completion)
# Default timeout is 120 seconds
try:
    result = client.get_task_result(task_id)
    if result["status"] == "ready":
        token = result["solution"]["gRecaptchaResponse"]
        print(f"Solved! Response token: {token}")
except Exception as e:
    print(f"Integration Error: {str(e)}")

---

Advanced Usage

Solving with Proxies

If the target website requires specific geographic location or IP reputation, you can pass your proxy credentials.

task_id = client.create_task({
    "type": "RecaptchaV2Task", # Note: No 'Proxyless' suffix
    "websiteURL": "https://example.com",
    "websiteKey": "6Le-x...",
    "proxyType": "http",
    "proxyAddress": "8.8.8.8",
    "proxyPort": 8080,
    "proxyLogin": "user",
    "proxyPassword": "password"
})

Async Support

For high-concurrency applications (FastAPI, Scrapy), use the asynchronous client.

import asyncio
from captchasonic import AsyncCaptchaSonicClient

async def main():
    async with AsyncCaptchaSonicClient("YOUR_API_KEY") as client:
        task_id = await client.create_task({...})
        result = await client.get_task_result(task_id)
        print(result)

asyncio.run(main())

---

Error Handling

The SDK raises specific exceptions to help you manage edge cases:

Exception	Meaning	Action
InvalidApiKeyError	Your API key is malformed or invalid.	Check your dashboard.
InsufficientFundsError	Your wallet balance is empty.	Add funds.
NetworkError	A timeout or connection issue occurred.	Retry the request.
TaskError	The AI failed to solve this specific challenge.	Check sitekey or target URL.

---

API Reference

CaptchaSonicClient(api_key: str)

Constructor for the synchronous client.

.create_task(data: dict) -> str

Sends a payload to the API. Returns the taskId.

.get_task_result(task_id: str, timeout: int = 120) -> dict

Polls the result endpoint until the task is ready or failed.

.get_balance() -> float

Returns your current account balance in USD.