SDK de Python
Resuelve CAPTCHAs desde Python con el SDK oficial de CaptchaSonic — transporte gRPC + HTTP, listo para asincronía, con tipado completo.
El SDK oficial de Python de CaptchaSonic convierte cada CAPTCHA compatible en una sola llamada a función. Incluye un cliente síncrono (CaptchaSonic) y otro asíncrono (AsyncCaptchaSonic), se comunica con nuestra infraestructura por gRPC de forma predeterminada (con un transporte HTTP opcional), e incluye anotaciones de tipo completas, reintentos automáticos ante errores transitorios y sondeo integrado para los desafíos de tipo token.
Instalación
pip install captchasonic
El transporte gRPC se instala de forma predeterminada. Para usar también el transporte opcional HTTP/JSON, instala el extra:
pip install "captchasonic[http]"
TIP
El SDK es compatible con Python 3.10, 3.11, 3.12 y 3.13 y se publica bajo la licencia MIT.
Autenticación
Necesitas una clave API de CaptchaSonic. Crea una cuenta y obtén tu clave desde el panel; después, recarga tu saldo desde Añadir fondos.
Pasa la clave como primer argumento posicional del cliente:
from captchasonic import CaptchaSonic
solver = CaptchaSonic("YOUR_API_KEY")
WARNING
Trata tu clave API como una contraseña. Manténla fuera del control de versiones: cárgala desde una variable de entorno o un gestor de secretos en lugar de escribirla en el código.
import os
from captchasonic import CaptchaSonic
solver = CaptchaSonic(os.environ["CAPTCHASONIC_API_KEY"])
Inicio rápido
La mayoría de los CAPTCHAs de tipo token (reCAPTCHA, Turnstile, hCaptcha) se resuelven con una sola llamada. El cliente sondea por ti y devuelve el token cuando la tarea está lista.
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 fieldDevuelve el token de reCAPTCHA: envíalo como
g-recaptcha-responsede la página.
Los métodos de tipo token sondean durante hasta 120 segundos por defecto antes de agotar el tiempo (ver Configuración).
Tipos de CAPTCHA compatibles
El SDK divide los métodos en dos familias:
- Métodos de token (
*_token,solve_turnstile,solve_cloudflare): tú proporcionaswebsite_url/website_key, el SDK sondea nuestra infraestructura y devuelve unresult["token"]listo para enviar. - Métodos de imagen / interactivos: tú proporcionas las imágenes del desafío y el SDK devuelve un
result["typed_solution"]que describe qué pulsar, arrastrar o escribir.
Todos los argumentos de imagen aceptan el tipo flexible ImageInput: una ruta de archivo (str), un pathlib.Path, bytes sin procesar o un objeto de archivo binario abierto.
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"]
Devuelve
result["token"]: envíalo comog-recaptcha-responsede la 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"]
Devuelve
result["token"]: envíalo comog-recaptcha-responsede la página.
reCAPTCHA v2 (cuadrícula de imágenes)
Cuando ya tienes las casillas del desafío, resuelve la cuadrícula directamente y recibe los índices en los que hacer clic.
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]
Devuelve
result["typed_solution"]["grid"]["objects"]: la lista de índices de casillas en las que hacer clic.
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 typeDevuelve el token de Turnstile: envíalo como
cf-turnstile-responsedel formulario.
AntiTurnstileTask
Cloudflare Challenge
El desafío completo de Cloudflare requiere un proxy.
result = solver.solve_cloudflare(
website_url="https://example.com",
website_key="0x4AAAAAAA...",
proxy="http://user:pass@host:port", # required
)
token = result["token"]
Devuelve
result["token"]: el token de autorización para la petición protegida.
Popular CAPTCHA (desafíos de imagen estilo hCaptcha)
solve_popular_captcha gestiona las variantes interactivas con imágenes; solve_popular_captcha_token devuelve un token directamente.
# 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"]
La variante de imagen devuelve
result["typed_solution"]["grid"]["objects"](índices de casillas en las que hacer clic); la variante de token devuelveresult["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
Devuelve
result["typed_solution"]: la acción a realizar, con la forma que determinageetest_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]
Devuelve
result["typed_solution"]["grid"]["objects"]: la lista de índices de casillas en las que hacer clic.
Imagen a 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
Devuelve
result["typed_solution"]["text"]["texts"][0]: el texto reconocido que hay que escribir.
Rompecabezas deslizante
Pasa el fondo y la pieza del rompecabezas; recibirás el desplazamiento horizontal en píxeles.
result = solver.solve_slide_image(
images=[Path("background.png"), Path("piece.png")],
)
offset_x = result["typed_solution"]["slide"]["x"] # float (pixels)
Devuelve
result["typed_solution"]["slide"]["x"]: el desplazamiento horizontal en píxeles para arrastrar la pieza.
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"]
Devuelve
result["typed_solution"]: la acción a realizar, con la forma que determinatype.
Binance
result = solver.solve_binance(
type="grid", # "grid" | "slide"
question="Select all bicycles", # required for "grid"
images=[Path("grid.png")],
)
solution = result["typed_solution"]
Devuelve
result["typed_solution"]: la acción a realizar, con la forma que determinatype.
Uso asíncrono
Para cargas de trabajo con alta concurrencia (manejadores de FastAPI, spiders de Scrapy, pipelines de asyncio), usa AsyncCaptchaSonic. Replica exactamente la API síncrona, pero cada método de resolución se puede esperar (await). Úsalo como gestor de contexto asíncrono para que el canal subyacente se limpie automáticamente.
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())
El cliente síncrono también admite el protocolo de gestor de contexto:
with CaptchaSonic("YOUR_API_KEY") as solver:
result = solver.solve_ocr(images=[Path("captcha.png")])
print(result["typed_solution"]["text"]["texts"][0])
Compatibilidad con proxy
Los métodos de token aceptan un argumento proxy opcional (obligatorio para solve_cloudflare). Usa una URL de proxy estándar:
proxy = "http://user:pass@host:port"
result = solver.solve_recaptcha_v2_token(
website_url="https://example.com",
website_key="6Le-...",
proxy=proxy,
)
TIP
Proporcionar un proxy permite a nuestro solucionador reflejar la ubicación geográfica y la reputación de IP de tu petición, lo que mejora las tasas de éxito en sitios con reglas antibot estrictas.
Configuración
Todas las opciones se pasan al constructor del cliente y se aplican tanto al cliente síncrono como al así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
)
| Opción | Predeterminado | Descripción |
|---|---|---|
transport | "grpc" | Protocolo de transmisión. "grpc" envía las imágenes sin sobrecarga de base64; "http" (requiere el extra [http]) envía REST/JSON con imágenes codificadas en base64. |
url | api.captchasonic.com:443 | Sustituye el endpoint de la API (por ejemplo, para instancias propias o de staging). |
timeout | 30.0 | Tiempo límite de red por llamada, en segundos. |
polling_interval | 2.0 | Segundos entre sondeos mientras se espera una tarea de token. |
polling_timeout | 120.0 | Segundos máximos de espera para una tarea de token antes de lanzar una excepción. |
secure | True | Usa TLS para el canal gRPC. |
Los errores transitorios de gRPC se reintentan automáticamente (hasta 3 intentos) con retroceso exponencial, así que solo necesitas gestionar los errores de negocio reales.
Manejo de errores
Todos los errores del SDK heredan de SonicError, así que puedes capturarlos todos con una sola cláusula except o bifurcar según la subclase específica. Cada error también incluye un 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).
Ayudantes de cuenta
balance = solver.get_balance() # current balance in USD (float)
print(f"Balance: ${balance:.2f}")
health = solver.health_check() # HealthCheckResponse — verifies connectivity
Usa health_check() como sonda ligera de disponibilidad en los servicios y get_balance() para validar los trabajos antes de empezar a gastar créditos.
Solución de problemas
TIP
ModuleNotFoundError al usar el transporte HTTP. El cliente HTTP depende de httpx, que es un extra opcional. Instálalo con pip install "captchasonic[http]" y define transport="http".
- Una tarea de token lanza una excepción a los ~120 segundos. Es el
polling_timeout. Auméntalo para destinos lentos, por ejemploCaptchaSonic(key, polling_timeout=240.0). solve_cloudflarefalla de inmediato. El argumentoproxyes obligatorio para el desafío de Cloudflare: proporciona una URL de proxy válida.- Errores de conexión gRPC detrás de un proxy o cortafuegos corporativo. gRPC necesita HTTP/2 por el puerto 443. Si tu red lo bloquea, cambia a
transport="http". - Los métodos de imagen devuelven índices, no un token. Los métodos interactivos (
solve_recaptcha_v2,solve_popular_captcha,solve_aws_waf,solve_geetest, etc.) devuelvenresult["typed_solution"], que describe la acción a realizar; solo*_token,solve_turnstileysolve_cloudflaredevuelvenresult["token"].