Python SDK

Официальный Python SDK CaptchaSonic превращает каждую поддерживаемую CAPTCHA в один вызов функции. Он включает синхронный (CaptchaSonic) и асинхронный (AsyncCaptchaSonic) клиенты, по умолчанию обращается к нашей инфраструктуре через gRPC (с опциональным транспортом HTTP) и содержит полные подсказки типов, автоматические повторы при временных ошибках и встроенный опрос (polling) для задач токенового типа.

---

Установка

pip install captchasonic

Транспорт gRPC устанавливается по умолчанию. Чтобы дополнительно использовать опциональный транспорт HTTP/JSON, установите extra:

pip install "captchasonic[http]"

---

Аутентификация

Вам нужен API-ключ CaptchaSonic. Создайте аккаунт и получите ключ в личном кабинете, затем пополните баланс на странице Пополнение средств.

Передайте ключ первым позиционным аргументом клиента:

from captchasonic import CaptchaSonic

solver = CaptchaSonic("YOUR_API_KEY")

import os
from captchasonic import CaptchaSonic

solver = CaptchaSonic(os.environ["CAPTCHASONIC_API_KEY"])

---

Быстрый старт

Большинство CAPTCHA токенового типа (reCAPTCHA, Turnstile, hCaptcha) решаются одним вызовом. Клиент сам выполняет опрос и возвращает токен, как только задача готова.

from captchasonic import CaptchaSonic

solver = CaptchaSonic("YOUR_API_KEY")

result = solver.solve_recaptcha_v2_token(
    website_url="https://example.com/login",
    website_key="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
)

print(result["token"])
# 03AGdBq25SxXT...  ← подставьте это в поле g-recaptcha-response

Возвращает result["token"] — отправьте его как g-recaptcha-response на странице.

Методы токенового типа выполняют опрос до 120 секунд по умолчанию, прежде чем сработает тайм-аут (см. Конфигурация).

---

Поддерживаемые типы CAPTCHA

SDK делит методы на два семейства:

• Методы токенов (*_token, solve_turnstile, solve_cloudflare) — вы передаёте website_url / website_key, SDK опрашивает нашу инфраструктуру и возвращает готовый к отправке result["token"].
• Методы изображений / интерактивные — вы сами передаёте изображения задачи, а SDK возвращает result["typed_solution"], описывающий, куда кликать, что перетаскивать или какой текст вводить.

Все аргументы изображений принимают гибкий тип ImageInput — путь к файлу (str), pathlib.Path, сырые bytes или открытый бинарный файловый объект.

from pathlib import Path

# Любой из этих вариантов годится как элемент списка `images=[...]`:
Path("captcha.png")        # pathlib.Path
"./captcha.png"            # путь в виде str
open("captcha.png", "rb").read()  # bytes

reCAPTCHA v2 (токен)

result = solver.solve_recaptcha_v2_token(
    website_url="https://example.com",
    website_key="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    proxy="http://user:pass@host:port",  # опционально
)
token = result["token"]

Возвращает result["token"] — отправьте его как g-recaptcha-response на странице.

reCAPTCHA v3 (токен)

result = solver.solve_recaptcha_v3_token(
    website_url="https://example.com",
    website_key="6Lc_aCMTAAAAAB...",
    proxy="http://user:pass@host:port",  # опционально
)
token = result["token"]

Возвращает result["token"] — отправьте его как g-recaptcha-response на странице.

reCAPTCHA v2 (сетка изображений)

Когда плитки задачи уже у вас, решайте сетку напрямую и получайте индексы для клика.

result = solver.solve_recaptcha_v2(
    images=[Path("tile.png")],         # список ImageInput
    question="traffic lights",          # метка или идентификатор сущности /m/...
    question_type="44",                # "split_33" | "33" | "44"
)
to_click = result["typed_solution"]["grid"]["objects"]  # list[int]

Возвращает result["typed_solution"]["grid"]["objects"] — список индексов плиток для клика.

Cloudflare Turnstile

result = solver.solve_turnstile(
    website_url="https://example.com",
    website_key="0x4AAAAAAA...",
    proxy="http://user:pass@host:port",  # опционально
)
token = result["token"]

Возвращает result["token"] — отправьте его как cf-turnstile-response в форме.

Cloudflare Challenge

Полный Cloudflare Challenge требует прокси.

result = solver.solve_cloudflare(
    website_url="https://example.com",
    website_key="0x4AAAAAAA...",
    proxy="http://user:pass@host:port",  # обязательно
)
token = result["token"]

Возвращает result["token"] — токен доступа для защищённого запроса.

Popular CAPTCHA (задачи изображений в стиле hCaptcha)

solve_popular_captcha обрабатывает интерактивные варианты с изображениями; solve_popular_captcha_token возвращает токен напрямую.

# Вариант с изображениями / интерактивный
result = solver.solve_popular_captcha(
    images=[Path("challenge.png")],
    question="Select all traffic lights",
    question_type="grid",  # "objectClassify" | "objectClick" | "objectDrag" | "grid"
)
to_click = result["typed_solution"]["grid"]["objects"]  # list[int]

# Вариант с токеном
result = solver.solve_popular_captcha_token(
    website_url="https://example.com",
    website_key="00000000-0000-0000-0000-000000000000",
    proxy="http://user:pass@host:port",  # опционально
)
token = result["token"]

Вариант с изображениями возвращает result["typed_solution"]["grid"]["objects"] (индексы плиток для клика); вариант с токеном возвращает result["token"].

GeeTest

result = solver.solve_geetest(
    geetest_type="nine",  # "nine" | "click" | "slide" | "match" | "winlinze"
    question="Select all bicycles",  # обязательно для "nine" и "click"
    images=[Path("tile.png")],        # обязательно для "nine", "click", "slide"
)
solution = result["typed_solution"]  # структура зависит от geetest_type

Возвращает result["typed_solution"] — действие для выполнения, его форма зависит от geetest_type.

AWS WAF

result = solver.solve_aws_waf(
    images=[Path("grid.png")],
    question="grid:vehicles:cars",
)
to_click = result["typed_solution"]["grid"]["objects"]  # list[int]

Возвращает result["typed_solution"]["grid"]["objects"] — список индексов плиток для клика.

Изображение в текст (OCR)

result = solver.solve_ocr(
    images=[Path("captcha.png")],
    module="common",       # "common" | "mtcaptcha" | "bls" | "morocco"
    numeric=False,         # ожидать только цифры
    case_sensitive=True,   # сохранять регистр букв
    min_length=4,
    max_length=8,
)
text = result["typed_solution"]["text"]["texts"][0]  # str

Возвращает result["typed_solution"]["text"]["texts"][0] — распознанный текст для ввода.

Слайдер-пазл

Передайте фон и фрагмент пазла; в ответ вы получаете горизонтальное смещение в пикселях для сдвига.

result = solver.solve_slide_image(
    images=[Path("background.png"), Path("piece.png")],
)
offset_x = result["typed_solution"]["slide"]["x"]  # float (пиксели)

Возвращает result["typed_solution"]["slide"]["x"] — горизонтальное смещение в пикселях для перетаскивания фрагмента.

TikTok

result = solver.solve_tiktok(
    type="whirl",  # "click" | "whirl" | "slide"
    images=[Path("outer.png")],
    examples=[Path("inner.png")],  # обязательно для "whirl" и "slide"
)
solution = result["typed_solution"]

Возвращает result["typed_solution"] — действие для выполнения, его форма зависит от type.

Binance

result = solver.solve_binance(
    type="grid",  # "grid" | "slide"
    question="Select all bicycles",  # обязательно для "grid"
    images=[Path("grid.png")],
)
solution = result["typed_solution"]

Возвращает result["typed_solution"] — действие для выполнения, его форма зависит от type.

---

Асинхронное использование

Для высоконагруженных задач (обработчики FastAPI, пауки Scrapy, конвейеры asyncio) используйте AsyncCaptchaSonic. Он в точности повторяет синхронный API, но каждый метод решения является awaitable. Используйте его как асинхронный контекстный менеджер, чтобы базовый канал закрывался автоматически.

import asyncio
from captchasonic import AsyncCaptchaSonic

async def main():
    async with AsyncCaptchaSonic("YOUR_API_KEY") as solver:
        result = await solver.solve_turnstile(
            website_url="https://example.com",
            website_key="0x4AAAAAAA...",
        )
        print(result["token"])

asyncio.run(main())

Синхронный клиент тоже поддерживает протокол контекстного менеджера:

with CaptchaSonic("YOUR_API_KEY") as solver:
    result = solver.solve_ocr(images=[Path("captcha.png")])
    print(result["typed_solution"]["text"]["texts"][0])

---

Поддержка прокси

Методы токенов принимают опциональный аргумент proxy (обязателен для solve_cloudflare). Используйте стандартный URL прокси:

proxy = "http://user:pass@host:port"

result = solver.solve_recaptcha_v2_token(
    website_url="https://example.com",
    website_key="6Le-...",
    proxy=proxy,
)

---

Конфигурация

Все параметры передаются в конструктор клиента и применяются как к синхронному, так и к асинхронному клиенту.

solver = CaptchaSonic(
    "YOUR_API_KEY",
    transport="grpc",                # "grpc" (по умолчанию) или "http"
    url="api.captchasonic.com:443",  # переопределение эндпоинта (опционально)
    timeout=30.0,                    # тайм-аут на вызов, секунды
    polling_interval=2.0,            # секунды между опросами задачи
    polling_timeout=120.0,           # максимальное ожидание токеновой задачи, секунды
    secure=True,                     # использовать TLS для gRPC
)

Параметр	По умолчанию	Описание
transport	"grpc"	Протокол передачи. "grpc" отправляет изображения без накладных расходов на base64; "http" (требует extra [http]) отправляет REST/JSON с изображениями в base64.
url	api.captchasonic.com:443	Переопределение эндпоинта API (например, для self-hosted или staging).
timeout	30.0	Сетевой тайм-аут на один вызов, в секундах.
polling_interval	2.0	Секунды между опросами при ожидании токеновой задачи.
polling_timeout	120.0	Максимальное ожидание токеновой задачи до выброса исключения, в секундах.
secure	True	Использовать TLS для канала gRPC.

Временные ошибки gRPC повторяются автоматически (до 3 попыток) с экспоненциальной задержкой, поэтому вам нужно обрабатывать только реальные бизнес-ошибки.

---

Обработка ошибок

Все ошибки SDK наследуются от SonicError, поэтому вы можете перехватить всё одним блоком except или различать конкретный подкласс. Каждая ошибка также содержит числовой error_id.

from captchasonic.exceptions import (
    SonicError,
    InvalidApiKeyError,
    InsufficientBalanceError,
)

try:
    result = solver.solve_turnstile(
        website_url="https://example.com",
        website_key="0x4AAAAAAA...",
    )
except InsufficientBalanceError:
    print("Top up your balance to continue.")
except InvalidApiKeyError:
    print("Check your API key.")
except SonicError as err:
    print(f"Solve failed (error_id={err.error_id}): {err}")

error_id	Исключение	Причина	Действие
1	InvalidApiKeyError	API-ключ отсутствует или недействителен.	Проверьте ключ в личном кабинете.
2	InsufficientBalanceError	Баланс аккаунта не покрывает задачу.	Пополните баланс.
3	DailyLimitExceededError	Дневная квота исчерпана.	Дождитесь дневного сброса или повысьте тариф.
4	MinuteLimitExceededError	Достигнут лимит запросов в минуту.	Снизьте частоту запросов / добавьте задержку.
5	QuotaExceededError	Квота тарифа исчерпана.	Повысьте тариф.
6	PlanExpiredError	Подписка истекла.	Продлите подписку.

---

Вспомогательные методы аккаунта

balance = solver.get_balance()  # текущий баланс в USD (float)
print(f"Balance: ${balance:.2f}")

health = solver.health_check()  # HealthCheckResponse — проверяет подключение

Используйте health_check() как лёгкую проверку готовности в сервисах, а get_balance() — чтобы проверить баланс перед запуском задач, которые расходуют кредиты.

---

Устранение неполадок

• Токеновая задача завершается ошибкой примерно через 120 секунд. Это polling_timeout. Увеличьте его для медленных целей, например CaptchaSonic(key, polling_timeout=240.0).
• solve_cloudflare сразу падает. Аргумент proxy обязателен для Cloudflare Challenge — укажите рабочий URL прокси.
• Ошибки подключения gRPC за корпоративным прокси/файрволом. gRPC требует HTTP/2 через порт 443. Если ваша сеть его блокирует, переключитесь на transport="http".
• Методы изображений возвращают индексы, а не токен. Интерактивные методы (solve_recaptcha_v2, solve_popular_captcha, solve_aws_waf, solve_geetest и т. д.) возвращают result["typed_solution"], описывающий нужное действие; только *_token, solve_turnstile и solve_cloudflare возвращают result["token"].

---

Ресурсы

• Пакет на PyPI
• Справочник REST API