> ## 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.

# Recaptcha2 画像認識 API 接続説明

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

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

## 申請プロセス

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

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

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

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

## 基本使用

まず、基本的な使用方法を理解します。ウェブサイトから Recaptcha2 CAPTCHA 画像をキャプチャする必要があります。ここでは、例としてのウェブサイトの URL は `https://www.google.com/recaptcha/api2/demo` です。具体的なページは以下の図の通りです：

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

CAPTCHA のチェックボックスをクリックしないと CAPTCHA 画像は表示されません。上の図で黄色の矢印が指している部分にあるテキストが、以下の `question` の値です。まず、具体的な Recaptcha2 CAPTCHA 画像を示す `image` フィールドを簡単に渡す必要があります。この画像は上の図で赤い矢印が指している画像であり、画像は標準サイズ (100x100, 300x300, 450x450) にスケーリングする必要があります。そうしないと、サービスは画像のタイプを判断できません。画像の圧縮は自分で行う必要があります。この記事では、[圧縮サイト](https://www.photopea.com/) を推奨します。このサイトで画像のサイズと大きさを圧縮できます。圧縮後の結果は以下の図の通りです：

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

また、CAPTCHA 画像に関連する認識内容パラメータ `question` を入力する必要があります。以下の内容表を参考にしてください：

### 中国語内容表

```json theme={null}
{
  "/m/0pg52": "タクシー",
  "/m/01bjv": "バス",
  "/m/02yvhj": "スクールバス",
  "/m/04_sv": "オートバイ",
  "/m/013xlm": "トラクター",
  "/m/01jk_4": "煙突",
  "/m/014xcs": "横断歩道",
  "/m/015qff": "信号機",
  "/m/0199g": "自転車",
  "/m/015qbp": "駐車メーター",
  "/m/0k4j": "車",
  "/m/015kr": "橋",
  "/m/019jd": "ボート",
  "/m/0cdl1": "ヤシの木",
  "/m/09d_r": "山",
  "/m/01pns0": "消火栓",
  "/m/01lynh": "階段"
}
```

### 英語内容表

```json theme={null}
{
  "/m/0pg52": "taxis",
  "/m/01bjv": "bus",
  "/m/02yvhj": "school bus",
  "/m/04_sv": "motorcycles",
  "/m/013xlm": "tractors",
  "/m/01jk_4": "chimneys",
  "/m/014xcs": "crosswalks", // pedestrian crossings も同様
  "/m/015qff": "traffic lights",
  "/m/0199g": "bicycles",
  "/m/015qbp": "parking meters",
  "/m/0k4j": "cars",
  "/m/015kr": "bridges",
  "/m/019jd": "boats",
  "/m/0cdl1": "palm trees",
  "/m/09d_r": "mountains or hills",
  "/m/01pns0": "fire hydrant",
  "/m/01lynh": "stairs"
}
```

上記の内容から、パラメータ `question` を消火栓に対応する `/m/01pns0` に設定します。具体的な内容は以下の通りです：

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

ここで、リクエストヘッダーを設定しました。含まれる内容は以下の通りです：

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

さらに、リクエストボディを設定します。含まれる内容は以下の通りです：

* `image`：Base64 エンコードされた CAPTCHA 画像。
* `question`：問題 ID、表を参照してください。/m/ で始まります。

選択後、右側に対応するコードが生成されるのがわかります。以下の図の通りです：

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

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

```json theme={null}
{
  "solution": {
    "size": 300,
    "label": "/m/01pns0",
    "confidences": [
      0,
      0.0007,
      1,
      0.0003,
      0.0046,
      1,
      0,
      1,
      0
    ],
    "objects": [
      2,
      5,
      7
    ],
    "type": "multi"
  }
}
```

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

* `solution`、今回の Recaptcha2 CAPTCHA 画像タスク処理後の検証結果。
  * `size`、Recaptcha2 CAPTCHA 画像のサイズ。
  * `label`、Recaptcha2 CAPTCHA 画像が認識した内容。
  * `confidences`、Recaptcha2 CAPTCHA 画像認識領域の信頼度、領域は0から始まります。
  * `objects`、Recaptcha2 CAPTCHA 画像認識後に認識内容を満たす領域、領域は0から始まります。
  * `type`、今回の Recaptcha2 CAPTCHA 画像タスクのタイプ、複数の領域がある場合は `multi` です。

Recaptcha2 CAPTCHA 画像の検証結果を得たことがわかります。まず、CAPTCHA 画像を領域に分割します。以下の図の通りです：

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

領域はすべて0から始まることがわかります。結果の `objects` から2,5,7を得たので、これらの3つの領域をクリックすることで検証を通過できます。

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

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/recognition/recaptcha2' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "question": "/m/01pns0",
  "image": "iVBORw0KGgoAAAANSUhEUgAAASoAAAEsCAIAAAD7AWllAAAAAX..."
}'
```

Python の接続コードは以下の通りです：

```python theme={null}
import requests

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

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

payload = {
    "question": "/m/01pns0",
    "image": "iVBORw0KGgoAAAANSUhEUgAAASoAAAEsCAIAAAD7AWllAAAAAX..."
}

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"
}
```

## 結論

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