Skip to main content
本文では、ユーザーが入力した内容と hCaptcha の CAPTCHA 画像を通じて、クリックする必要のある小さな画像の座標を返す hCaptcha 画像認識 API の接続方法について説明します。

​
申請プロセス

hCaptcha 画像認識 API を使用するには、まず Ace Data Cloud コンソール にアクセスして API トークンを取得し、保管してください。 まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。 1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。 初回申請時には無料のクレジットが付与され、無料で体験できます。クレジットが不足した場合は、コンソール で一般残高をチャージできます。
📘 完全なドキュメント：hCaptcha 画像認識 API →

​
基本使用

まず、基本的な使用方法を理解します。これは、処理する hCaptcha CAPTCHA 画像を入力することで、処理結果を得ることができます。最初に queries フィールドを簡単に渡す必要があります。これは具体的な hCaptcha CAPTCHA 画像です。hCaptcha CAPTCHA を含むウェブサイトからこの CAPTCHA 画像をキャプチャする必要があります。サンプルウェブサイトのリンクは次のとおりです： https://democaptcha.com/demo-form-eng/hcaptcha.html。チェックボックスをクリックすると、具体的な完全な CAPTCHA 画像が表示されます。以下の図のように：

queries フィールドは上記の CAPTCHA 画像のスクリーンショットであり、画像サイズは100KBを超えないことをお勧めします。また、上の画像の赤い矢印が指す領域をキャプチャし、画像サイズを圧縮し、Base64 エンコードに変換する必要があります。以下の図のように：

さらに、CAPTCHA 画像に関連する認識内容パラメータ question を入力する必要があります。これは中英文の翻訳をサポートし、関連する認識内容を直接入力できます。上記のウェブページ画像の黄色い矢印が示す内容から、question に入力すべき内容は Please click on the UNIQUE object among the others. です。具体的な内容は以下の通りです：

ここで、リクエストヘッダーを設定しました。これには以下が含まれます：
  • accept：受け取りたいレスポンス結果の形式。ここでは application/json、つまり JSON 形式を記入します。
  • authorization：API を呼び出すためのキー。申請後、直接ドロップダウンから選択できます。
また、リクエストボディを設定しました。これには以下が含まれます：
  • queries：Base64 エンコードされた CAPTCHA 画像のリスト。
  • question：CAPTCHA 画像に関連する認識内容パラメータで、中英文を直接入力できます。
選択後、右側にも対応するコードが生成されていることがわかります。以下の図のように：

「Try」ボタンをクリックするとテストが実行され、上の図のように次のような結果が得られます：
返された結果には複数のフィールドがあり、以下のように説明されます：
  • solution、今回の hCaptcha CAPTCHA 画像タスク処理後の検証結果。
    • label、hCaptcha CAPTCHA 画像が認識した内容。
    • box、hCaptcha CAPTCHA 画像の認識結果の位置情報で、画像の座標情報で構成されています。
    • confidences、hCaptcha CAPTCHA 画像認識後に認識内容を満たす信頼度。
  • started_at、finished_at：今回のリクエストの処理開始と結果生成の時間、Unix タイムスタンプ（秒、浮動小数点）。
  • elapsed：今回の処理の総時間（秒）。
hCaptcha CAPTCHA 画像の検証結果を得たことがわかります。結果の box の位置座標情報に基づいて、その CAPTCHA 画像の該当領域をシミュレートクリックすることで検証を通過できます。 次に、結果の box の位置情報を使用してクリックする方法を説明します。まず、アップロードした CAPTCHA 画像に直角座標系を構築します。中心原点は画像の左下隅にあり、360 は横座標、276 は縦座標に対応します。CAPTCHA に対応する座標をシミュレートクリックするだけで済みます。具体的な画像情報は以下の図のように：

また、対応する接続コードを生成したい場合は、生成されたものを直接コピーできます。たとえば、CURL のコードは以下の通りです：
Python の接続コードは以下の通りです：

​
非同期モード（async）

デフォルトでは、API は同期ブロッキングです：1回のリクエストは、認識結果の処理が完了するまで待機します。複数のソルバーのローテーションを行っている場合、「タスクを提出した後、すぐに task_id を取得し、他のソルバーをスケジュールし、後で結果を読み取る」ことを希望する場合は、リクエストボディに async: true を渡すことができます。 async: true を渡すと、インターフェースは即座に task_id を返し、ブロックして待機することはありません：
進捗を確認するには、task_idを使用してPOST /captcha/tasksを照会できます（3〜5秒ごとに推奨）。このインターフェースはタスク処理をトリガーしたり進めたりしません。照会しなくても、ネットワークが切断されても、クライアントを終了しても、サーバーは処理を続けます：
処理中はstatus: processingが返されます：
処理が完了すると、status: readyと認識結果solution（フィールド構造は同期モードと完全に一致）を返します：
料金説明：非同期モードでは、タスクの作成と「処理中」状態の読み取りは課金されません；クライアントが初めて成功した結果を読み取ったときに1回課金されます（既存の動作および同期モードの価格と一致）。サーバーはタスクを自動的に進めますが、バックグラウンドで先に完了しても早期に課金されることはありません。タスクが120秒以内に成功しない場合は、HTTP 504 timeoutで終了し、課金されません。/captcha/tasksはタスクを進める責任はありません。

​
エラーハンドリング

APIを呼び出す際にエラーが発生した場合、APIは対応するエラーコードと情報を返します。例えば：
  • 400 token_mismatched：不正なリクエスト、パラメータが欠落または無効な可能性があります。
  • 400 api_not_implemented：不正なリクエスト、パラメータが欠落または無効な可能性があります。
  • 401 invalid_token：未承認、無効または欠落した認証トークン。
  • 429 too_many_requests：リクエストが多すぎます、レート制限を超えました。
  • 500 api_error：内部サーバーエラー、サーバーで何かがうまくいきませんでした。

​
エラー応答の例

​
結論

この文書を通じて、hCaptcha画像認識APIを使用してユーザーが認識した内容とhCaptchaのキャプチャ画像を入力し、最終的にクリックする必要のある小さな画像の座標を返して検証を完了する方法を理解しました。この文書がAPIの接続と使用に役立つことを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。