コアSDK

エコシステム全体のエンジン。 capsolver-core は純粋な Python を使用して、ページ上の CAPTCHA を検出し、そのパラメーターを読み取り、CapSolver AI サービスを通じてそれらを解決し、トークンを埋め戻します。上位レベルの capsolver-agent パッケージと capsolver-mcp パッケージは両方ともその上に構築されます。

トークン モードのみ。 この SDK は、CapSolver API (reCAPTCHA v2/v3、Cloudflare Turnstile) からトークンをリクエストすることで解決します。画像グリッドをクリックしたり、ページ上でスライダーをドラッグしたりすることはありません。

1. 概要

capsolver-core は、「CAPTCHA の解決」を 4 つの明確な段階に分割し、単一のパイプラインに連鎖させます。

1. 検出 ( detect ) — ページ上にどの CAPTCHA タイプが存在するかを識別します。
2. パラメータの読み取り ( get_captcha_info ) — 各 CAPTCHA の構造化パラメータ (タイプ、サイト キー、URL など) をライブ ページから直接読み取ります。
3. Solve ( solve ) — パラメーターを CapSolver の AI サービスに渡し、使用可能なトークンを返します。
4. フィルバック ( solve_on_page ) — サイトが検証を合格したものとして扱うように、トークンをページ DOM に書き戻します。

このパイプラインの周りに、いくつかのエンジニアリング上の利便性が追加されます。

• ✅ 完全非同期 API — async / await に基づいて構築されているため、多数のソルブを同時に実行できます。
• ✅ 接続の再利用とクリーンアップ — 内部 HTTP 接続プールを維持し、非同期コンテキスト マネージャーとして機能します。
• ✅ プラグ可能なハンドラー レジストリ - 各 CAPTCHA タイプは 1 つのハンドラーによって処理され、カスタマイズまたはオーバーライドできます。
• ✅ 2 レベルの粒度 — パラメーターがわかっている場合は純粋な API を使用します。ページしかない場合は、Playwright Browser モードを使用してください。

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 ) のみが利用可能で、Playwright が欠落しているため、ブラウザーに依存するメソッド detect / get_captcha_info / solve_on_page は利用できません。

3. API と 2 つのモード

3.1 クライアントの作成

create_capsolver(**options) (または Capsolver(**options) ) はクライアントを返します。

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 メソッドの概要

3.3 入力の解決: CaptchaInfo

solve() へのコア入力は CaptchaInfo です。 type 、 website_url 、および website_key は必須です (空の website_url または website_key は ValueError を発生させます)。残りは CAPTCHA タイプに応じてオプションです。

solve_on_page() のオプションは SolveOnPageOptions によって制御されます。

solve() ( WaitOptions ) の wait_options には timeout と polling_interval の 2 つのオプション フィールドのみがあり、単一のソルブに対してクライアントのグローバル デフォルトをオーバーライドするために使用されます。

3.4 戻り値の型

detect() は list[CaptchaType] を返し、 get_captcha_info() は list[CaptchaInfo] を返します。

3.5 各モードでの API の使用方法

2 つのモードの唯一の違いは、パラメータの取得元です。これが、異なる 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 — 解決されたトークン。 reCAPTCHA の場合は g-recaptcha-response として、または Turnstile の場合は cf-turnstile-response として送信してください。
• captcha_type — 解決された CAPTCHA タイプ。
• expire_time — 秒単位のトークンの有効期限。サービスがそれを返す場合にのみ存在し、そうでない場合は None 。
• user_agent — 解決に使用される UA。サービスがそれを返す場合にのみ存在し、そうでない場合は None 。
• raw — g_recaptcha_response / token / user_agent / expire_time を含む生の TokenSolution 。

4.2 solve_on_page — ページ全体の検出 + 解決 + フィルバック (ブラウザ モード)

呼び出しとパラメータ: 入力は Playwright 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 — その CAPTCHA の CaptchaInfo (タイプとパラメータ)。
• solution — Solution ; 失敗時は None。
• filled — トークンがページに正常に埋め戻されたかどうか。
• error — 失敗理由の文字列。 成功した場合は None。

4.3 detect — ページ上にある CAPTCHA を検出する

呼び出しとパラメータ: 入力は Playwright page です。

types = await cap.detect(page)

応答/フィールドのサンプル ( list[CaptchaType] ):

[<CaptchaType.RECAPTCHA_V2: 'reCaptchaV2'>]

ページ上で検出された CAPTCHA タイプの列挙型のリストを返します。空のリストは、何も見つからなかったことを意味します。

4.4 get_captcha_info — 構造化パラメータの読み取り

呼び出しとパラメータ: 入力は Playwright 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() — 現在サポートされている型文字列のリストを返します。