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_tokentokenreCAPTCHA v2 (token) — Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready).
solve_recaptcha_v2_token(…)returnssolution.tokenfrom 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 fieldimport { CaptchaSonic } from "captchasonic";
const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY);
const result = await solver.solveRecaptchaV2Token({
websiteURL: "https://example.com/login",
websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
console.log(result.solution.gRecaptchaResponse);
// 03AGdBq25SxXT... ← drop into the g-recaptcha-response fieldRetorna o token do reCAPTCHA — envie-o como
g-recaptcha-responseda 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ê fornecewebsite_url/website_key, o SDK faz o polling na nossa infraestrutura e retorna umresult["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_tokentokenreCAPTCHA v2 (token) — Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready).
solve_recaptcha_v2_token(…)returnssolution.tokenresult = 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 comog-recaptcha-responseda 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 comog-recaptcha-responseda 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_turnstiletokenCloudflare Turnstile — Solve a Cloudflare Turnstile token challenge (async — polls until ready).
solve_turnstile(…)returnssolution.tokenresult = solver.solve_turnstile(
website_url="https://example.com",
website_key="0x4AAAAAAA...",
proxy="http://user:pass@host:port", # optional
)
token = result["token"]await solver.solveTurnstile({
websiteURL: "https://example.com",
websiteKey: "0x4AAAAAAA...",
proxy: "http://user:[email protected]:8080",
});REST task typeRetorna o token do Turnstile — envie-o como
cf-turnstile-responsedo formulário.
AntiTurnstileTask
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.
CAPTCHA popular (desafios de imagem estilo hCaptcha)
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 retornaresult["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 degeetest_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 detype.
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 detype.
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ção | Padrão | Descriçã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. |
url | api.captchasonic.com:443 | Substitui o endpoint da API (ex.: para instalações próprias ou staging). |
timeout | 30.0 | Timeout de rede por chamada, em segundos. |
polling_interval | 2.0 | Segundos entre consultas enquanto aguarda uma tarefa de token. |
polling_timeout | 120.0 | Tempo máximo, em segundos, para aguardar uma tarefa de token antes de lançar erro. |
secure | True | Usa 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}")
| id | Python exception | Node errorName | Meaning | Action |
|---|---|---|---|---|
0 | SonicError | SonicError | Base class for every SDK error — catches anything below. | Inspect `error.errorId` (Node) / `err.error_id` (Python) and branch. |
1 | InvalidApiKeyError | InvalidApiKeyError | API key is missing, malformed, or revoked. | Verify the key in your dashboard. |
2 | InsufficientBalanceError | InsufficientBalanceError | Account balance can't cover the task. | Add funds. |
3 | DailyLimitExceededError | DailyLimitExceededError | Daily quota exhausted. | Wait for the daily reset or upgrade your plan. |
4 | MinuteLimitExceededError | MinuteLimitExceededError | Per-minute rate limit hit. | Slow down requests / add exponential backoff. |
5 | QuotaExceededError | QuotaExceededError | Plan quota exhausted. | Upgrade your plan. |
6 | PlanExpiredError | PlanExpiredError | Subscription 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_cloudflarefalha imediatamente. O argumentoproxyé 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.) retornamresult["typed_solution"]descrevendo a ação a executar; apenas*_token,solve_turnstileesolve_cloudflareretornamresult["token"].