Introducción e inicio rápido

1. Presentamos el SDK de Python de CapSolver

El SDK se envía como tres paquetes independientes, cada uno de los cuales se puede instalar por sí solo a través de pip install, además de un repositorio de ejemplos complementario. Juntos te permiten pasar de “hay un CAPTCHA en la página” a “tengo un token válido” en solo unas pocas líneas de Python, ya sea que estés escribiendo un script único, manejando un navegador real con Playwright o conectando la capacidad de resolución a un agente autónomo de IA.

Está impulsado por el servicio de resolución de IA de CapSolver. El SDK se encarga de todo por su parte: detectar el CAPTCHA, ensamblar los parámetros, llamar al servicio y volver a completar el resultado, mientras que el reconocimiento y la resolución reales se realizan en la nube. La idea central se reduce a una sola oración: su código (o su modelo) decide qué hacer, y CapSolver se encarga de resolverlo.

1.1 Funciones principales

• ✅ Resolución de tokens basada en IA: CapSolver devuelve un token que usted envía al sitio de destino.
• ✅ Dos modos de uso: API pura (modo token, para claves de sitios conocidos, no se requiere navegador) y modo navegador basado en Playwright.
• ✅ Cobertura de los principales CAPTCHA: reCAPTCHA v2/v3 (incluido Enterprise) y Cloudflare Turnstile.
• ✅ API totalmente asíncrona: construida sobre async / await, una opción natural para los rastreadores y agentes modernos.
• ✅ Paquetes de tres capas: desde el motor de bajo nivel hasta las herramientas del agente y un servicio MCP; Elija lo que necesita (ver 1.2).
• ✅ CLI incluidas: capsolver, capsolver-agent y capsolver-mcp le permiten ejecutar diagnósticos sin escribir ningún código.

1.2 CAPTCHA y parámetros admitidos

Actualmente, el SDK resuelve los siguientes tipos de CAPTCHA:

Los parámetros principales requeridos por cada tipo son website_url + website_key. reCAPTCHA v3 también puede aceptar page_action, min_score y una pista enterprise, mientras que Cloudflare puede aceptar cdata. Puede inspeccionar los tipos admitidos por su compilación actual en cualquier momento:

cap = create_capsolver(api_key="YOUR_API_KEY")
print(cap.get_supported_captchas())

Nota: En el modo Navegador, no necesita proporcionar estos parámetros manualmente: get_captcha_info(page) lee el tipo y la clave del sitio directamente desde la página en vivo.

2. Capacidades básicas (SDK)

2.1 Los Tres Paquetes

El conjunto completo de funciones más un repositorio de ejemplos. Estos no son tres pares para elegir: los dos últimos están construidos sobre capsolver-core, simplemente brindando la misma capacidad de resolución a través de una interfaz diferente. Elija el que mejor se adapte a su forma de trabajar.

** capsolver-core — El SDK principal (motor)**

El paquete de nivel más bajo y el motor compartido del que dependen los otros dos. Divide la resolución de un CAPTCHA en cuatro pasos (detectar → leer parámetros → resolver → completar) y ofrece dos niveles de granularidad: cuando se conoce la clave del sitio, utilice API pura (modo token, sin navegador); cuando solo tengas la página, deja que Playwright la detecte automáticamente y rellene el resultado. Totalmente asíncrono, con un registro de controlador conectable.

• Mejor para: scripts, rastreadores y automatización donde usted controla el código y no necesita un LLM.
• Puntos de entrada: create_capsolver() → solve() / solve_on_page().
• Instalar: pip install capsolver-core (agregue [playwright] para el modo Navegador).

** capsolver-agent — Herramientas del agente**

Envuelve el núcleo como herramientas que un LLM puede llamar: proporciona esquemas de herramientas independientes del marco más un ejecutor asíncrono, así como implementaciones LangChain BaseTool listas para usar. Dentro de su bucle, el modelo llama a “resolver” de la misma manera que llama a “hacer clic” o “escribir”, y el ejecutor transmite esa llamada a los métodos del núcleo y devuelve un resultado estructurado.

• Mejor para: dejar que el modelo decida cuándo resolver: llamada a función OpenAI, el SDK de agentes OpenAI, LangChain, uso del navegador o cualquier bucle de agente personalizado.
• Puntos de entrada: get_all_tools() + create_executor() o get_langchain_tools().
• Instalar: pip install capsolver-agent (agregue [langchain] para LangChain).

** capsolver-mcp — Servicio MCP**

Expone el mismo conjunto de herramientas que un servicio estándar a través del Protocolo de contexto del modelo. Cualquier cliente compatible con MCP descubre estas herramientas automáticamente al conectarse; no se requiere código de adaptador por cliente. Admite tres transportes: stdio, SSE y streamable-http.

• Mejor para: uso plug-and-play dentro de un cliente de IA: Claude Desktop, Claude Code, Cursor, Windsurf, Cline y más, con casi cero código de integración.
• Puntos de entrada: el comando capsolver-mcp o create_server().
• Instalar: pip install capsolver-mcp (agregue [browser] para las herramientas del navegador).

2.2 Casos de uso

Cada vez que un CAPTCHA bloquea el siguiente paso, este SDK gana su lugar. Algunos escenarios típicos:

Raspado web/recopilación de datos

Un rastreador llega a un reCAPTCHA o Turnstile en una página de listado, página de búsqueda o muro de inicio de sesión, y todo el proceso de recolección se detiene. Utilice el modo Token para obtener un token y enviarlo con su solicitud, o utilice el modo Navegador para completarlo directamente en la página; de cualquier manera, el raspado continúa. → Recomendado: capsolver-core (modo token cuando se conoce la clave del sitio; solve_on_page para páginas dinámicas).

Automatización de cuentas y flujo de trabajo

Los flujos de varios pasos, como el registro, el inicio de sesión, el restablecimiento de contraseña y el pago, a menudo generan un CAPTCHA en un paso específico, congelando todo el script. Deje de resolver exactamente en ese paso: una vez que se completa el token, el script continúa enviando el formulario, espera la redirección y ejecuta los pasos restantes hasta su finalización. → Recomendado: capsolver-core Modo navegador; especialmente fluido cuando su guión ya impulsa a Playwright.

Agentes de IA (navegación autónoma)

Déle a un agente una tarea como “iniciar sesión y realizar las órdenes” y obtendrá un CAPTCHA en algún lugar del camino sin previo aviso. En lugar de hacer que el modelo haga clic a través de sí mismo (la orientación con píxeles perfectos y las rutas del cursor similares a las humanas son difíciles de falsificar en motores de riesgo pasados, y los bucles de reintento de imágenes inundan la ventana contextual), registre una acción de “resolver”: cuando llega a un CAPTCHA, llama a la acción, recupera un token y continúa en la misma sesión del navegador sin interrumpir el flujo. → Recomendado: capsolver-agent (deje que el modelo lo llame a sí mismo), o capsolver-mcp (úselo directamente dentro de un cliente AI).

Pruebas automatizadas/herramientas internas

Las pruebas de extremo a extremo y las herramientas de operaciones internas deben borrar los pasos CAPTCHA en sus propios sitios o en sitios de terceros de manera confiable, sin que la intervención manual ralentice las cosas. → Recomendado: elegir por entorno: capsolver-core (en código) o capsolver-mcp (en un cliente).

En resumen: en cualquier lugar donde necesite borrar un CAPTCHA mediante programación en Python, este SDK está dentro del alcance.

3. Instalación y configuración de clave API

Antes de comenzar, tenga una cosa en cuenta: la resolución real ocurre en el servicio en la nube de CapSolver; el SDK solo lo llama desde su lado. Entonces el primer paso no es instalar un paquete; es tener una cuenta y una clave API. La configuración consta de tres pasos, en orden: regístrese y obtenga una clave → instale el SDK → conecte la clave.

3.1 Regístrese y obtenga su clave API

1. Registre una cuenta en el sitio web de CapSolver.
2. Abra el panel y copie su clave API.
3. Agregue fondos a su cuenta: cada resolución exitosa consume saldo y la resolución fallará cuando el saldo llegue a cero.

3.2 Instalar el SDK

Los tres paquetes están alojados actualmente como código abierto en GitHub y aún no están publicados en PyPI, así que instálelos a través de git. capsolver-core es el motor, y tanto capsolver-agent como capsolver-mcp dependen de él, por lo que siempre se requiere núcleo. Agregue la capa superior que desee utilizar:

# Engine (required; both other packages depend on it)
pip install git+https://github.com/capsolver-ai/capsolver-core.git
 
# Optional: MCP service — exposes the tools to MCP clients
pip install git+https://github.com/capsolver-ai/capsolver-mcp.git
 
# Optional: Agent tools — LLM-callable tool definitions + LangChain tools
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

Para el modo Navegador (detectar CAPTCHA en una página real y volver a completar el token), agregue el [playwright] extra e instale Chromium:

pip install "capsolver-core[playwright] @ git+https://github.com/capsolver-ai/capsolver-core.git"
playwright install chromium

Nota: detect y solve_on_page requieren el navegador adicional; El modo token no necesita ningún navegador.

Los tres repositorios son:

También puedes clonar un repositorio localmente antes de instalarlo, lo cual resulta útil para leer el código fuente o realizar tu propio desarrollo:

git clone https://github.com/capsolver-ai/capsolver-core.git
cd capsolver-core
pip install .            # or: pip install -e .  for an editable install

3.3 Conecte su clave API

Finalmente, entregue la clave del paso 3.1 al SDK. De forma predeterminada, todos los paquetes lo leen desde la variable de entorno CAPSOLVER_API_KEY:

# bash / zsh
export CAPSOLVER_API_KEY="your-capsolver-api-key"
 
# PowerShell
$env:CAPSOLVER_API_KEY = "your-capsolver-api-key"
 
# cmd
set CAPSOLVER_API_KEY=your-capsolver-api-key

Alternativamente, omita la variable de entorno y pase api_key="..." directamente a create_capsolver().

4. Tu primera solución

Con el entorno listo, ejecutemos de un extremo a otro con el código más pequeño posible. El camino que tome depende de si ya conoce la clave del sitio: si la conoce, use el modo Token; Si todo lo que tiene es la URL de una página, utilice el modo Navegador.

4.1 Modo Token (ya conoces la clave del sitio)

Cuando conoce el tipo de CAPTCHA, la URL de la página y la clave del sitio, no es necesario ningún navegador: entregue los parámetros y recupere un token.

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,
        website_url="https://example.com",
        website_key="6Lc...",
    )
    solution = await cap.solve(info)
    print(solution.token)  # submit as g-recaptcha-response
 
asyncio.run(main())

4.2 Modo Navegador (una llamada, directamente en la página en vivo)

Si todo lo que tiene es una página, y prefiere no buscar la clave del sitio usted mismo, deje que el SDK detecte automáticamente cada CAPTCHA en la página, los resuelva uno por uno y vuelva a llenar los tokens en el DOM. Una llamada lo hace todo.

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)
        for r in results:
            print(r.info.type, r.solution.token if r.solution else None, r.filled, r.error)
 
asyncio.run(main())