GhostCaptcha Client

Official Python client for the GhostCaptcha API

---

GhostCaptcha Client, hCaptca çözüm API'si için yazılmış, production-grade Python kütüphanesidir. Senkron ve asenkron istemci, bağlantı havuzu, otomatik yeniden deneme, ve kapsamlı hata yönetimi sunar.

Features

• Dual Client — Sync (GhostCaptchaClient) + Async (AsyncGhostCaptchaClient)
• Connection Pooling — Single httpx connection pool, auto cleanup
• Rate Limit Auto-Retry — 429 hatasında Retry-After başlığını okuyup bekler
• Proxy Support — HTTP/HTTPS proxy, set_proxy() ile canlı değiştirme
• Debug Mode — enable_debug() ile detaylı request/response loglama
• Device Registration — HWID/MAC/CPU toplama (Windows/Linux/Mac)
• TypedDict Responses — IDE otocomplete ile tip güvenli yanıtlar
• GhostCaptcha Compatible — createTask, getTaskResult, getBalance

Installation

pip install ghostcaptcha-client

Requires Python 3.9+ and httpx.

Quick Start

from ghostcaptcha_client import GhostCaptchaClient

client = GhostCaptchaClient("hcap-xxx...")
print(client.get_balance())
client.close()

import asyncio
from ghostcaptcha_client import AsyncGhostCaptchaClient

async def main():
    async with AsyncGhostCaptchaClient("hcap-xxx...") as client:
        print(await client.get_balance())

asyncio.run(main())

API Reference

Constructor Options

Parameter	Default	Description
api_key	—	Your API key (hcap-...)
base_url	production	API base URL (can also set GHOSTCAPTCHA_API_URL env)
verify_ssl	True	SSL certificate verification
timeout	60	Request timeout in seconds
auto_register	False	Auto-register device info on init
proxy	None	Proxy URL (e.g. http://user:pass@host:8080)

Configuration

client = GhostCaptchaClient("hcap-xxx...")

client.enable_debug()             # Enable debug logging
client.set_proxy("http://proxy:8080")  # Set HTTP proxy

Captcha Solving

Method	Returns	Description
solve(image_bytes)	dict	Solve from raw image bytes
solve_file(path)	dict	Solve from image file
solve_base64(b64)	dict	Solve from base64-encoded image

result = client.solve_file("captcha.png")
print(result["actions"])  # [{"x": 120, "y": 340}, ...]

GhostCaptcha-Compatible

Method	Returns	Description
get_balance()	dict	Get account balance
get_soft_id()	str	Get Soft ID
create_task(task)	str	Create solving task (returns taskId)
get_task_result(task_id)	dict	Poll for task result
wait_for_result(task_id)	dict	Poll with auto-retry until ready

task_id = client.create_task({
    "type": "HCaptchaClassification",
    "queries": ["base64_encoded_image"],
})

result = client.wait_for_result(task_id, poll_interval=0.5, timeout=120)

Error Handling

from ghostcaptcha_client import (
    GhostCaptchaError, AuthError, RateLimitError,
    BalanceError, NetworkError,
)

try:
    balance = client.get_balance()
except AuthError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except BalanceError:
    print("Insufficient balance")
except NetworkError:
    print("Connection error")
except GhostCaptchaError as e:
    print(f"API error [{e.code}]: {e.description}")

Exception	HTTP Status	Description
AuthError	401	Invalid or missing API key
RateLimitError	429	Too many requests (auto-retries with Retry-After)
BalanceError	401	Insufficient credits
NetworkError	—	Connection or timeout error
GhostCaptchaError	varies	Base exception for all API errors

Context Managers

# Sync
with GhostCaptchaClient("hcap-xxx...") as client:
    balance = client.get_balance()

# Async
async with AsyncGhostCaptchaClient("hcap-xxx...") as client:
    balance = await client.get_balance()

Device Registration

Auto-collects HWID, CPU ID, MAC address, and OS info for device-bound licensing. Works on Windows (WMI/PowerShell), Linux (sysfs/dmidecode), and macOS (system_profiler).

client = GhostCaptchaClient("hcap-xxx...", auto_register=True)
print(client.device_id)  # UUID if registration succeeded

Wait for Result (Polling)

Automatically polls get_task_result until the task completes or times out:

# Sync
result = client.wait_for_result(task_id, poll_interval=0.5, timeout=120)

# Async
result = await client.wait_for_result(task_id, poll_interval=0.5, timeout=120)

Connection Pooling

Both clients use a single httpx.Client / httpx.AsyncClient instance with connection pooling. For manual resource management:

client = GhostCaptchaClient("hcap-xxx...")
# ... use client ...
client.close()  # Frees the connection pool

Testing

GHOSTCAPTCHA_API_URL=http://api.ghostcaptcha.xyz/v1 python -m pytest tests/ -v

---

Made with ❤️ by GhostCaptcha · GitHub