简介和快速入门

1. 介绍 CapSolver Python SDK

该 SDK 作为三个独立的软件包提供——每个软件包都可以通过 pip install 单独安装——加上一个配套的示例存储库。它们一起让您只需几行 Python 代码即可从“页面上有验证码”转变为“我有一个有效的令牌”——无论您是编写一次性脚本、使用 Playwright 驱动真正的浏览器，还是将解决能力连接到自主 AI 代理中。

它由 CapSolver 的 AI 解决服务提供支持。 SDK 会处理您这边的所有事情 - 检测验证码、组装参数、调用服务以及将结果填回 - 而实际的识别和解决则在云端进行。核心思想可以归结为一句话：你的代码（或你的模型）决定_做什么_，而 CapSolver 处理_解决它_。

1.1 核心特性

• ✅ 人工智能驱动的令牌解决 — CapSolver 返回您提交到目标站点的令牌。
• ✅ 两种使用模式 — 纯 API（令牌模式，用于已知站点密钥，无需浏览器）和基于 Playwright 的浏览器模式。
• ✅ 覆盖主要验证码 — reCAPTCHA v2 / v3（包括 Enterprise）和 Cloudflare Turnstile。
• ✅ 完全异步 API — 基于 async / await 构建，非常适合现代爬虫和代理。
• ✅ 三层包 — 从底层引擎到代理工具再到 MCP 服务；选择您需要的（参见 1.2）。
• ✅ 捆绑 CLI — capsolver 、 capsolver-agent 和 capsolver-mcp 让您无需编写任何代码即可运行诊断。

1.2 支持的验证码和参数

该SDK目前可解决以下验证码类型：

每种类型所需的核心参数是 website_url + website_key 。 reCAPTCHA v3 还可以采用 page_action 、 min_score 和 enterprise 提示，而 Cloudflare 可以采用 cdata 。您可以随时检查当前版本支持的类型：

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

注意： 在浏览器模式下，您无需手动提供这些参数 — get_captcha_info(page) 会直接从实时页面读取类型和站点密钥。

2. 核心能力（SDK）

2.1 三个包

完整的功能集以及一个示例存储库。这不是三个可供选择的对等体 - 后两个都构建在 capsolver-core 之上，只是通过不同的接口提供相同的解决能力。选择最适合您工作方式的一项。

** capsolver-core — 核心 SDK（引擎）**

最低级别的包，以及另外两个包所依赖的共享引擎。它将验证码的解析分为四个步骤——检测→读取参数→解析→填充——并提供两个级别的粒度：当站点密钥已知时，采用纯API（令牌模式，无浏览器）；当站点密钥已知时，采用纯API（令牌模式，无浏览器）；当您只有页面时，让 Playwright 自动检测并将结果填回。完全异步，具有可插入的处理程序注册表。

• 最适合：脚本、爬虫和自动化，您可以控制代码并且不需要法学硕士。
• 入口点： create_capsolver() → solve() / solve_on_page() 。
• 安装： pip install capsolver-core（为浏览器模式添加 [playwright]）。

** capsolver-agent — 代理工具**

将核心包装为法学硕士可以调用的工具：它提供与框架无关的工具模式以及异步执行器，以及现成的 LangChain BaseTool 实现。在其循环中，模型调用“解决”的方式与调用“单击”或“类型”的方式相同，并且执行器中继调用核心的方法并返回结构化结果。

• 最适合： 让模型决定何时求解 — OpenAI 函数调用、OpenAI Agents SDK、LangChain、浏览器使用或任何自定义代理循环。
• 入口点： get_all_tools() + create_executor() 或 get_langchain_tools() 。
• 安装： pip install capsolver-agent（为LangChain添加[langchain]）。

** capsolver-mcp — MCP 服务**

通过 模型上下文协议 将同一组工具公开为标准服务。任何与 MCP 兼容的客户端都会在连接时自动发现这些工具 — 无需每个客户端适配器代码。支持三种传输：stdio、SSE 和 Streamable-http。

• 最适合： 在 AI 客户端内即插即用 - Claude Desktop、Claude Code、Cursor、Windsurf、Cline 等，集成代码几乎为零。
• 入口点： capsolver-mcp 命令，或 create_server() 。
• 安装： pip install capsolver-mcp（为浏览器工具添加 [browser]）。

2.2 用例

每当验证码阻止下一步时，此 SDK 就会赢得一席之地。几个典型场景：

网页抓取/数据收集

爬虫程序在列表页面、搜索页面或登录墙上点击 reCAPTCHA 或 Turnstile，整个收集管道就会停止。使用令牌模式获取令牌并将其与您的请求一起提交，或者使用浏览器模式将其直接填充到页面中 - 无论哪种方式，抓取都会继续。 → 推荐： capsolver-core（当站点密钥已知时的令牌模式；solve_on_page 用于动态页面）。

账户和工作流程自动化

注册、登录、密码重置和结帐等多步骤流程通常会在某一特定步骤中抛出验证码，从而冻结整个脚本。将解决问题直接放到该步骤中 - 填充令牌后，脚本将继续提交表单，等待重定向，并运行剩余步骤以完成。 → 推荐： capsolver-core 浏览器模式；当您的剧本已经驱动 Playwright 时，尤其流畅。

人工智能代理（自主浏览）

给代理一个类似“登录并拉取订单”的任务，它会在没有警告的情况下在某个地方遇到验证码。不是让模型点击自身——像素完美的定位和类似人类的光标路径很难伪造过去的风险引擎，并且图像重试循环会淹没上下文窗口——为其注册一个“解决”操作：当它命中验证码时，它会调用该操作，取回令牌，并在同一个浏览器会话中继续，而不会中断流程。 → 推荐： capsolver-agent（让模型自行调用），或 capsolver-mcp（直接在 AI 客户端内使用）。

自动化测试/内部工具

端到端测试和内部操作工具需要可靠地清除您自己或第三方站点上的验证码步骤，而无需手动干预来减慢速度。 → 推荐： 按环境选择 — capsolver-core（在代码中）或 capsolver-mcp（在客户端中）。

简而言之：任何您需要在 Python 中以编程方式清除验证码的地方，此 SDK 都在范围内。

3. 安装和 API 密钥设置

在开始之前，请记住一件事：实际的求解发生在 CapSolver 的云服务上 - SDK 仅从您这边调用它。所以第一步不是安装软件包；而是安装软件包。它有一个帐户和一个 API 密钥。设置分为三个步骤，依次为：注册并获取密钥→安装 SDK→连接密钥。

3.1 注册并获取您的 API 密钥

1. 在【CapSolver网站】（https://www.capsolver.com）注册账户。
2. 打开仪表板并复制您的 API 密钥。
3. 为您的账户添加资金——每次成功的解决都会消耗余额，当余额为零时解决将失败。

3.2 安装SDK

这三个包目前作为开源托管在 GitHub 上，尚未发布到 PyPI，因此请通过 git 安装它们。 capsolver-core 是引擎，capsolver-agent 和 capsolver-mcp 都依赖于它 - 所以核心始终是必需的。添加您想要使用的上层：

# 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

对于浏览器模式（在真实页面上检测验证码并重新填写令牌），添加 [playwright] 额外内容并安装 Chromium：

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

注意： detect 和 solve_on_page 需要额外的浏览器；令牌模式根本不需要浏览器。

这三个存储库是：

您还可以在安装之前在本地克隆存储库 - 方便阅读源代码或进行自己的开发：

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 连接您的 API 密钥

最后，将步骤3.1中的密钥交给SDK。默认情况下，所有包都从 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

或者，跳过环境变量并将 api_key="..." 直接传递给 create_capsolver() 。

4. 你的第一个解决方案

环境准备好后，让我们用尽可能少的代码端到端地运行一下。选择哪条路径取决于您是否已经知道站点密钥：如果知道，请使用 Token 模式；如果您只有一个页面 URL，请使用浏览器模式。

4.1 令牌模式（您已经知道站点密钥）

当您知道验证码类型、页面 URL 和站点密钥时，无需浏览器 - 移交参数，取回令牌。

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 浏览器模式（一键直达直播页面）

如果您只有一个页面（并且您不想自己寻找站点密钥），请让 SDK 自动检测页面上的每个验证码，逐一解决它们，并将令牌填充回 DOM。一通电话即可搞定一切。

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())