概要とクイックスタート

1. CapSolver Python SDK の紹介

SDK は、3 つの独立したパッケージ (それぞれ pip install 経由で単独でインストール可能) と、付随するサンプルリポジトリとして出荷されます。これらを組み合わせることで、1 回限りのスクリプトを作成する場合でも、Playwright で実際のブラウザを駆動する場合でも、解決機能を自律型 AI エージェントに接続する場合でも、わずか数行の Python で「ページに CAPTCHA がある」から「有効なトークンを持っている」に至ることができます。

これは、CapSolver の AI 解決サービスを利用しています。 SDK は、CAPTCHA の検出、パラメータの組み立て、サービスの呼び出し、結果の埋め戻しなど、すべてをユーザー側で処理しますが、実際の認識と解決はクラウドで行われます。核となるアイデアは 1 つの文に要約されます。コード (またはモデル) が「何をする」かを決定し、CapSolver がそれを「解決」します。

1.1 コア機能

✅ AI を活用したトークン解決 — CapSolver は、ターゲットサイトに送信したトークンを返します。
✅ 2 つの使用モード — 純粋な API (トークンモード、既知のサイトキー用、ブラウザーは不要) と Playwright ベースのブラウザモード。
✅ 主要な CAPTCHA の範囲 — reCAPTCHA v2 / v3 (Enterprise を含む) および Cloudflare Turnstile。
✅ 完全非同期 API — async / await に基づいて構築されており、最新のクローラーやエージェントに自然に適合します。
✅ 3 層パッケージ — 低レベルのエンジンからエージェントツール、MCP サービスまで。必要なものを選択してください (1.2 を参照)。
✅ バンドルされた CLI — capsolver 、 capsolver-agent 、および capsolver-mcp を使用すると、コードを書かずに診断を実行できます。

1.2 サポートされている CAPTCHA とパラメータ

SDK は現在、次の CAPTCHA タイプを解決します。

タイプ	列挙型 ( `CaptchaType` )	工具値 ( `captcha_type` )	メモ
reCAPTCHA v2	`RECAPTCHA_V2`	`reCaptchaV2`	目に見えないものを含む
reCAPTCHA v3	`RECAPTCHA_V3`	`reCaptchaV3`	エンタープライズを含む
クラウドフレア回転木戸	(クラウドフレア)	`cloudflare`	回転式改札口ウィジェット

すべての型で必要なコアパラメーターは 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 3 つのパッケージ

完全な機能セットと 1 つのサンプルリポジトリ。これらは 3 つのピアから選択できるものではありません。後の 2 つは両方とも capsolver-core の上に構築されており、異なるインターフェイスを通じて同じ解決機能を提供しているだけです。自分の働き方に最も適したものを選択してください。

** capsolver-core — コア SDK (エンジン)**

最下位レベルのパッケージと、他の 2 つが依存する共有エンジン。 CAPTCHA の解決を 4 つのステップ (検出 → パラメータの読み取り → 解決 → フィルバック) に分割し、2 つのレベルの粒度を提供します。サイトキーがわかっている場合は、純粋な API (トークンモード、ブラウザなし) を使用します。ページしかない場合は、Playwright に自動検出して結果を入力させます。完全に非同期で、プラグ可能なハンドラーレジストリを備えています。

最適な用途: コードを制御し、LLM を必要としない スクリプト、クローラー、自動化。
エントリポイント: create_capsolver() → solve() / solve_on_page() 。
インストール: pip install capsolver-core (ブラウザモードの場合は [playwright] を追加)。

** capsolver-agent — エージェントツール**

LLM が呼び出すことができるツールとしてコアをラップします。これは、フレームワークに依存しないツールスキーマと非同期エグゼキュータ、および既製の 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 の 3 つのトランスポートをサポートします。

最適な用途: AI クライアント内でのプラグアンドプレイの使用 — Claude Desktop、Claude Code、Cursor、Windsurf、Cline などを、統合コードがほぼゼロで使用できます。
エントリポイント: capsolver-mcp コマンド、または create_server() 。
インストール: pip install capsolver-mcp (ブラウザツール用に [browser] を追加)。

リポジトリ	パッケージ	一行の役割
キャプソルバーコア	`capsolver-core`	コア SDK — CAPTCHA を検出し、API を呼び出して解決し、トークンを埋め戻します。
エージェント-キャプソルバー	`capsolver-agent`	エージェントツール — フレームワークに依存しないツールスキーマ + LangChain ツール
mcp-capsolver	`capsolver-mcp`	MCP サービス — モデルコンテキストプロトコル経由で解決ツールを公開する

2.2 使用例

CAPTCHA が次のステップをブロックするたびに、この SDK がその役割を果たします。いくつかの典型的なシナリオ:

Webスクレイピング/データ収集

クローラーがリストページ、検索ページ、またはログインウォールの reCAPTCHA または Turnstile にヒットし、コレクションパイプライン全体が停止します。トークンモードを使用してトークンを取得し、リクエストとともに送信するか、ブラウザモードを使用してトークンをページに直接入力します。どちらの方法でもスクレイピングは続行されます。 → 推奨: capsolver-core (サイトキーがわかっている場合はトークンモード、動的ページの場合は solve_on_page)。

アカウントとワークフローの自動化

サインアップ、ログイン、パスワードのリセット、チェックアウトなどの複数のステップのフローでは、多くの場合、特定の 1 つのステップで CAPTCHA がスローされ、スクリプト全体がフリーズします。解決をまさにそのステップにドロップします。トークンが入力されると、スクリプトはフォームの送信を続け、リダイレクトを待ち、残りのステップを実行して完了します。 → 推奨: capsolver-core ブラウザモード。スクリプトがすでに Playwright を駆動している場合は特にスムーズです。

AI エージェント (自律ブラウジング)

エージェントに「ログインして注文を取り出す」などのタスクを与えると、警告なしに途中のどこかで CAPTCHA がヒットします。モデル自体がクリックスルーするのではなく (ピクセル完璧なターゲティングと人間のようなカーソルパスは過去のリスクエンジンを偽装するのが難しく、画像再試行ループがコンテキストウィンドウに溢れるため)、モデルの「解決」アクションを登録します。CAPTCHA に到達すると、アクションが呼び出され、トークンが返され、フローを中断することなく同じブラウザセッションで続行されます。 → 推奨: capsolver-agent (モデル自体を呼び出す)、または capsolver-mcp (AI クライアント内で直接使用する)。

自動テスト/内部ツール

エンドツーエンドのテストと内部運用ツールは、手動介入による処理速度の低下を招くことなく、独自のサイトまたはサードパーティのサイトで CAPTCHA ステップを確実にクリアする必要があります。 → 推奨: 環境によって選択します — capsolver-core (コード内) または capsolver-mcp (クライアント内)。

つまり、Python でプログラムによって CAPTCHA をクリアする必要がある場所ならどこでも、この SDK は範囲内にあります。

3. インストールと API キーのセットアップ

始める前に、1 つのことに留意してください。実際の解決は CapSolver のクラウドサービスで行われます。SDK はユーザー側からのみそれを呼び出します。したがって、最初のステップはパッケージをインストールすることではありません。アカウントと API キーを持っています。セットアップは次の 3 つのステップで行われます。キーの登録と取得→ SDK のインストール→キーの接続 です。

3.1 API キーを登録して取得する

CapSolver Web サイトでアカウントを登録します。
ダッシュボードを開き、API キーをコピーします。
アカウントに資金を追加します。解決が成功するたびに残高が消費され、残高がゼロになると解決は失敗します。

3.2 SDK をインストールする

3 つのパッケージは現在 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

ブラウザモード (実際のページで CAPTCHA を検出し、トークンを再度入力する) の場合は、[playwright] を追加して Chromium をインストールします。

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

注意: detect と solve_on_page には追加のブラウザが必要です。トークンモードではブラウザはまったく必要ありません。

3 つのリポジトリは次のとおりです。

パッケージ	GitHub リポジトリ
`capsolver-core`	https://github.com/capsolver-ai/capsolver-core
`capsolver-agent`	https://github.com/capsolver-ai/capsolver-agent
`capsolver-mcp`	https://github.com/capsolver-ai/capsolver-mcp

インストールする前にリポジトリのクローンをローカルに作成することもできます。これは、ソースを読んだり、独自の開発を行う場合に便利です。

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 キーを接続する

Finally, hand the key from step 3.1 to the 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. 最初の解決

環境の準備ができたら、可能な限り最小のコードをエンドツーエンドで実行してみましょう。どのパスを選択するかは、サイトキーを既に知っているかどうかによって決まります。知っている場合は、トークンモードを使用します。ページ URL しかない場合は、ブラウザモードを使用してください。

4.1 トークンモード (サイトキーはすでにわかっています)

CAPTCHA タイプ、ページ 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 ブラウザモード (1 回の呼び出し、ライブページ上で直接)

持っているのがページだけで、サイトキーを自分で探したくない場合は、SDK にページ上のすべての CAPTCHA を自動検出させ、それらを 1 つずつ解決し、トークンを DOM に埋め戻します。 1 回の電話ですべてが完了します。

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

人工知能エージェントのCapSolver コアSDK