SDK principal

El motor de todo el ecosistema. capsolver-core usa Python puro para detectar CAPTCHA en una página, leer sus parámetros, resolverlos a través del servicio CapSolver AI y volver a completar el token. Los paquetes de nivel superior capsolver-agent y capsolver-mcp están construidos sobre él.

Solo modo token. Este SDK resuelve solicitando un token de la API de CapSolver (reCAPTCHA v2/v3, Cloudflare Turnstile). No hace clic en cuadrículas de imágenes ni arrastra controles deslizantes en la página.

1. Descripción general

capsolver-core divide “resolver un CAPTCHA” en cuatro etapas claras, encadenadas en un solo proceso:

1. Detectar ( detect ): identifica qué tipos de CAPTCHA están presentes en la página.
2. Leer parámetros ( get_captcha_info ): lea los parámetros estructurados de cada CAPTCHA (tipo, clave del sitio, URL, etc.) directamente desde la página en vivo.
3. Resolver ( solve ): entregue los parámetros al servicio de inteligencia artificial de CapSolver y recupere un token utilizable.
4. Rellenar ( solve_on_page ): escriba el token nuevamente en la página DOM para que el sitio considere la verificación como aprobada.

Alrededor de este oleoducto, añade varias comodidades de ingeniería:

• ✅ API totalmente asíncrona: construida sobre async / await, por lo que puedes ejecutar una gran cantidad de soluciones simultáneamente.
• ✅ Reutilización y limpieza de conexiones: mantiene un grupo de conexiones HTTP interno y funciona como un administrador de contexto asíncrono.
• ✅ Registro de controlador conectable: cada tipo de CAPTCHA es manejado por un controlador, que puedes personalizar o anular.
• ✅ Dos niveles de granularidad: utilice API pura cuando se conozcan los parámetros; use el modo Navegador Playwright cuando todo lo que tenga sea la página.

¿Cuándo deberías usar core directamente? Cuando controlas el código tú mismo y no necesitas exponer la resolución a un LLM.

2. Instalación

capsolver-core es de código abierto en GitHub y aún no está publicado en PyPI, así que instálalo a través de git:

pip install git+https://github.com/capsolver-ai/capsolver-core.git
 
# With Playwright support (for detect / solve_on_page)
pip install "capsolver-core[playwright] @ git+https://github.com/capsolver-ai/capsolver-core.git"
playwright install chromium

Configure su clave:

export CAPSOLVER_API_KEY="your-capsolver-api-key"

Nota: El SDK funciona sin el [playwright] extra; en ese caso, solo está disponible el modo Token ( solve ), y los métodos dependientes del navegador detect / get_captcha_info / solve_on_page no están disponibles porque falta Playwright.

3. La API y los dos modos

3.1 Crear un cliente

create_capsolver(**options) (o Capsolver(**options)) devuelve un cliente.

Capsolver tiene un grupo de conexiones HTTP interno, por lo que es mejor usarlo como administrador de contexto asíncrono para garantizar que se liberen las conexiones:

async with create_capsolver(api_key="YOUR_API_KEY") as cap:
    solution = await cap.solve(info)
# or call await cap.aclose() explicitly when you're done

3.2 Métodos de un vistazo

3.3 Resolver entrada: CaptchaInfo

La entrada principal a solve() es un CaptchaInfo. type , website_url y website_key son necesarios (un website_url o website_key vacío aumenta ValueError ); el resto son opcionales dependiendo del tipo CAPTCHA:

Las opciones para solve_on_page() están controladas por SolveOnPageOptions:

El wait_options para solve() ( WaitOptions ) tiene solo dos campos opcionales, timeout y polling_interval , que se utilizan para anular los valores predeterminados globales del cliente para una única resolución.

3.4 Tipos de devolución

detect() devuelve list[CaptchaType] y get_captcha_info() devuelve list[CaptchaInfo].

3.5 Cómo cada modo utiliza estas API

La única diferencia entre los dos modos es de dónde provienen los parámetros, razón por la cual llaman a diferentes API:

Modo token (ya conoces la clave del sitio): usa solo solve(). Usted construye el CaptchaInfo usted mismo y recupera un token:

info = CaptchaInfo(type=CaptchaType.RECAPTCHA_V2, website_url=..., website_key=...)
solution = await cap.solve(info)

Modo de navegador (conduciendo la página con Playwright): utiliza detect() / get_captcha_info() / solve_on_page(). El solve_on_page() todo en uno cubre la detección, resolución y reposición; O puedes ejecutar los pasos por separado para controlar cada etapa tú mismo:

results = await cap.solve_on_page(page)              # all in one call
# or step by step:
types = await cap.detect(page)
infos = await cap.get_captcha_info(page)
solution = await cap.solve(infos[0])

4. Llamar a cada API: solicitudes y respuestas

Esta sección analiza cada método individualmente: la llamada real, los parámetros a pasar, una respuesta de muestra y una explicación de los campos de respuesta.

4.1 solve — Resolver (modo Token)

Ejemplo de llamada y respuesta:

import asyncio
from capsolver_core import create_capsolver, CaptchaType, CaptchaInfo
 
async def main():
    cap = create_capsolver(api_key="YOUR_API_KEY")
 
    info = CaptchaInfo(
        type=CaptchaType.RECAPTCHA_V2,        # required: CAPTCHA type
        website_url="https://example.com",    # required: page URL
        website_key="6Lc...",                 # required: site public key (data-sitekey)
        # v3 also takes page_action / min_score; Enterprise takes enterprise/s; Cloudflare takes cdata
    )
    solution = await cap.solve(info)
    print(solution.token)
 
asyncio.run(main())

Respuesta de muestra ( Solution ):

Solution(
  token="03AFcWeA6f...",                  # the credential to submit to the target site
  captcha_type=CaptchaType.RECAPTCHA_V2,
  expire_time=120,
  user_agent="Mozilla/5.0 ...",
  raw=TokenSolution(...),
)

Campos de respuesta:

• token — el token resuelto; envíelo como g-recaptcha-response para reCAPTCHA o cf-turnstile-response para Turnstile.
• captcha_type — el tipo CAPTCHA que se resolvió.
• expire_time — vencimiento del token en segundos; presente solo cuando el servicio lo devuelve; de lo contrario, None .
• user_agent — la UA utilizada para resolver; presente solo cuando el servicio lo devuelve; de lo contrario, None .
• raw: el TokenSolution sin formato, que contiene g_recaptcha_response / token / user_agent / expire_time.

4.2 solve_on_page — Detectar + resolver + rellenar toda la página (modo navegador)

Llamada y parámetros: la entrada es un Playwright page , con un SolveOnPageOptions opcional.

import asyncio
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright
 
async def main():
    cap = create_capsolver(api_key="YOUR_API_KEY")
 
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page()
        await page.goto("https://example.com/login")
 
        results = await cap.solve_on_page(page)   # or pass options=SolveOnPageOptions(...)
        for r in results:
            print(r.info.type, r.solution.token if r.solution else None, r.filled, r.error)
 
asyncio.run(main())

Respuesta de muestra ( list[SolveOnPageResult] ):

[
  SolveOnPageResult(
      info=CaptchaInfo(type=CaptchaType.RECAPTCHA_V2, website_url=..., website_key=...),
      solution=Solution(token="03AF...", captcha_type=CaptchaType.RECAPTCHA_V2),
      filled=True,
      error=None,
  ),
]

Campos de respuesta (por elemento):

• info — el CaptchaInfo para ese CAPTCHA (tipo y parámetros).
• solution — el Solution; None en caso de falla.
• filled: si el token se volvió a completar correctamente en la página.
• error — cadena de motivo del fallo; None sobre el éxito.

4.3 detect — Detecta qué CAPTCHA están en la página

Llamada y parámetros: la entrada es un Dramaturgo page .

types = await cap.detect(page)

Respuesta de muestra/campos ( list[CaptchaType] ):

[<CaptchaType.RECAPTCHA_V2: 'reCaptchaV2'>]

Devuelve una lista de las enumeraciones de tipo CAPTCHA detectadas en la página; una lista vacía significa que no se encontró ninguno.

4.4 get_captcha_info — Leer parámetros estructurados

Llamada y parámetros: la entrada es un Dramaturgo page .

infos = await cap.get_captcha_info(page)
for info in infos:
    print(info.type, info.website_url, info.website_key)
solution = await cap.solve(infos[0])     # once read, can be solved directly

Respuesta de muestra/campos ( list[CaptchaInfo] ):

# [CaptchaInfo(type=CaptchaType.RECAPTCHA_V2,
#              website_url="https://example.com",
#              website_key="6Lc...")]

4.5 get_balance — Consultar saldo

Llamada y parámetros: sin entrada.

balance = await cap.get_balance()
print(balance.balance, balance.packages)

Respuesta de muestra/campos ( BalanceResp ):

BalanceResp(balance=12.34, packages=[])

• balance — saldo de cuenta (flotación).
• packages — lista de planes/paquetes de suscripción; una lista vacía si no hay ninguna.

4.6 get_supported_captchas / get_handler — Acceso al registro

Llamada y respuesta:

cap.get_supported_captchas()      # → ['reCaptchaV2', 'reCaptchaV3', 'cloudflare']

• get_supported_captchas(): devuelve una lista de los tipos de cadenas actualmente admitidos.