Skip to content
CaptchaSonic

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_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

Devuelve el token de reCAPTCHA: envíalo como g-recaptcha-response de 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ú proporcionas website_url / website_key, el SDK sondea nuestra infraestructura y devuelve un result["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_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"]

Devuelve result["token"]: envíalo como g-recaptcha-response de 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 como g-recaptcha-response de 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_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"]

Devuelve el token de Turnstile: envíalo como cf-turnstile-response del formulario.

REST task typeAntiTurnstileTask

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.

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 devuelve 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

Devuelve result["typed_solution"]: la acción a realizar, con la forma que determina 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]

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 determina 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"]

Devuelve result["typed_solution"]: la acción a realizar, con la forma que determina type.


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ónPredeterminadoDescripció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.
urlapi.captchasonic.com:443Sustituye el endpoint de la API (por ejemplo, para instancias propias o de staging).
timeout30.0Tiempo límite de red por llamada, en segundos.
polling_interval2.0Segundos entre sondeos mientras se espera una tarea de token.
polling_timeout120.0Segundos máximos de espera para una tarea de token antes de lanzar una excepción.
secureTrueUsa 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}")
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).


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 ejemplo CaptchaSonic(key, polling_timeout=240.0).
  • solve_cloudflare falla de inmediato. El argumento proxy es 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.) devuelven result["typed_solution"], que describe la acción a realizar; solo *_token, solve_turnstile y solve_cloudflare devuelven result["token"].

Recursos