CAPTCHAを解くAPIのJavaScriptでの実装方法

TL;DR

• CapSolverはシンプルなREST APIを提供しています。CAPTCHAを送信するには/createTaskを呼び出し、status === 'ready'になるまで/getTaskResultをポーリングします。
• 本ガイドでサポートされるチャレンジタイプ: reCAPTCHA v2, reCAPTCHA v3, および Cloudflare Turnstile。
• APIキーは.envに保存してください。ハードコードしないでください。
• リリース準備のNode.js統合にはaxios + ポーリングループを使用してください。
• 長時間実行されるオートメーションジョブで耐障害性を高めるために、再試行ロジックと指数バックオフを追加してください。

イントロダクション

現代のウェブオートメーションやデータ収集プロジェクトでは、ワークフローを妨げるCAPTCHAチャレンジに遭遇することがよくあります。ウェブスクリーパーの構築、ブラウザタスクの自動化、AIエージェントの開発など、さまざまなシナリオで、信頼性の高いCAPTCHA解決ソリューションの統合が不可欠になります。CapSolverは、これらのチャレンジをプログラムで処理するAI駆動のAPIを提供し、このガイドではJavaScriptで実装する方法をステップバイステップで説明します。

自動化トラフィックは現在、インターネットトラフィックのほぼ半分を占めており、ボット検出とCAPTCHAチャレンジはウェブアプリケーションでますます一般的になっています。正当なオートメーションワークフローを構築する開発者にとって、信頼性の高いプログラム可能なソリューションを持つことはもはやオプションではなく、コアインフラストラクチャの要件となっています。

CapSolver APIワークフローの理解

コードに進む前に、CapSolverがCAPTCHAリクエストを処理する方法を理解しておくことが、適切な統合を構築するための鍵になります。ワークフローは単純なパターンに従います: タスクを送信し、完了をポーリングし、解決策を取得します。

CAPTCHAチャレンジをCapSolverに送信すると、システムは一意のタスクIDを割り当てます。その後、アプリケーションは定期的にサービスにポーリングし、解決策が準備できるまで待ちます。解決が完了すると、ワークフローを続行するために必要なトークンやデータを含むレスポンスを受け取ります。

CapSolverはreCAPTCHA v2/v3、Cloudflare Turnstile、画像からテキストへのチャレンジなど、さまざまなCAPTCHAタイプをサポートしています。APIワークフローはチャレンジタイプによって一貫していますが、タスクパラメータは必要な特定の解決策に応じて異なります。サポートされるタスクタイプの完全な一覧については、CapSolverタスクタイプリファレンスを参照してください。プラットフォームに慣れていない場合は、Getting Startedガイドでアカウントのセットアップと最初のAPIコールについて説明しています。CapSolverが実際のスクリーピングパイプラインにどのように適合するかの概要については、CapSolverをオートメーションワークフローに統合する方法を参照してください。

プロジェクトのセットアップ

このガイドでは、JavaScriptおよびNode.jsプロジェクトに特化したCapSolverのCAPTCHA解決APIの実装について説明します。Node.js 18+がインストールされていることを確認し、アカウントダッシュボードからCapSolver APIキーを用意してください。

プロジェクト構造:

capsolver-integration/
├── .env                 # 環境変数
├── capsolver-client.js  # コアAPIクライアント
├── index.js             # 使用例
└── package.json

プロジェクトを初期化し、依存関係をインストールしてください:

mkdir capsolver-integration
cd capsolver-integration
npm init -y
npm install axios dotenv

axiosは、Node.jsで広く使用されているHTTPクライアントで、クリーンなプロミスベースの構文とビルトインのタイムアウト処理を提供します—これらは外部APIのポーリング時に役立ちます。

APIキーを安全に保存するための.envファイルを作成してください:

CAPSOLVER_API_KEY=your-api-key-here

セキュリティの注意: .envファイルをバージョン管理にコミットしないでください。すぐに.gitignoreに追加してください。公開されたAPIキーは、不正利用や予期せぬ料金の原因になります。オートメーションプロジェクトでの資格情報の取り扱いに関するベストプラクティスについては、OWASP Secrets Managementを参照してください。

コアAPIクライアントの作成

統合の基盤となる再利用可能なクライアントは、認証とリクエストフォーマットを処理します。このクライアントはAPIエンドポイントをカプセル化し、各操作用のメソッドを提供します。これをcapsolver-client.jsとして保存してください:

// capsolver-client.js
const axios = require('axios');

class CapSolverClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.capsolver.com';
  }

  async request(endpoint, data) {
    const response = await axios.post(`${this.baseUrl}${endpoint}`, {
      ...data,
      clientKey: this.apiKey
    }, {
      headers: { 'Content-Type': 'application/json' },
      timeout: 30000
    });
    return response.data;
  }

  delay(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

module.exports = CapSolverClient;

注意: このガイドのコード例は、CapSolverのドキュメント化されたAPI構造に基づいた実装パターンを示しています。エンドポイントのパス、タスクタイプ名、リクエスト/レスポンスフォーマットの最新情報を公式CapSolver APIドキュメントで確認してください。これらの詳細は変更される可能性があります。

このクライアントは、API通信の繰り返し処理を処理し、ヘッダーの設定やクライアントキーを含むリクエストボディのフォーマットを担当します。

アカウント残高の確認

大規模なCAPTCHA解決を行う前に、アカウントに十分なクレジットがあることを確認してください。CapSolverは成功した解決ごとに課金するモデルを採用しているため、残高の確認はワークフローの途中で予期せぬ失敗を防ぐために重要です。

// CapSolverClientクラスに追加
async getBalance() {
  const result = await this.request('/getBalance', {});

  if (result.errorCode) {
    throw new Error(`残高チェックに失敗: ${result.errorCode} - ${result.errorDescription}`);
  }

  return {
    balance: result.balance,
    currency: result.currency || 'USD'
  };
}

多くの開発者は、長時間のオートメーション実行が始まる前にクレジットが尽きているかどうかを確認するために、初期化シーケンスに残高チェックを組み込みます。

reCAPTCHA v2の解決

reCAPTCHA v2は、チェックボックスチャレンジや画像選択タスクのようなよく知られたチャレンジを提示します。これを解決するには、ターゲットページのURLと、ページのHTMLに埋め込まれたサイトキーが必要です。解決されたトークンは、フォームやリクエストに送信されます。

// CapSolverClientクラスに追加
async solveReCaptchaV2(websiteUrl, websiteKey) {
  const task = {
    type: 'RecaptchaV2Task',
    websiteURL: websiteUrl,
    websiteKey: websiteKey
  };
  return await this.submitAndWait(task);
}

async submitAndWait(task) {
  // ステップ1: タスクを送信
  const submitResult = await this.request('/createTask', { task });

  if (submitResult.errorCode) {
    throw new Error(`タスク作成に失敗: ${submitResult.errorCode}`);
  }

  const taskId = submitResult.taskId;

  // ステップ2: 結果をポーリング
  while (true) {
    await this.delay(1500);

    const result = await this.request('/getTaskResult', { taskId });

    if (result.status === 'ready') {
      return result.solution;
    }

    if (result.status === 'failed') {
      throw new Error(`解決に失敗: ${result.errorDescription || '不明なエラー'}`);
    }
    // status === 'processing' → 続けてポーリング
  }
}

1.5秒のポーリング間隔は、応答性とAPIレートリミットのバランスを取っています。statusフィールドはタスクが実行中の間はprocessing、解決策が利用可能になるとready、チャレンジが解決できなかった場合はfailedになります。完全なレスポンススキーマについては、getTaskResult APIリファレンスを参照してください。

reCAPTCHA v3の解決

reCAPTCHA v3は、背景で非表示で動作し、視覚的なチャレンジを提示する代わりにリスクスコアを返します。CapSolverはv3チャレンジを解決できますが、ターゲットサイトが要求する最小スコアしきい値を指定することも可能です。

// CapSolverClientクラスに追加
async solveReCaptchaV3(websiteUrl, websiteKey, options = {}) {
  const {
    pageAction = 'verify',
    minScore = 0.9
  } = options;

  const task = {
    type: 'RecaptchaV3Task',
    websiteURL: websiteUrl,
    websiteKey: websiteKey,
    pageAction: pageAction,
    minScore: minScore
  };

  return await this.submitAndWait(task);
}

reCAPTCHA v3タスクは、視覚的なチャレンジにインタラクションする必要がないため、v2タスクよりも通常は速く完了します。pageActionパラメータは、ターゲットページで定義されたアクション文字列と一致する必要があります。

Cloudflare Turnstileの解決

Cloudflare Turnstileチャレンジは、特にCloudflareで保護されたサイトをスクリーピングする際のオートメーションワークフローで頻繁に現れます。CapSolverはこれらのチャレンジを専用でサポートしています:

// CapSolverClientクラスに追加
async solveTurnstile(websiteUrl, websiteKey, options = {}) {
  const {
    pageAction = 'managed',
    metadata = {}
  } = options;

  const task = {
    type: 'AntiCloudflareTask',
    websiteURL: websiteUrl,
    websiteKey: websiteKey,
    pageAction: pageAction,
    metadata: metadata
  };

  return await this.submitAndWait(task);
}

より高度なCloudflareシナリオ—チャレンジページやブラウザのファイントプリントのシミュレーション—については、ヘッドレスブラウザでのCAPTCHA解決の自動化のガイドを参照してください。

完全な構成

以下は、実際のオートメーションシナリオでクライアントを使用する方法を示す完全なindex.jsです:

// index.js
const CapSolverClient = require('./capsolver-client');
require('dotenv').config();

async function main() {
  const client = new CapSolverClient(process.env.CAPSOLVER_API_KEY);

  try {
    // 実行前に残高を確認
    const { balance, currency } = await client.getBalance();
    console.log(`アカウント残高: ${balance} ${currency}`);

    if (balance < 0.01) {
      throw new Error('残高不足。CapSolverアカウントにチャージしてください。');
    }

    // 例: reCAPTCHA v2を解決
    const solution = await client.solveReCaptchaV2(
      'https://example.com/login',
      '6Le-wvkAAAAAATBQbZDLjMjqTLV92vP6EXjs'
    );

    console.log('CAPTCHAは正常に解決されました');
    console.log('トークン:', solution.gRecaptchaResponse);

    // トークンをオートメーションワークフローに挿入
    // await page.evaluate(token => {
    //   document.getElementById('g-recaptcha-response').value = token;
    // }, solution.gRecaptchaResponse);

  } catch (error) {
    console.error('エラー:', error.message);
    process.exit(1);
  }
}

main();

エラーハンドリングとリトライ

プロダクション統合には堅牢なエラーハンドリングが必要です。ネットワーク問題、一時的なAPIダウンタイム、CAPTCHAの失敗などは発生する可能性があるため、リトライロジックを実装することで信頼性が大幅に向上します:

async function withRetry(operation, maxAttempts = 3, delayMs = 2000) {
  let lastError;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await operation();
    } catch (error) {
      lastError = error;
      console.warn(`試行 ${attempt}/${maxAttempts} が失敗しました: ${error.message}`);

      if (attempt < maxAttempts) {
        await new Promise(resolve => setTimeout(resolve, delayMs * attempt));
      }
    }
  }

  throw lastError;
}

// 使用例
const solution = await withRetry(() =>
  client.solveReCaptchaV2('https://example.com', 'your-site-key')
);

指数バックオフ(delayMs * attempt)により、一時的な障害中にAPIを過度に負荷しないようにし、サービスが復元する時間を確保します。

JavaScript統合のベストプラクティス

APIキーを安全に保つ。 常に環境変数から資格情報を読み込み、ハードコードしないでください。ローカルでは.envファイルを使用し、CI/CDパイプラインでは適切なシークレット管理を実施してください。

タスクタイムアウトを設定する。 タスクがスタックした場合にオートメーションが無限に待機しないように、最大ポーリング期間を追加してください。ほとんどの解決シナリオをカバーするため、タイムアウトは120秒が適切です。

残高をプログラムでモニタリングする。 長時間実行されるオートメーションジョブでは、起動時に残高を確認し、必要に応じて定期的に確認してください。これにより、実行中に静かに失敗するのを防げます。

タスクタイプとチャレンジを一致させる。 間違ったタスクタイプを使用することは、失敗の一般的な原因です。タスクを送信する前に、ターゲットページのHTMLを確認し、正しいサイトキーを抽出してください。

レートリミットを尊重する。 あなたのワークフローが結果を処理できる速度より速くタスクを送信しないでください。タスクをキューイングし、制御された速度で処理することで、より安定したスループットが得られます。

CAPTCHA解決をスクリーピングパイプラインに統合するための広範な視点については、CapSolverをオートメーションまたはスクリーピングワークフローに統合する方法を参照してください。PuppeteerやPlaywrightを含む追加のパターンについてもカバーしています。プロジェクトがヘッドレスブラウザを特に関与する場合、ヘッドレスブラウザでのCAPTCHA解決の自動化がエンドツーエンドのセットアップを説明しています。

FAQ

Q: CapSolver APIを使用するにはプロキシが必要ですか？
A: 必要ありません。ほとんどのタスクタイプでは、CapSolverが独自のインフラストラクチャで解決を行います。ターゲットURLとサイトキーのみを渡す必要があります。プロキシ設定はオプションで、特定のIPからブラウザセッションをシミュレートする必要があるタスクのバリアントのみで必要です。詳細についてはプロキシ使用ガイドを参照してください。

Q: CAPTCHAの解決にはどのくらい時間がかかりますか？
A: 解決時間はチャレンジタイプによって異なります。reCAPTCHA v3は通常5秒未満で解決します。reCAPTCHA v2やCloudflare Turnstileは、チャレンジの難易度や現在のキュー負荷によって10〜30秒かかることがあります。このガイドのポーリングループは、変動する解決時間を自動的に処理します。

Q: 実行中に残高が尽きてしまった場合、どうなりますか？
A: 次の/createTaskコールでエラーコードが返されます。このガイドのクライアントはその場合にエラーをスローします。これは、アラートを送信するか、ジョブを一時停止するなどの処理でキャッチできます。起動時に残高を確認する（ガイドに示されているように）ことが、この問題を防ぐ最も簡単な方法です。

Q: このクライアントをブラウザ（フロントエンドJavaScript）で使用できますか？
A: できません。APIキーはサーバーサイドでなければなりません。フロントエンドコードに公開すると、誰でもあなたのクレジットを使用できるようになります。常にNode.jsバックエンド、サーバーレス関数、または他のサーバーサイド環境からCapSolver APIを呼び出してください。

Q: タスクがfailedを返した場合、どうすればよいですか？
A: failedステータスは通常、チャレンジパラメータが正しくないことを意味します（間違ったサイトキー、タスクタイプの不一致、またはサポートされていないページ設定）。レスポンスのerrorDescriptionフィールドを確認し、タスクパラメータをタスクタイプドキュメントと照合し、修正された値で再試行してください。また、CapSolver FAQで一般的なエラーパターンを確認することもできます。

Q: 本格的なJavaScript/Node.js SDKはありますか？
A: CapSolverは複数の言語用の公式SDKを提供しています。JavaScriptプロジェクトの場合、このガイドのパターンを直接使用できます。または、CapSolver GitHubで公開されているnpmパッケージやコードサンプルを確認することもできます。

次のステップ

この実装により、JavaScriptの自動化プロジェクトにCAPTCHA解決機能を追加するための堅牢な基盤が得られます。このクライアントを拡張して、追加のタスクタイプを追加したり、PuppeteerやPlaywrightなどのブラウザ自動化ツールに統合したり、AIスクリーピングワークフローと組み合わせて、より高度なデータ抽出パイプラインを作成することもできます。

他のチャレンジタイプやその特定のパラメータについては、公式タスクタイプドキュメントを参照してください。

今日からCapSolverでJavaScriptプロジェクトでCAPTCHAを解決し始めましょう。アカウントを作成し、APIキーを取得し、上のクライアントコードをあなたの次の自動化プロジェクトに配置してください。