Skip to content
CaptchaSonic

SDK Python

Resolva CAPTCHAs em Python com o SDK oficial da CaptchaSonic — transporte gRPC + HTTP, pronto para async, totalmente tipado.

O SDK Python oficial da CaptchaSonic transforma cada CAPTCHA suportado em uma única chamada de função. Ele traz um cliente síncrono (CaptchaSonic) e um assíncrono (AsyncCaptchaSonic), se comunica com a nossa infraestrutura via gRPC por padrão (com transporte HTTP opcional) e inclui type hints completos, novas tentativas automáticas para erros transitórios e polling integrado para desafios do tipo token.


Instalação

pip install captchasonic

O transporte gRPC é instalado por padrão. Para usar também o transporte opcional HTTP/JSON, instale o extra:

pip install "captchasonic[http]"

TIP

O SDK oferece suporte ao Python 3.10, 3.11, 3.12 e 3.13 e é publicado sob a licença MIT.


Autenticação

Você precisa de uma API key da CaptchaSonic. Crie uma conta e obtenha a sua chave no dashboard, depois adicione saldo em Adicionar fundos.

Passe a chave como primeiro argumento posicional para o cliente:

from captchasonic import CaptchaSonic

solver = CaptchaSonic("YOUR_API_KEY")

WARNING

Trate a sua API key como uma senha. Mantenha-a fora do controle de versão — carregue-a de uma variável de ambiente ou de um gerenciador de segredos, em vez de deixá-la fixa no código.

import os
from captchasonic import CaptchaSonic

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

Início rápido

A maioria dos CAPTCHAs do tipo token (reCAPTCHA, Turnstile, hCaptcha) é resolvida com uma única chamada. O cliente faz o polling por você e retorna o token assim que a tarefa estiver pronta.

solve_recaptcha_v2_tokentoken
Verified v1.0.0· 2026-05-28

reCAPTCHA v2 (token) — Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready).

signaturesolve_recaptcha_v2_token(…)returnssolution.token
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...  ← drop this into the g-recaptcha-response field

Retorna o token do reCAPTCHA — envie-o como g-recaptcha-response da página.

Os métodos de token fazem polling por até 120 segundos por padrão antes de expirar (veja Configuração).


Tipos de CAPTCHA suportados

O SDK divide os métodos em duas famílias:

  • Métodos de token (*_token, solve_turnstile, solve_cloudflare) — você fornece website_url / website_key, o SDK faz o polling na nossa infraestrutura e retorna um result["token"] pronto para envio.
  • Métodos de imagem / interativos — você fornece as imagens do desafio, e o SDK retorna um result["typed_solution"] descrevendo o que clicar, arrastar ou digitar.

Todos os argumentos de imagem aceitam o tipo flexível ImageInput — um caminho de arquivo (str), um pathlib.Path, bytes brutos ou um objeto de arquivo binário aberto.

from pathlib import Path

# Any of these work as an item in an `images=[...]` list:
Path("captcha.png")        # pathlib.Path
"./captcha.png"            # str path
open("captcha.png", "rb").read()  # bytes

reCAPTCHA v2 (token)

solve_recaptcha_v2_tokentoken
Verified v1.0.0· 2026-05-28

reCAPTCHA v2 (token) — Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready).

signaturesolve_recaptcha_v2_token(…)returnssolution.token
result = solver.solve_recaptcha_v2_token(
    website_url="https://example.com",
    website_key="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    proxy="http://user:pass@host:port",  # optional
)
token = result["token"]

Retorna result["token"] — envie-o como g-recaptcha-response da página.

reCAPTCHA v3 (token)

result = solver.solve_recaptcha_v3_token(
    website_url="https://example.com",
    website_key="6Lc_aCMTAAAAAB...",
    proxy="http://user:pass@host:port",  # optional
)
token = result["token"]

Retorna result["token"] — envie-o como g-recaptcha-response da página.

reCAPTCHA v2 (grade de imagens)

Quando você já tem os blocos do desafio, resolva a grade diretamente e receba os índices a clicar.

result = solver.solve_recaptcha_v2(
    images=[Path("tile.png")],         # ImageInput list
    question="traffic lights",          # label or /m/... entity id
    question_type="44",                # "split_33" | "33" | "44"
)
to_click = result["typed_solution"]["grid"]["objects"]  # list[int]

Retorna result["typed_solution"]["grid"]["objects"] — a lista de índices dos blocos a clicar.

Cloudflare Turnstile

solve_turnstiletoken
Verified v1.0.0· 2026-05-28

Cloudflare Turnstile — Solve a Cloudflare Turnstile token challenge (async — polls until ready).

signaturesolve_turnstile(…)returnssolution.token
result = solver.solve_turnstile(
    website_url="https://example.com",
    website_key="0x4AAAAAAA...",
    proxy="http://user:pass@host:port",  # optional
)
token = result["token"]

Retorna o token do Turnstile — envie-o como cf-turnstile-response do formulário.

REST task typeAntiTurnstileTask

Desafio Cloudflare

O desafio completo do Cloudflare exige um proxy.

result = solver.solve_cloudflare(
    website_url="https://example.com",
    website_key="0x4AAAAAAA...",
    proxy="http://user:pass@host:port",  # required
)
token = result["token"]

Retorna result["token"] — o token de liberação para a requisição protegida.

solve_popular_captcha trata as variantes interativas com imagens; solve_popular_captcha_token retorna um token diretamente.

# Image / interactive variant
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]

# Token variant
result = solver.solve_popular_captcha_token(
    website_url="https://example.com",
    website_key="00000000-0000-0000-0000-000000000000",
    proxy="http://user:pass@host:port",  # optional
)
token = result["token"]

A variante de imagem retorna result["typed_solution"]["grid"]["objects"] (índices dos blocos a clicar); a variante de token retorna result["token"].

GeeTest

result = solver.solve_geetest(
    geetest_type="nine",  # "nine" | "click" | "slide" | "match" | "winlinze"
    question="Select all bicycles",  # required for "nine" and "click"
    images=[Path("tile.png")],        # required for "nine", "click", "slide"
)
solution = result["typed_solution"]  # structure varies by geetest_type

Retorna result["typed_solution"] — a ação a executar, cuja forma depende de 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]

Retorna result["typed_solution"]["grid"]["objects"] — a lista de índices dos blocos a clicar.

Imagem para texto (OCR)

result = solver.solve_ocr(
    images=[Path("captcha.png")],
    module="common",       # "common" | "mtcaptcha" | "bls" | "morocco"
    numeric=False,         # expect only digits
    case_sensitive=True,   # preserve letter case
    min_length=4,
    max_length=8,
)
text = result["typed_solution"]["text"]["texts"][0]  # str

Retorna result["typed_solution"]["text"]["texts"][0] — o texto reconhecido a ser digitado.

Quebra-cabeça deslizante

Envie o fundo e a peça do quebra-cabeça; você recebe de volta o deslocamento horizontal em pixels para deslizar.

result = solver.solve_slide_image(
    images=[Path("background.png"), Path("piece.png")],
)
offset_x = result["typed_solution"]["slide"]["x"]  # float (pixels)

Retorna result["typed_solution"]["slide"]["x"] — o deslocamento horizontal em pixels para arrastar a peça.

TikTok

result = solver.solve_tiktok(
    type="whirl",  # "click" | "whirl" | "slide"
    images=[Path("outer.png")],
    examples=[Path("inner.png")],  # required for "whirl" and "slide"
)
solution = result["typed_solution"]

Retorna result["typed_solution"] — a ação a executar, cuja forma depende de type.

Binance

result = solver.solve_binance(
    type="grid",  # "grid" | "slide"
    question="Select all bicycles",  # required for "grid"
    images=[Path("grid.png")],
)
solution = result["typed_solution"]

Retorna result["typed_solution"] — a ação a executar, cuja forma depende de type.


Uso assíncrono

Para cargas de trabalho com alta concorrência (handlers FastAPI, spiders Scrapy, pipelines asyncio), use AsyncCaptchaSonic. Ele espelha exatamente a API síncrona, mas todos os métodos de resolução são aguardáveis (awaitable). Use-o como gerenciador de contexto assíncrono para que o canal subjacente seja limpo automaticamente.

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())

O cliente síncrono também suporta o protocolo de gerenciador de contexto:

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

Suporte a proxy

Os métodos de token aceitam um argumento opcional proxy (obrigatório para solve_cloudflare). Use uma URL de proxy padrão:

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

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

TIP

Fornecer um proxy permite que o nosso solver espelhe a localização geográfica e a reputação de IP da sua requisição, o que melhora as taxas de sucesso em sites com regras anti-bot rigorosas.


Configuração

Todas as opções são passadas ao construtor do cliente e valem tanto para o cliente síncrono quanto para o assíncrono.

solver = CaptchaSonic(
    "YOUR_API_KEY",
    transport="grpc",                # "grpc" (default) or "http"
    url="api.captchasonic.com:443",  # endpoint override (optional)
    timeout=30.0,                    # per-call timeout, seconds
    polling_interval=2.0,            # seconds between task polls
    polling_timeout=120.0,           # max wait for a token task, seconds
    secure=True,                     # use TLS for gRPC
)
OpçãoPadrãoDescrição
transport"grpc"Protocolo de transporte. "grpc" envia imagens sem overhead de base64; "http" (requer o extra [http]) envia REST/JSON com imagens codificadas em base64.
urlapi.captchasonic.com:443Substitui o endpoint da API (ex.: para instalações próprias ou staging).
timeout30.0Timeout de rede por chamada, em segundos.
polling_interval2.0Segundos entre consultas enquanto aguarda uma tarefa de token.
polling_timeout120.0Tempo máximo, em segundos, para aguardar uma tarefa de token antes de lançar erro.
secureTrueUsa TLS no canal gRPC.

Erros transitórios de gRPC são repetidos automaticamente (até 3 tentativas) com backoff exponencial, então você só precisa tratar erros de negócio reais.


Tratamento de erros

Todos os erros do SDK herdam de SonicError, então você pode capturar tudo com uma única cláusula except ou tratar uma subclasse específica. Cada erro também carrega um error_id numérico.

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}")
errors7 canonical `errorId` codes
idPython exceptionNode errorNameMeaningAction
0SonicErrorSonicErrorBase class for every SDK error — catches anything below.Inspect `error.errorId` (Node) / `err.error_id` (Python) and branch.
1InvalidApiKeyErrorInvalidApiKeyErrorAPI key is missing, malformed, or revoked.Verify the key in your dashboard.
2InsufficientBalanceErrorInsufficientBalanceErrorAccount balance can't cover the task.Add funds.
3DailyLimitExceededErrorDailyLimitExceededErrorDaily quota exhausted.Wait for the daily reset or upgrade your plan.
4MinuteLimitExceededErrorMinuteLimitExceededErrorPer-minute rate limit hit.Slow down requests / add exponential backoff.
5QuotaExceededErrorQuotaExceededErrorPlan quota exhausted.Upgrade your plan.
6PlanExpiredErrorPlanExpiredErrorSubscription has expired.Renew your subscription.

Every concrete row inherits from SonicError — catch it once to handle all SDK failures, or branch on errorId / exception subclass for granular control. Transient gRPC errors are retried automatically with exponential backoff (up to 3 attempts).


Funções auxiliares da conta

balance = solver.get_balance()  # current balance in USD (float)
print(f"Balance: ${balance:.2f}")

health = solver.health_check()  # HealthCheckResponse — verifies connectivity

Use health_check() como uma sonda de prontidão leve em serviços e get_balance() para validar jobs antes de começar a gastar créditos.


Solução de problemas

TIP

ModuleNotFoundError ao usar o transporte HTTP. O cliente HTTP depende do httpx, que é um extra opcional. Instale com pip install "captchasonic[http]" e defina transport="http".

  • Uma tarefa de token gera erro após ~120 segundos. Esse é o polling_timeout. Aumente-o para alvos lentos, ex.: CaptchaSonic(key, polling_timeout=240.0).
  • solve_cloudflare falha imediatamente. O argumento proxy é obrigatório para o desafio Cloudflare — forneça uma URL de proxy funcional.
  • Erros de conexão gRPC atrás de proxy corporativo/firewall. O gRPC precisa de HTTP/2 na porta 443. Se a sua rede bloquear isso, mude para transport="http".
  • Métodos de imagem retornam índices, não um token. Os métodos interativos (solve_recaptcha_v2, solve_popular_captcha, solve_aws_waf, solve_geetest, etc.) retornam result["typed_solution"] descrevendo a ação a executar; apenas *_token, solve_turnstile e solve_cloudflare retornam result["token"].

Recursos