Skip to main content
本文では、ユーザーが hCaptcha 認証画像を認識してクリックすることなく、Website Key を提出するだけでバックエンドで自動的にデコードを実現し、認証を完了できる hCaptcha プロトコル認識 API の接続説明を紹介します。

​
申請プロセス

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

​
基本的な使用法

まず、基本的な使用方法を理解します。処理する必要のある hCaptcha 認証のウェブサイトの URL を入力するだけで、処理された結果を得ることができます。最初に website_url フィールドを簡単に渡す必要があります。私たちのサンプルサイトは https://accounts.hcaptcha.com/demo です。この website_url ページで website_key を取得する必要があります。まずこのウェブページを開き、F12 を押してコンソールに入ります。最後に Element ページで hcaptcha-demo を全体検索すると、以下の結果が得られます：

ここで data-sitekey に対応する一連の文字列が website_key の値です。以下は具体的なパラメータ結果です：

ここでは、リクエストヘッダーを設定しています。含まれるのは：
  • accept：受け取りたいレスポンス結果の形式。ここでは application/json、つまり JSON 形式を記入します。
  • authorization：API を呼び出すためのキー。申請後、直接ドロップダウンから選択できます。
さらに、リクエストボディを設定しています。含まれるのは：
  • website_url：認証を処理するウェブサイトの URL。
  • website_key：hCaptcha におけるウェブサイトのキー識別子。
  • rqdata：オプション。hCaptcha Enterprise のチャレンジがページ内で data-rqdata を提供する場合、その原始値を記入します。通常の hCaptcha では記入不要です。
  • proxy：オプション。自前のプロキシ（Bring Your Own Proxy）。設定後、システムは提供されたプロキシ IP を使用して認証を解決します。出口 IP の品質を制御するために使用されます（例えば、公共プロキシ IP がターゲットサイトにブロックされて 410 Gone が返されるのを避けるため）。形式は scheme://[user:pass@]host:port で、scheme は http/https/socks4/socks5 をサポートします。例えば http://user:pass@1.2.3.4:8080 のようになります。未記入の場合はプラットフォームのデフォルトプロキシが使用されます。
選択後、右側にも対応するコードが生成されていることがわかります。以下のように示されています：

「Try」ボタンをクリックするとテストが行えます。上の図のように、以下の結果が得られました：
私たちはhCaptchaの検証結果を処理し、これをPOSTまたはターゲットサイトに模擬的に送信するために使用できることがわかります。一度限りの使用で、有効期限は120秒、60秒以内の使用を推奨します。次に、処理されたトークンをターゲットサイトに送信してRecaptcha2の検証を通過させるCURLバージョンを提供します。 まず、サイトがどのようにPOSTリクエストを送信しているかを取得する必要があります。そうすれば、生成されたトークンを渡すことができます。最初にF12コンソールを開き、手動で検証を行います。最後に、サイトがPOSTリクエストを送信したことがわかります。このPOSTリクエストの構造を確認する必要があります。具体的な手順は以下の通りです。
  • まず手動で検証を行います。具体的には以下の図の通りです：

  • 次にsubmitをクリックし、コンソールのnetworkの変化を観察します。具体的には以下の図の通りです：

  • 今回のPOSTリクエストの構造を分析し、右クリックしてCURLのコードをコピーします。具体的には以下の図の通りです：

上の図から分析すると、今回のPOSTリクエストのURLは：https://accounts.hcaptcha.com/demoであり、送信する必要があるパラメータは g-recaptcha-response、h-captcha-response と email です。処理されたトークンを以下のdataに渡すだけで済みます。トークン検証に対応するCURLコードは以下の通りです：
トークン検証に対応するPythonコードは以下の通りです：
次に、コンソールがこのような結果になったことを観察します：

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

​
非同期モード（async）

デフォルトでは、APIは同期ブロッキングです：1回のリクエストはトークン処理が完了するまで待機します。複数のソルバーのローテーションを行っている場合、「タスクを提出した後、すぐにtask_idを取得し、他のソルバーを調整し、後で結果を読み取る」ことを希望する場合は、リクエストボディに async: true を渡すことができます。 async: true を渡すと、インターフェースはすぐに task_id を返し、ブロックして待機しません：
進捗を確認するには、この task_id を使用して POST /captcha/tasks をクエリできます（3〜5秒ごとを推奨）。このインターフェースはタスク処理をトリガーしたり進めたりしません。クエリしなくても、ネットワークが切断されても、クライアントが終了しても、サーバーは処理を続けます：
処理中は status: processing が返されます：
処理が完了すると、status: ready とトークンが返されます：
請求の説明：非同期モードでは、タスクの作成と「処理中」状態の読み取りは課金されません；クライアントが最初に成功した結果を読み取るときに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の検証画像を認識したりクリックしたりすることなく、Website Keyを提出するだけでバックエンドで自動的にデコードし、検証を完了する方法を理解しました。この文書がAPIの接続と使用に役立つことを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。