指南
CapSolver AI
核心 SDK

核心SDK

整个生态系统的引擎。 capsolver-core 使用纯 Python 来检测页面上的验证码，读取其参数，通过 CapSolver AI 服务解决它们，然后将令牌填回。更高级别的 capsolver-agent 和 capsolver-mcp 包都构建在其之上。

仅限令牌模式。 此 SDK 通过从 CapSolver API（reCAPTCHA v2/v3、Cloudflare Turnstile）请求令牌来解决。它不会单击页面上的图像网格或拖动滑块。

1. 概述

capsolver-core 将“解决验证码”分为四个清晰的阶段，链接到一个管道中：

  1. 检测 ( detect ) — 识别页面上存在哪些验证码类型。
  2. 读取参数 ( get_captcha_info ) — 直接从实时页面读取每个验证码的结构化参数（类型、站点密钥、URL 等）。
  3. Solve ( solve ) — 将参数交给 CapSolver 的 AI 服务并取回可用的令牌。
  4. 填回 ( solve_on_page ) — 将令牌写回到页面 DOM 中，以便站点将验证视为已通过。

围绕这条管道，它增加了一些工程便利：

  • ✅ 完全异步 API — 构建于 async / await 之上，因此您可以同时运行大量求解。
  • ✅ 连接重用和清理 — 维护内部 HTTP 连接池并充当异步上下文管理器。
  • ✅ 可插入处理程序注册表 — 每个验证码类型均由一个处理程序处理，您可以自定义或覆盖该处理程序。
  • ✅ 两级粒度 — 当参数已知时采用纯 API；当您只有页面时，请使用剧作家浏览器模式。

什么时候应该直接使用 core？ 当您自己控制代码并且不需要向 LLM 公开求解时。

2.安装

capsolver-core 在 GitHub 上开源，尚未发布到 PyPI，因此通过 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

设置你的密钥：

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

注意： SDK 在没有 [playwright] 额外功能的情况下工作 - 在这种情况下，只有令牌模式 ( solve ) 可用，并且依赖于浏览器的方法 detect / get_captcha_info / solve_on_page 不可用，因为缺少 Playwright。

3. API 和两种模式

3.1 创建客户端

create_capsolver(**options) （或 Capsolver(**options) ）返回一个客户端。

选项默认描述
api_key—CapSolver 客户端密钥（求解所需）
servicehttps://api.capsolver.comAPI 基本 URL
default_timeout120总轮询预算（以秒为单位）
polling_interval5结果轮询之间的间隔（以秒为单位）
request_timeout_ms30000单个HTTP请求超时
app_id—开发者/附属机构 ID
handlers全部内置覆盖已注册的验证码处理程序
source—流量来源标识符
version—客户端版本标签
on_error—非致命错误的回调

Capsolver 拥有一个内部 HTTP 连接池，因此最好将其用作异步上下文管理器以确保释放连接：

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 方法概览

方法参数返回描述
solve(info, wait_options?)CaptchaInfo 、 WaitOptions?Solution从参数求解
detect(page)剧作家pagelist[CaptchaType]页面上有哪些验证码
get_captcha_info(page)剧作家pagelist[CaptchaInfo]每个小部件的结构化参数
solve_on_page(page, options?)page 、 SolveOnPageOptions?list[SolveOnPageResult]检测→解决→填充
get_balance()—BalanceResp账户余额
register(handler)CaptchaHandler—将处理程序添加到注册表
get_supported_captchas()—list[str]列出支持的类型
get_handler(key)STR / CaptchaTypeCaptchaHandler | None通过键查找处理程序

3.3 求解输入：CaptchaInfo

solve() 的核心输入是 CaptchaInfo 。 type 、 website_url 和 website_key 是必需的（空的 website_url 或 website_key 引发 ValueError ）；其余部分是可选的，具体取决于验证码类型：

参数类型必填适用于描述
typeCaptchaType是的全部RECAPTCHA_V2 / RECAPTCHA_V3 / CLOUDFLARE
website_urlSTR是的全部托管验证码的页面的完整 URL
website_keySTR是的全部站点公钥（reCAPTCHA 的 data-sitekey / Turnstile 的站点密钥）
versionSTR没有验证码"v2" 或 "v3" ；通常会自动检测到
page_actionSTR没有reCAPTCHA v3v3 操作名称（例如 "login" ）
min_score浮动没有reCAPTCHA v3期望的最低分数 (0.0–1.0)
invisible布尔没有reCAPTCHA v2这是否是隐形v2
enterprise布尔没有验证码是否使用Enterprise变体
sSTR没有reCAPTCHA 企业企业 s 代币
cdataSTR没有云耀旋转门的cdata自定义参数
proxySTR没有全部代理，如 user:pass@host:port 或 host:port
user_agentSTR没有全部自定义用户代理
container_idSTR没有浏览器补回DOM id 用于在回填期间定位小部件容器
callbackSTR没有浏览器补回求解后触发的回调函数名称
binded_button_idSTR没有浏览器补回关联提交按钮的 DOM id
extra字典没有全部尚未建模的字段的传递

solve_on_page() 的选项由 SolveOnPageOptions 控制：

选项类型默认描述
autofill布尔True解决后是否自动将token填回页面DOM
throw_on_error布尔False在单个 CAPTCHA 失败时，是引发异常还是将其记录在 error 字段中
timeout浮动客户端默认此呼叫的总轮询预算（以秒为单位）
polling_interval浮动客户端默认此调用的轮询间隔（以秒为单位）

solve() ( WaitOptions ) 的 wait_options 只有两个可选字段 timeout 和 polling_interval ，用于覆盖单个求解的客户端全局默认值。

3.4 返回类型

类型领域描述
Solutiontoken已解决的令牌 - 您提交到目标站点的凭据
captcha_type已解决的验证码类型
expire_time令牌过期时间（以秒为单位）（仅在服务返回时出现）
user_agent用于解决的UA（仅在服务返回时出现）
raw原始 TokenSolution （包含 g_recaptcha_response 等）
SolveOnPageResultinfo该验证码的 CaptchaInfo
solutionSolution ; None 失败
filledtoken是否被填回页面
error失败原因； None 成功
BalanceRespbalance账户余额（浮动）
packages计划/订阅套餐列表

detect() 返回 list[CaptchaType] ， get_captcha_info() 返回 list[CaptchaInfo] 。

3.5 每种模式如何使用这些 API

两种模式之间的唯一区别是参数来自哪里——这就是它们调用不同 API 的原因：

令牌模式（您已经知道站点密钥） - 仅使用 solve() 。您自己构造 CaptchaInfo 并取回令牌：

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

浏览器模式（使用 Playwright 驱动页面） — 使用 detect() / get_captcha_info() / solve_on_page() 。一体化 solve_on_page() 涵盖检测、求解和填充；或者您可以单独运行这些步骤来自己控制每个阶段：

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. 调用每个 API：请求和响应

本节将分别介绍每个方法 - 真正的调用、要传递的参数、示例响应以及响应字段的说明。

4.1 solve — 求解（令牌模式）

调用和响应示例：

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

响应示例 ( 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(...),
)

响应字段：

  • token — 已解决的令牌；将其提交为 g-recaptcha-response（用于 reCAPTCHA）或 cf-turnstile-response（用于 Turnstile）。
  • captcha_type — 已解决的验证码类型。
  • expire_time — 令牌到期时间（以秒为单位）；仅当服务返回它时才存在，否则 None 。
  • user_agent — 用于求解的 UA；仅当服务返回它时才存在，否则 None 。
  • raw — 原始 TokenSolution ，包含 g_recaptcha_response / token / user_agent / expire_time 。

4.2 solve_on_page — 全页检测+求解+填充（浏览器模式）

**调用和参数：**输入是剧作家 page ，带有可选的 SolveOnPageOptions 。

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

响应示例 ( 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,
  ),
]

响应字段（每个项目）：

  • info — 该验证码的 CaptchaInfo（类型和参数）。
  • solution — Solution ； None 失败。
  • filled — 令牌是否成功填回页面。
  • error — 失败原因字符串； None 成功。

4.3 detect — 检测页面上有哪些验证码

**调用和参数：**输入是剧作家 page 。

types = await cap.detect(page)

示例响应/字段 ( list[CaptchaType] ):

[<CaptchaType.RECAPTCHA_V2: 'reCaptchaV2'>]

返回页面上检测到的验证码类型枚举列表；空列表意味着没有找到。

4.4 get_captcha_info — 读取结构化参数

**调用和参数：**输入是剧作家 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

示例响应/字段 ( list[CaptchaInfo] ):

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

4.5 get_balance — 检查余额

**调用和参数：**无输入。

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

示例响应/字段 ( BalanceResp ):

BalanceResp(balance=12.34, packages=[])
  • balance — 账户余额（浮动）。
  • packages — 计划/订阅包列表；如果没有则为空列表。

4.6 get_supported_captchas / get_handler — 注册表访问

呼叫和响应：

cap.get_supported_captchas()      # → ['reCaptchaV2', 'reCaptchaV3', 'cloudflare']
  • get_supported_captchas() — 返回当前支持的类型字符串的列表。
简介 & 快速开始Agent 工具