SkyvernによるCapSolverの統合：AIブラウザ自動化におけるCAPTCHA処理のガイド

TL;DR

• Skyvernは、ウェブページを開き、フォームを入力し、ビジネスワークフローを進行する責任を負い、CapSolver はCAPTCHAトークンを返却します。

• 自前の capsolver SDKを直接インストールし、capsolver.solve()を呼び出して、createTaskとポーリングロジックを自分で実装する必要を避けてください。

• トークンを取得したら、それを現在のブラウザページに戻し、Skyvernにフォームを送信し、結果を検証させます。

イントロダクション

Skyvernは、Playwright、ビジョンモデル、および大規模言語モデル（LLM）に基づいたAIブラウザ自動化プラットフォームです。Skyvernは、ウェブページ内のテキスト、フォーム、インタラクティブな要素を理解し、自然言語の指示に基づいてページナビゲーション、ボタンクリック、コンテンツ入力、ファイルアップロード、情報抽出、マルチステップワークフローなどのタスクを完了できます。このアプローチにより、ページ構造の変更によって引き起こされるスクリプトの保守コストを削減し、ログイン、フォーム送信、バックオフィス操作、データ収集などのシナリオに最適です。

自動化ワークフローがCAPTCHAチャレンジに遭遇した場合、現在のページURL、サイトキー、CAPTCHAタイプなどのパラメータを提供して、公式のCapSolver Python SDKを呼び出すことができます。CapSolverがタスクを完了すると、対応する検証トークンが返却されます。プログラムはPlaywrightを使用して、このトークンを現在のページの応答フィールド、JavaScriptコールバック、またはビジネスリクエストに書き込みます。検証が成功すると、Skyvernは元のユーザー承認タスクを継続して実行できます。例えば、フォームの送信、次のページへの移動、最終的な操作結果の確認などです。

1. 依存関係のインストール

Skyvernは現在、Python 3.11、3.12、または3.13を必要とします。Skyvern、CapSolver SDK、Chromiumをインストールしてください：

pip install "skyvern[local]"
pip install --upgrade capsolver
python -m playwright install chromium

2. CapSolverコード

# pip install --upgrade capsolver
# export CAPSOLVER_API_KEY='...'

import capsolver

# capsolver.api_key = "..."
solution = capsolver.solve({
    "type": "ReCaptchaV2TaskProxyLess",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})

print(solution)

成功した場合、返却される結果は主に以下になります：

token = solution["gRecaptchaResponse"]

パラメータの役割：

websiteURLとwebsiteKeyは、現在のページの実際の設定と一致する必要があります。

3. Skyvern統合例

以下は最小限の統合例です。Skyvernはまずページを開き、フォームを入力し、その後公式SDK経由でトークンを取得し、最後にトークンをページに戻して送信します。

import asyncio
import capsolver
from skyvern import Skyvern


TARGET_URL = "https://www.google.com/recaptcha/api2/demo"
WEBSITE_KEY = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"


async def inject_token(page, token: str):
    await page.evaluate(
        """
        (token) => {
            const textarea = document.getElementById('g-recaptcha-response');
            if (textarea) {
                textarea.value = token;
            }
        }
        """,
        token,
    )


async def main():
    skyvern = Skyvern.local()
    browser = await skyvern.launch_local_browser(headless=False)
    page = await browser.get_working_page()

    try:
        await page.goto(TARGET_URL)
        solution = await asyncio.to_thread(
            capsolver.solve,
            {
                "type": "ReCaptchaV2TaskProxyLess",
                "websiteURL": TARGET_URL,
                "websiteKey": WEBSITE_KEY,
            },
        )

        token = solution["gRecaptchaResponse"]
        await inject_token(page, token)

        await page.act("Submit")
        await page.validate("Verification successful... Great!")
    finally:
        await browser.close()

4. トークンをページに戻す方法

CapSolverはトークンを返却する責任を負いますが、ターゲットサイトのビジネスフォームを自動的に送信しません。異なるウェブサイトはトークンをさまざまな方法で処理します。一般的な方法には以下が含まれます：

1. g-recaptcha-responseの隠しフィールドに書き込むこと；
2. ページに設定されたJavaScriptコールバックを呼び出すこと；
3. トークンをビジネスインターフェースのパラメータとして送信すること。

例のinject_token()は、隠しフィールドとテストコールバックの両方を試みます。実際の使用では、このスニペットは自社ウェブサイトのフロントエンド実装に応じて調整する必要があります。

5. 一般的な問題

トークンが返却されるが、ページは依然として失敗する

以下のパラメータを確認してください：

• websiteURLは現在のページアドレスですか？
• websiteKeyは現在のサイトからのものですか？
• トークンを取得した後にページがリフレッシュされましたか？
• トークンは正しいページのコールバックまたはビジネスインターフェースに渡されましたか？

6. CapSolver APIを使用してImageToTextを解決する

reCAPTCHAに加えて、SkyvernはCapSolverと連携して通常の画像からテキストへのCAPTCHAを処理することもできます。BotDetect CAPTCHA Demoを例として、CAPTCHA画像の要素IDはdemoCaptcha_CaptchaImage、結果入力ボックスのIDはcaptchaCode、検証ボタンのIDはvalidateCaptchaButtonです。

ImageToTextTaskは、CAPTCHA画像をBase64に変換し、bodyパラメータ経由で送信する必要があります。画像srcがData URLの場合、例えば：

data:image/png;base64,iVBORw0KGgoAAA...

CapSolverに渡す際は、コンマの後のBase64コンテンツのみを保持し、data:image/...;base64,プレフィックスは除外してください。トークンタイプのタスクとは異なり、ImageToTextTaskは追加のgetTaskResultポーリングを必要とせず、認識結果を直接返します。

以下は完全なSkyvern統合例です：

import asyncio

import capsolver
from skyvern import Skyvern


TARGET_URL = "https://captcha.com/demos/features/captcha-demo.aspx"


async def main():
    skyvern = Skyvern.local()
    browser = await skyvern.launch_local_browser(headless=False)
    page = await browser.get_working_page()

    try:
        await page.goto(TARGET_URL)
        await page.locator("#demoCaptcha_CaptchaImage").wait_for()

        # CAPTCHA画像のData URLを読み込む。
        image_src = await page.locator(
            "#demoCaptcha_CaptchaImage"
        ).get_attribute("src")

        if not image_src or "," not in image_src:
            raise RuntimeError("有効なBase64 CAPTCHA画像が見つかりませんでした")

        # Data URLプレフィックスを削除し、Base64データのみを保持する。
        base64_image = image_src.split(",", 1)[1]

        solution = await asyncio.to_thread(
            capsolver.solve,
            {
                "type": "ImageToTextTask",
                "websiteURL": TARGET_URL,
                "module": "common",
                "body": base64_image,
            },
        )

        captcha_text = solution["text"]
        print("認識結果:", captcha_text)

        await page.locator("#captchaCode").fill(captcha_text)
        await page.locator("#validateCaptchaButton").click()
        await page.wait_for_timeout(5000)
    finally:
        await browser.close()


if __name__ == "__main__":
    asyncio.run(main())

コードの実行プロセスは以下のように要約できます：

SkyvernがCAPTCHAページを開く
  -> #demoCaptcha_CaptchaImageを検索
  -> Base64画像データを抽出し、クリーンアップ
  -> capsolver.solve(ImageToTextTask)を呼び出す
  -> solution["text"]を読み込む
  -> #captchaCodeに記入
  -> #validateCaptchaButtonをクリック

適切な認識モデルの選択

moduleはオプションのパラメータで、デフォルトではcommonを使用できます。CAPTCHAに数字のみが含まれる場合、numberを使用できます。一部の特殊なスタイルには、CapSolverドキュメントに従って対応する独立モデルを選択することで認識精度を向上させることができます。

例えば、数字のみのCAPTCHAを認識する場合、タスクパラメータを以下のように変更できます：

solution = capsolver.solve({
    "type": "ImageToTextTask",
    "module": "number",
    "images": [base64_image],
})

answers = solution["answers"]

numberモデルは複数の画像を一度に送信できます。imagesには最大9つのBase64文字列を含めることができます。他のモデル名と対応する画像タイプについては、公式CapSolver ImageToTextTaskドキュメントを参照してください。

7. まとめ

AIブラウザ自動化の適切な技術的解決策を選ぶことは、タスクの複雑さ、ページ変更の頻度、およびターゲットウェブサイトの検証メカニズムに依存します。SeleniumやPlaywrightなどの従来のツールは、構造が安定し、明確な操作経路を持つ自動化ワークフローに適しています。SkyvernはビジョンモデルとLLMを導入することで、ページ構造が頻繁に変化し、意味的理解が必要な、またはマルチステップ操作を含むウェブタスクに適しています。SkyvernはPlaywrightに基づいてブラウザを制御するため、自然言語を通じてページナビゲーション、フォーム入力、ボタンクリック、データ抽出を完了できます。プロセスがCAPTCHAチャレンジに遭遇した場合、開発者は公式のCapSolver SDKを組み合わせて検証トークンを取得し、結果を現在のページに戻して、フォーム送信、ページ遷移、結果検証などの後続の操作を継続させることができます。SkyvernとCapSolverを組み合わせることで、開発者はより柔軟で保守しやすく、スケーラブルなブラウザ自動化ワークフローを構築でき、従来のセレクターの保守コストを削減し、複雑なウェブタスクの実行効率と安定性を向上させることができます。権限の範囲を明確に定義し、APIキーを保護し、自動化結果を検証し記録することは、関連プロジェクトの安定した運用のための重要な前提条件です。

参考文献

• Skyvern GitHub

• CapSolver reCAPTCHA公式ドキュメント

• CapSolver ImageToTextTask公式ドキュメント

CapSolverボーナスコードを取得する

自動化予算を即座に増やす！
CapSolverアカウントにチャージする際にボーナスコード CAP26 を使用すると、毎回チャージに対して 5%のボーナス を受け取れます — 制限なし。
CapSolverダッシュボードで今すぐ取得してください

よくある質問（FAQ）

Q1: iframe内のCAPTCHAをどう処理しますか？
A1: トークンを挿入する前にpage.frame_locator('iframe_selector')を使用してiframeコンテキストに切り替えてください。CapSolverに送信するwebsiteURLはiframeURLではなく、親ページURLであることを確認してください。

Q2: ウェブサイトがカスタムJavaScriptコールバックを使用している場合どうなりますか？
A2: コールバック関数名（例: onCaptchaResolved）を特定し、Playwright経由で実行してください: await page.evaluate("onCaptchaResolved(token)", token)。

Q3: ImageToText認識率を向上させるにはどうすればいいですか？
A3: 特定のmoduleパラメータ（数字のCAPTCHAの場合number）を使用し、抽出されたBase64画像が明確で高解像度であることを確認してください。

Q4: APIキーのセキュリティをどう確保すればいいですか？
A4: APIキーをハードコードしないでください。os.getenv("CAPSOLVER_API_KEY")などの環境変数を使用して安全に読み込みます。

Q5: リトライメカニズムを実装すべきですか？
A5: はい、capsolver.solve()に一時的なネットワークやサービスの問題に対処するための指数バックオフリトライを実装するにはtenacityなどのライブラリを使用してください。

Q6: トークンの有効期限はどのくらいですか？
A6: CAPTCHAトークンはすぐに期限切れになります（例: 2分）。CapSolverからトークンを取得した後、すぐに挿入し、送信してください。

Q7: Skyvernは異なるCAPTCHAタイプを自動的にルーティングできますか？
A7: はい、Skyvernのビジョン機能を使用して最初にCAPTCHAタイプを識別し、適切なCapSolverペイロードを動的に構築できます（例: ReCaptchaV2TaskProxyLessとImageToTextTaskの切り替え）。

Q8: Skyvernのビジョンは他にどのような役に立ちますか？
A8: 動的な要素の場所の特定（固定IDなしでCAPTCHAを検出）、送信後の視覚的検証（成功メッセージの確認）、スマートリトライのための視覚的エラー検出を可能にします。