> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# hCaptcha 画像認識 API 連携説明

> hCaptcha verification code recognition service 集成指南 - Ace Data Cloud

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

## 申請プロセス

API を使用するには、まず [hCaptcha 画像認識 API](https://platform.acedata.cloud/documents/recognition-hcaptcha-integration) の該当ページでサービスを申請する必要があります。ページに入ったら、「Acquire」ボタンをクリックします。以下の図のように：

![](https://cdn.acedata.cloud/q6ytrc.png)

まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。ログインまたは登録後、現在のページに自動的に戻ります。

初回申請時には無料のクレジットが付与され、この API を無料で使用できます。

## 基本的な使用法

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

<p>
  <img src="https://cdn.acedata.cloud/xryo59.png" width="500" className="m-auto" />
</p>

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

<p>
  <img src="https://cdn.acedata.cloud/g8ikkb.png" width="500" className="m-auto" />
</p>

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

<p>
  <img src="https://cdn.acedata.cloud/empncr.png" width="500" className="m-auto" />
</p>

ここでは、リクエストヘッダーを設定しています。これには以下が含まれます：

* `accept`：受け取りたいレスポンス結果の形式。ここでは `application/json`、つまり JSON 形式を記入します。
* `authorization`：API を呼び出すためのキー。申請後、直接ドロップダウンから選択できます。

また、リクエストボディを設定しています。これには以下が含まれます：

* `queries`：Base64 エンコードされた CAPTCHA 画像のリスト。
* `question`：CAPTCHA 画像に関連する認識内容パラメータで、中英を直接入力できます。

選択後、右側にも対応するコードが生成されていることがわかります。以下の図のように：

<p>
  <img src="https://cdn.acedata.cloud/bww9b0.png" width="500" className="m-auto" />
</p>

「Try」ボタンをクリックするとテストが行えます。上の図のように、以下の結果が得られました：

```json theme={null}
{
  "solution": {
    "label": "Please click on the UNIQUE object among the others",
    "box": [
      "360",
      "276"
    ],
    "confidences": 0.6354503631591797
  }
}
```

返された結果には複数のフィールドがあり、以下のように説明されます：

* `solution`：今回の hCaptcha CAPTCHA 画像タスク処理後の検証結果。
  * `label`：hCaptcha CAPTCHA 画像が認識した内容。
  * `box`：hCaptcha CAPTCHA 画像の認識結果の位置情報で、画像の座標情報で構成されています。
  * `confidences`：hCaptcha CAPTCHA 画像認識後に認識内容を満たす信頼度。

ここで、hCaptcha CAPTCHA 画像の検証結果を得たことがわかります。結果の `box` の位置座標情報に基づいて、その CAPTCHA 画像の該当領域をシミュレートクリックすることで検証を通過できます。

次に、結果の `box` の位置情報を使用してクリックする方法を説明します。まず、アップロードした CAPTCHA 画像に対して直角座標系を構築します。中心原点は画像の左下隅にあり、360 は横座標、276 は縦座標に対応します。CAPTCHA に対応する座標をシミュレートクリックするだけで済みます。具体的な画像情報は以下の図のように：

<p>
  <img src="https://cdn.acedata.cloud/4ykvbl.png" width="500" className="m-auto" />
</p>

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

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/recognition/hcaptcha' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "question": "Please click on the UNIQUE object among the others.",
  "queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"]
}'
```

Python の連携コードは以下の通りです：

```python theme={null}
import requests

url = "https://api.acedata.cloud/captcha/recognition/hcaptcha"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "question": "Please click on the UNIQUE object among the others.",
    "queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

## エラーハンドリング

API を呼び出す際にエラーが発生した場合、API は対応するエラーコードと情報を返します。例えば：

* `400 token_mismatched`：不正なリクエスト、パラメータが不足または無効な可能性があります。
* `400 api_not_implemented`：不正なリクエスト、パラメータが不足または無効な可能性があります。
* `401 invalid_token`：未承認、無効または不足している認証トークン。
* `429 too_many_requests`：リクエストが多すぎます、レート制限を超えました。
* `500 api_error`：内部サーバーエラー、サーバーで何かがうまくいきませんでした。

### エラー応答の例

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## 結論

この文書を通じて、hCaptcha 画像認識 API を使用してユーザーが認識内容と hCaptcha CAPTCHA 画像を入力し、最終的にクリックする必要のある小さな画像の座標を返す方法を理解しました。この記事が、API の連携と使用をより良くする手助けとなることを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。