
Sora Fujimoto
AI Solutions Architect
発行済み Nov 19, 2026
更新されました Nov 19, 2026 · 最小読み取り

ImageToTextTask を使ってローカル画像 CAPTCHA を読み取ります。このタスクは createTask から直接認識結果を返します。errorId の両方を確認し、利用する前に solution.text を検証します。CAPTCHA ソルバーは、認可されたワークフロー内で、サポートされているチャレンジをサーバー側で処理するステップを Laravel アプリケーションに提供します。Laravel は PHP の Web アプリケーションフレームワークであり、アプリケーションコード、コンソールコマンド、バックグラウンド処理を実行できます。HTTP クライアントは API リクエストを送信しますが、ブラウザページをレンダリングしたり、CAPTCHA ウィジェットを操作したりはしません。
たとえば、社内オペレーションツールが、承認済みの書類取得タスク中に画像チャレンジを受け取る場合があります。アプリケーションはその画像をソルバーへ送信し、返却されたテキストを確認したうえで、その回答を既存ワークフロー内の該当ステップへ渡します。セッション管理、結果のバリデーション、処理を継続するかどうかの判断は、引き続きアプリケーション側が保持します。
本ガイドでは、Laravel 標準の HTTP クライアントと CapSolver を使用します。例では、保有しているローカルのテスト画像のみを認識対象とし、より大きなアプリケーションへ接続する前に、リクエストと結果を簡単に確認できるようにしています。これは、自身のフォームに CAPTCHA 保護を導入するためのガイドではありません。
動作中の Laravel アプリケーション、残高のある CapSolver アカウント、そして自分が所有するか処理する権限を持つローカルの PNG または JPEG 画像を用意します。以下のコマンド用に、その画像を storage/app/fixture.png に配置してください。自分で答えを確認できる、シンプルなテキスト画像を選びましょう。
コマンドは Laravel プロジェクトのルートで実行します。統合にはフレームワークの HTTP クライアントを利用するので、別途ソルバー用 SDK を入れる必要はありません。PHP は API へ検証済み HTTPS 接続を確立できる必要があります。
ここで使用するタスクは ImageToTextTask です。その body には、data-URI プレフィックスを含まない、画像の Base64 データを格納します。common モジュールは認識したテキストを返します。非同期タスクフローとは異なり、この認識タスクは createTask レスポンスの中で結果を返します。この例では getTaskResult をポーリングしません。
API キーはアプリケーションの環境変数に保存し、設定ファイルを通じて公開します。サーバー上の .env に次のエントリを追加し、ローカルでプレースホルダを置き換えてください。
CAPSOLVER_API_KEY=YOUR_CAPSOLVER_API_KEY
config/capsolver.php を作成します。
<?php
return ['api_key' => env('CAPSOLVER_API_KEY')];
コマンドは config('capsolver.api_key') を読み取ります。Laravel の 設定に関するガイドでは、特に設定がキャッシュされる場合に、環境変数の値を設定ファイルに置くべき理由を説明しています。デプロイ時に設定キャッシュを利用している場合は、キー変更後に通常のデプロイプロセスに従ってキャッシュを再構築してください。
.env をバージョン管理に含めず、キーをフロントエンドの JavaScript に渡さないでください。送信リクエストボディのログ出力も避けてください。clientKey フィールドは認証情報であり、画像フィールドには一般的なアプリケーションログに残したくないデータが含まれる可能性があります。
以下のクロージャコマンドを routes/console.php に追加し、そのファイルに既にある他のコマンドは残しておきます。Laravel は クロージャベースの Artisan コマンドをサポートしており、最初の統合を、直接実行・確認しやすい小さな単位に保てます。
このコマンドはローカル入力を検証し、1 回のリクエストを送り、レスポンスチェックを通過した後にのみ、空でないテキスト結果を出力します。PNG/JPEG の制限やタイムアウト値は、あくまでサンプルアプリケーションとしての選択であり、ベンダー側制限の完全な一覧ではありません。
<?php
use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\Http;
use Illuminate\Http\Client\ConnectionException;
Artisan::command('captcha:read {path}', function () {
$key = config('capsolver.api_key');
$path = $this->argument('path');
if (! is_string($key) || $key === '') {
$this->error('Set CAPSOLVER_API_KEY on the server.');
return 1;
}
if (! is_file($path) || ! is_readable($path)) {
$this->error('Supply a readable local image file.');
return 1;
}
if (! in_array(mime_content_type($path), ['image/png', 'image/jpeg'], true)) {
$this->error('This example accepts PNG and JPEG files.');
return 1;
}
$image = file_get_contents($path);
if ($image === false) {
$this->error('Could not read the image.');
return 1;
}
try {
$response = Http::acceptJson()->connectTimeout(10)->timeout(60)
->post('https://api.capsolver.com/createTask', [
'clientKey' => $key,
'task' => [
'type' => 'ImageToTextTask',
'module' => 'common',
'body' => base64_encode($image),
],
]);
} catch (ConnectionException $exception) {
$this->error('Connection failed or timed out. Check before resubmitting.');
return 1;
}
if (! $response->successful()) {
$this->error('Solver HTTP error: '.$response->status());
return 1;
}
$data = $response->json();
if (! is_array($data) || ($data['errorId'] ?? null) !== 0) {
$this->error('Solver API error: '.($data['errorCode'] ?? 'INVALID_RESPONSE'));
return 1;
}
$text = $data['solution']['text'] ?? null;
if (($data['status'] ?? null) !== 'ready' || ! is_string($text) || $text === '') {
$this->error('No ready text result was returned.');
return 1;
}
$this->line($text);
return 0;
})->purpose('Read an authorized image CAPTCHA with the solver API');
HTTP ステータスチェックが重要なのは、Laravel がすべての HTTP エラーレスポンスに対して自動的に例外を投げるわけではないためです。API レベルのチェックは別物です。HTTP レスポンスが成功していても、期待される errorId、タスクステータス、結果フィールドが含まれている必要があります。
このコマンドは、タスク作成の自動リトライをあえて行いません。接続タイムアウトが発生すると、サービス側が元のリクエストを受信したかどうか判断できない場合があります。特に、この処理を独自のリトライポリシーを持つキュージョブに移行する際は、再送前に失敗内容を確認してください。
CapSolver ボーナスコードを利用する
自動化用の予算をすぐに増やしましょう。
入金時にボーナスコード CAP26 を利用すると、チャージごとに 5% のボーナス が無制限に付与されます。
今すぐ CapSolver ダッシュボード から引き換えましょう。
ローカルのフィクスチャ画像に対してコマンドを 1 回実行します。
php artisan captcha:read storage/app/fixture.png
画像に 583729 が含まれている場合、期待される出力は次のとおりです。
583729
返ってきたテキストと実際の画像を比較し、大文字・小文字や判別が難しい文字も確認してください。空でない文字列が返ってきたことは、リクエストが結果を生成したことを示しますが、将来のすべての画像での精度を保証するものではありません。このステップを許可されたアプリケーションワークフローに接続する際は、別途、送信先の受け入れレスポンスを検証に用いてください。
PHP が証明書ファイルやトラストストアに関するエラーを報告した場合は、リトライ前に、そのランタイムで設定されている CA バンドルを修正してください。TLS 証明書検証は有効のまま保ちます。このコマンドの接続エラーメッセージは意図的に簡潔にしてあります。資格情報やリクエストボディを出力せずに、インフラ側の診断で詳細を調査してください。
入力失敗、通信失敗、API エラー、後続処理での拒否は、それぞれ異なる結果として扱ってください。これにより、存在しないファイルが有料 API リトライになってしまうことを防ぎ、アプリケーション側のバリデーションエラーがソルバーのダウンタイムとしてカウントされることも防げます。
| 結果 | 次のアクション |
|---|---|
| API キーが不足している | リクエスト実行前にサーバー設定を修正する |
| ファイルがない、またはこの例で非対応 | 入力を修正する。ソルバーへのリクエストは不要 |
| 接続失敗またはタイムアウト | ネットワークや TLS 設定を確認し、再送前に状況を確認 |
| HTTP または API エラー | ステータスやエラーコードを記録し、該当 API ガイダンスに従う |
| テキストが返ってきた | 画像と比較し、次のアプリケーションステップを検証する |
コマンドをキュージョブに適用する際は、シリアライズされたジョブペイロードにシークレットを含めず、実行時に設定から読み出してください。ジョブのリトライ動作は明示的に定義します。結果が受理されたと確証できない場合は、呼び出し元ワークフローに未解決の結果として返してください。
より広範な運用トラブルシューティングについては、動的 DNS プロキシエラーの解説 を参照してください。これは別のセッション関連の失敗例です。この例はプロキシの一貫性に関するものであり、画像認識の話ではありません。このコマンドに対して、そのタスクパラメータを適用しないでください。
実際に直面しているチャレンジに基づいてタスクを選択し、すべての CAPTCHA を画像認識エンドポイントへ送るようなことはしないでください。画像からテキストへの結果は文字列であり、reCAPTCHA や Turnstile の統合で期待されるトークンの代わりにはなりません。
サポートされている API タスクタイプ を使って、該当するコントラクトを特定してください。ブラウザ実行、ウィジェットパラメータ、送信先へのサブミットは、いずれも別個の責任領域です。まずは小さな画像ワークフローを完成させ、その後でアプリケーションが必要とする、特定のサポート対象タスクを構築・テストしましょう。
Laravel 標準の HTTP クライアントだけで、小さく検証しやすいソルバー統合は十分実現できます。リクエストはサーバー側にとどめ、ドキュメントどおりのタスクスキーマを使い、結果と次のアプリケーションステップの両方を検証してください。CapSolver は、アプリケーション全体を乗っ取ることなく、認可されたワークフローの CAPTCHA ステップに組み込むことができます。
Q: Laravel 用の CAPTCHA ソルバーパッケージは必要ですか?
いいえ。この例では Laravel 標準の HTTP クライアントを使って、API を直接呼び出しています。別のラッパーは任意であり、利用前に必ず最新のタスク契約と整合しているか確認してください。
Q: これで Laravel のログインフォームに CAPTCHA 保護が追加されますか?
いいえ。このコマンドはソルバー API を通じて、権限のある画像チャレンジを認識するものです。自分のフォームに CAPTCHA 保護を追加することは、CAPTCHA プロバイダの検証サービスとの別の統合になります。
Q: この例では getTaskResult をポーリングする必要がありますか?
いいえ。ImageToTextTask は認識結果を createTask から直接返します。別のタスクタイプでは異なる結果フローを取る場合があるため、選択したタスクのドキュメントに従ってください。
Q: このコードは、そのままで reCAPTCHA や Turnstile を解くことができますか?
いいえ。このコードは ImageToTextTask を送り、テキストを期待しています。reCAPTCHA や Turnstile は、異なるタスクパラメータとトークン結果を利用します。タスク名だけを変更しても不十分です。
Q: タイムアウト後に自動リトライすべきですか?
同じタスクをむやみに再作成しないでください。タイムアウトは、リクエストがサービスに到達した後でも発生し得ます。自動リトライを追加する前に、失敗を確認し、上限付きのリトライポリシーを定義してください。

Sora Fujimoto
AI Solutions Architect
Connecting agents, browsers, and APIs into one workflow.
著者について
制御された画像テスト、実際のAPI結果、およびフォーム受理チェックを用いて、ヘッドレスとヘッド付きのCAPTCHAワークフローを比較します。結果が何を証明しているのかを学びましょう。

CAPTCHAソルバーをNodeのタスクとしてCypressに追加し、APIキーはブラウザ側のコードに含めないように保持し、テスト済みのJavaScriptサンプルを使って所有する画像CAPTCHAフォームを検証します。
