画像CAPTCHAソルバーのNode.jsでの作成: ステップバイステップガイド

TL;DR

• イメージCAPTCHAソルバーは画像のバイトを受けて認識された文字を返します。reCAPTCHAトークンではなくなります。
• Node.jsでは、画像をBufferに読み込み、それをBase64にエンコードしてImageToTextTaskリクエストにします。
• 文書化された画像認識フローはcreateTaskからsolution.textを返します。この例ではポーリングは行われません。
• 解決用のAPIキーはサーバーに保持し、所有しているまたはテストに許可された画像を使用してください。
• 下記のNode.jsアダプターはモックされた応答でテストされています。本番の解決と実際のフォームによる承認には、環境で検証が必要です。

画像CAPTCHA統合は、全体の実装に影響を与える区別から始まります。入力は画像ファイルであり、有用な出力はテキストです。Node.jsのテストランナーが歪んだ文字を含むフォームに遭遇した場合、その特定の試行に必要な文字が必要です。トークンを対象とするreCAPTCHAの例は別のタスクを扱います。

このガイドでは、文書化されたCapSolverの画像認識リクエストと、ファイルがリクエストボディになる方法、および答えが現れる場所を示す小さなNode.jsアダプターを使用します。この例では所有しているテストフォームとローカルに保存できる画像を前提としています。ブラウザのナビゲーションとアプリケーション固有のフォーム送信は、テストランナーの一部です。

画像CAPTCHAソルバーはどのような情報を返しますか？

画像CAPTCHAソルバーは、送信された画像で認識された文字を返します。CAPTCHA用語集では広い文脈が説明されていますが、この実装ではインタラクティブなウィジェットではなくテキスト画像に焦点を当てます。

公式のImageToTextTaskドキュメントでは、タイプ、body内のBase64画像、認識モジュールを含むタスクが定義されています。成功したリクエストはsolution.textで認識されたテキストを公開します。このフローでは、初期のcreateTaskリクエストに結果が含まれます。

例をフォームに接続する際には、次の値を別々に保持してください：

認識結果は中間結果です。チャレンジが変更された、セッションが期限切れになった、または答えが別の画像に属する場合、アプリケーションは答えを拒否する可能性があります。

ステップ1: Node.jsと所有しているテスト画像を準備する

fetchとAbortSignal.timeoutを組み込みで使用するNode.jsバージョンを使用してください。アダプターはNode.js 24.16.0でテストされています。npm依存は必要ありません。以下の2つのJavaScriptファイルを1つのディレクトリに保存し、それらの隣に非機密のテスト画像を配置してください。

この例では./captcha.pngを読み込みます。これは画像URLやエンコードされた文字列ではなく、ローカルパスです。APIコールのデバッグを行う前にファイルを確認してください。PNG拡張子で保存されたHTMLエラーページは依然としてHTMLページです。サービスがサポートする有効な画像を使用してください。

CapSolverアカウントから解決用APIキーを取得し、環境またはシークレットマネージャーを通じてCAPSOLVER_API_KEYとしてプロセスに公開してください。この資格情報はブラウザJavaScriptやソースコード管理から除外してください。管理用の公開またはMCP資格情報は解決用APIキーの代用にはなりません。

画像に関連するフォームセッションを保持してください。フォームが新しいチャレンジを生成するたびに新しい画像を保存してください。他のリクエストが以前のフォームを使用している間に共有されたファイル名を上書きすると、間違った試行に対して有効な認識応答が生成される可能性があります。並行した試行には別々のファイルを保持するか、それらのバイトを別々に保持してください。

ステップ2: 画像バイトをBase64にエンコードする

画像をバイナリデータとして読み込み、結果のBufferをエンコードしてください。NodeのファイルシステムドキュメントではreadFileが説明されており、BufferドキュメントではBase64エンコードが定義されています。

以下のキーエクスプレッションはimage.toString('base64')です。最初にファイルをUTF-8で読み込まないでください。画像バイトはテキストドキュメントではありません。task.bodyとしてファイル名を送信しないでください。リモートサービスはあなたのコンピュータ上のパスではなく、エンコードされたコンテンツが必要です。

data:image/png;base64,のプレフィックスなしでローカルのBase64を送信してください。データURLはブラウザで役立ちますが、認識ドキュメントに表示されているタスクボディとは異なります。Bufferからエンコードを生成することで、関係のないプレフィックスや改行をコピーする必要がありません。

この例では空のファイルを拒否します。画像形式、寸法、視覚的な品質の検証は行われません。アプリケーションが任意のアップロードを受信する場合、この関数の前に検証してください。成功した読み込みはバイトが利用可能であることを示すだけで、それ以上ではありません。

ステップ3: ImageToTextTaskリクエストを送信する

このアダプターをrecognize-image.mjsとして保存してください。エンドポイントとタスクのフィールドは公式ドキュメントに従います。ファイルの読み込み、タイムアウト、および応答チェックはこの例の追加です。アダプターはモックされた応答で実行されました。実際のサービスに対して使用するには、あなたの解決キーが必要であり、これはライブ検証ステップです。

import { readFile } from 'node:fs/promises';

// 要求フィールドは公式のImageToTextTaskドキュメントに従います。
export async function recognizeImage(path, apiKey, request = fetch) {
  if (!apiKey) throw new Error('Set CAPSOLVER_API_KEY first.');
  const image = await readFile(path);
  if (!image.length) throw new Error('The image file is empty.');

  const response = await request('https://api.capsolver.com/createTask', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    signal: AbortSignal.timeout(60000),
    body: JSON.stringify({
      clientKey: apiKey,
      task: {
        type: 'ImageToTextTask',
        module: 'common',
        body: image.toString('base64')
      }
    })
  });
  if (!response.ok) throw new Error('HTTP status ' + response.status);
  const result = await response.json();
  if (result.errorId !== 0) {
    throw new Error(result.errorCode || 'Image recognition failed.');
  }
  if (result.status !== 'ready' ||
      typeof result.solution?.text !== 'string' ||
      !result.solution.text.length) {
    throw new Error('The API did not return recognized text.');
  }
  return result.solution.text;
}

この関数はパスとAPIキーを受け取り、認識されたテキストを返します。3番目の引数はテストでfetchを置き換えるために使用されます。通常の呼び出しでは省略してください。60秒のタイムアウトはローカル設定であり、認識時間やサービス制限ではありません。

応答チェックは要求の各段階に従います。失敗したHTTPステータスはパース前に失敗します。無効なJSONはパースエラーを生成します。プロバイダーのエラーはerrorIdで処理されます。成功した見かけのエンベロープは、空でないテキストを含む準備ができている結果である必要があります。これにより、空のフォーム値として静かに見過ごされる可能性が防がれます。

自動的なリトライは行われません。送信失敗後、クライアントはサービスが元のタスクを受信したかどうかを知らない可能性があります。リトライを追加する前に、この不確実性をどう処理するかを決定してください。

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

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

ステップ4: アダプターを実行し、テキストを使用する

アダプターの隣にrun.mjsとして次のエントリポイントを保存してください。ライブリクエストには独自の解決キーが必要です。ローカルアダプターのテストではライブ解決は完了していません：

import { recognizeImage } from './recognize-image.mjs';

try {
  const path = process.argv[2];
  if (!path) throw new Error('Usage: node run.mjs ./captcha.png');
  const text = await recognizeImage(path, process.env.CAPSOLVER_API_KEY);
  console.log(text); // この例では、非機密の所有テスト画像のみを使用してください。
} catch (error) {
  console.error(error.message);
  process.exitCode = 1;
}

解決キーが環境に存在する場合、以下のコマンドを実行してください。このガイドではライブ呼び出しは行われていません：

node run.mjs ./captcha.png

成功した呼び出しは返されたテキストを出力します。答えはあなたの画像に依存し、ライブコールには固定された期待値はありません。このターミナル例では非機密の所有fixtureを使用し、共有アプリケーションのログでチャレンジの答えを出力しないでください。

テストランナーではrecognizeImageを呼び出し、その戻り値を同じ画像に関連する答えフィールドに送信してください。セレクターと送信方法はあなたのアプリケーションに属するため、ここでは作成されません。送信後の実際のフォームの結果をアサートしてください。例えば、期待されるテストレコードが受け入れられたことを確認してください。

認識された文字列を保持してください。フォームが正規化を明示的に定義していない限り、変換して大文字にしたり、スペースを削除したりしないでください。これはその意味を変える可能性があります。既知の文字セットは予期しない結果を識別するのに役立ちますが、検証は不安定な文字を静かに書き換えないでください。

どの認識モジュールを選択すべきですか？

サービスが説明する画像タスクに応じてモジュールを選択してください。このリクエストは明示的にcommonを使用します。専門的なモードを選択する前に、ImageToTextTaskドキュメントのモジュールの説明を参照してください。

モジュールは関係のない入力を修復できません。フォーム全体のスクリーンショット、古くなったチャレンジ、または関係のないテキストを含む画像は、設定に関係なく不適切な答えを生成する可能性があります。送信されたバイトが意図されたチャレンジとアクティブな試行に該当することを確認してください。

あなたのアプリケーションがいくつかの画像スタイルを生成する場合、それぞれのスタイルに代表的な所有サンプルを使用してください。あなたのfixtureからの期待される答えを認識された答えから分離してください。これにより、合成エンコードチェックを証拠として提示することなく、不一致を再現可能にします。

例えば、fixtureは正確なファイルバイトがBase64エンコードとデコード後に生存することをアサートできます。別の認識チェックでは、プロバイダーの答えがfixtureの既知の文字列と比較されます。3番目のテストでは、その答えがフォームを通じて送信されます。これらのテストは異なる質問に答え、それぞれ別の結果を報告する必要があります。

どの失敗を最初に調査すべきですか？

認識品質よりもローカル入力の失敗を最初に調査してください。読み込めないパス、空のファイル、または欠如したキーは、リクエストが正常に完了していないことを意味します。認識モジュールを変更してもこれらの失敗は解決できません。

リモートの失敗については、制御された診断記録にプロバイダーのエラーコードを保持し、公式APIエラー参照を参照してください。リクエストボディをダンプしないでください。これは資格情報と画像を含みます。失敗した段階とエラー識別子を記録してください。

NodeのグローバルAPIドキュメントは、ここでの要求と中止のプリミティブをカバーしています。ローカルの待機を終えることはリモート処理がキャンセルされたことを示しません。

問題を報告する際には、どの段階で失敗したかを説明してください。"ファイルの読み込みに失敗した"と"サービスがフォームによって拒否されたテキストを返した"は異なる証拠が必要です。資格情報や画像コンテンツは、制御されたサポートプロセスが明示的に必要としない限り、共有報告から除外してください。

本番のCAPTCHAを使用する前にテストされた内容は？

アダプターは、リクエストの構築とBase64の保持、欠如した資格情報、空の入力、HTTPの失敗、プロバイダーのエラー、結果の欠如、不正なまたは失敗した応答をカバーする7つのローカルテストケースで実行されました。一部のケースは関連するアサーションをグループ化しています。テストではfetchが置き換えられたため、有料サービスにはアクセスしていません。

画像のfixtureはエンコードをチェックし、答えは供給されたテスト値でした。これらのチェックはローカルJavaScriptの動作を確立します。これらは認識精度や実際のフォームによる承認を測定するものではありません。統合に信頼を置く前に、あなたの解決キーと現在の所有チャレンジでこれらのチェックを完了してください。

同じアプリケーション内のトークンタスクの場合、別のJavaScript CAPTCHA APIガイドを使用してください。画像認識はその独自のブランチに保つべきです。結果タイプと文書化された取得フローが異なるためです。CapSolverを試して、最終的な接続を検証してください。

FAQ

Q: npmパッケージが必要ですか？

アダプターは組み込みのNode.js APIを使用し、npmパッケージは必要ありません。互換性のあるランタイム、有効な画像、解決キーが必要です。ローカルテストではNode.js 24.16.0が使用されました。

Q: ImageToTextTaskはgetTaskResultを使用すべきですか？

文書化された認識フローはcreateTaskからsolution.textで準備ができている結果を返します。このアダプターはポーリングを行いません。別のCAPTCHAタスクからのポーリングループは自動的にコピーしないでください。

Q: Base64ではなく画像URLを送信できますか？

この文書化されたリクエストはbodyフィールドにエンコードされた画像コンテンツを使用します。所有している画像はあなたのアプリケーションを通じて取得し、そのバイトをエンコードしてください。ファイル名やURLはその値に等しくありません。

Q: なぜフォームが認識されたテキストを拒否する可能性があるのですか？

画像とセッションが同じ試行に属し、答えが変更されていないことを確認してください。返された文字列は認識の正確性やアプリケーションの承認を保証しません。

Q: ローカルテストは認識精度を証明していますか？

いいえ。アダプターの動作を検証するために供給された応答を使用しています。認識とエンドツーエンドの承認には、ライブサービスとあなたの所有フォームに対する別々のテストが必要です。