hCaptcha 画像認識

HCaptchaClassification は hCaptcha が表示する画像問題を認識します。問題文と画像を送ると、どの画像を選ぶか、どの位置をクリックするか、どこからどこへドラッグするかが返ります。ブラウザ上での操作はお使いのプログラムで行います。token は返しません。同期で結果を返し、1 回あたり 8 ポイント（約 $1.20 / 1k）。対象が見つからなかった場合（結果が空の場合）は課金されません。

ヒント

クリック処理を自分で書きたくない場合は、ブラウザ拡張機能をそのまま使えます。ここで説明する問題形式にはすべて対応しています。クリック位置ではなく token が必要な場合は hCaptcha を使ってください。

POSThttps://api.yescaptcha.com/createTaskグローバルエンドポイントコピー

POSThttps://cn.yescaptcha.com/createTask中国エンドポイントコピー

タイプと料金

タスクタイプ	価格	返却方式	備考
HCaptchaClassification	$1.20 / 1k; 8 ポイント/タスク · ¥8 / 1k	同期	対象が見つからなかった場合は課金されません

米ドル価格は US$1 ≈ ¥6.67 での概算です。タスクはポイントで課金されます。

リクエストパラメータ

フィールド	型	必須	説明
type	string	はい	タスクタイプ。値はこのページの「タイプと料金」を参照してください
queries	array	はい	ページ上の順序に並べた、問題画像の Base64 エンコード文字列のリスト(3×3 グリッドなら 9 枚のタイル)
question	string	いいえ	ページに表示されている問題文の全文（簡体字中国語または英語を推奨）。例: Please click each image containing a bicycle。question と anchors の少なくとも一方を送信してください。両方の送信を推奨します
anchors	array	いいえ	問題文の横に表示される例示画像の Base64 エンコード文字列のリスト。例示画像がある問題では必須

• question にはページに表示されている問題文をそのまま渡します。翻訳は不要ですが、hCaptcha の言語は簡体字中国語または英語に切り替えることをおすすめします。新しい問題文はたいてい早期に対応され、まったく新しいカテゴリは 3 営業日以内に対応します。

注意

問題文の右上に例示画像が表示されている場合は、その画像を anchors に入れてください。例示画像を見ないと判断できない問題は、anchors がないと認識できません。

3×3 グリッドの選択

問題文が「Please click each image containing …」の形式で、下に 9 枚の小さな画像が並んでいる場合です。queries に 9 枚の画像の Base64 を順番に入れます。

POST https://api.yescaptcha.com/createTask

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaClassification",
    "question": "Please click each image containing a bicycle",
    "queries": ["BASE64_IMAGE_1", "BASE64_IMAGE_2"]
  }
}

レスポンス:

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "objects": [true, false, false, true, true, false, true, true, false],
    "top_k": [0, 3, 4, 6, 7],
    "confidences": [1.0, 0.0, 0.0, 1.0, 1.0, 0.0, 1.0, 1.0, 0.0]
  }
}

objects と top_k は同じ内容を表します。前者は各画像が対象かどうか、後者は対象画像の番号（0 始まり）です。該当する画像をクリックしてください。

指定位置のクリック

問題文が「Please click …」の形式で、下に 1 枚の大きな画像があり、その画像上の 1 か所または複数か所をクリックする場合です。

1. question にはページ上の問題文を渡します。例示画像がある場合は anchors に入れます。
2. queries には画像を 1 枚入れます。canvas から直接書き出した元画像（JPG への変換を推奨）が最適です。スクリーンショットしか取れない場合は、下図の赤枠内にある大きな画像の領域だけを、過不足なく切り取ってください。
3. 返された box がクリックする座標で、x1、y1、x2、y2 … の順に並びます。原点はアップロードした画像の左上です。
4. アップロードした画像のサイズとページ上の表示サイズが異なる場合は換算が必要です。ページ上の x = 返された x × 表示幅 ÷ アップロードした画像の幅（y も同様）。たとえば返された x = 769、canvas の表示幅 350、アップロードした画像の幅 1000 の場合、ページ上でクリックする位置は 769 × 350 ÷ 1000 ≈ 269 です。

POST https://api.yescaptcha.com/createTask

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaClassification",
    "question": "Please click on the entity present in the sample image.",
    "anchors": ["BASE64_ANCHOR_1", "BASE64_ANCHOR_2", "BASE64_ANCHOR_3"],
    "queries": ["BASE64_OF_THE_BIG_IMAGE"]
  }
}

レスポンス:

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "box": ["221", "213"]
  }
}

複数の対象をクリックする場合、box には複数組の座標が順に入ります: ["221", "213", "340", "118", ...]。

指定位置へのドラッグ

問題文が「Drag … to …」の形式で、右側のピースを画像内の対応する位置までドラッグする場合です。

1. question にはページ上の問題文を渡します。
2. スクリーンショットを 1 枚 queries に入れます。画像にはドラッグするピースと目標位置の両方が写っている必要があり、どの辺も 260 ピクセル以上にしてください。
3. 返された box の各項目が 1 回のドラッグです。start はピースの位置、end はドロップ先の位置です。ピースが複数ある場合は 1 つずつドラッグします。

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "type": "drag",
    "box": [
      {
        "start": [644, 218],
        "end": [239, 315]
      }
    ]
  }
}

スクリーンショットではなくプロトコルのデータ（ピースの画像、ピースの座標、背景の大きな画像）を取得している場合は、座標に従ってピースを背景画像に合成し、ページのスクリーンショットと同じ見た目の画像にしてから送信してください。

アニメーション問題

問題の画像がアニメーションの場合は、アニメーション（GIF などの形式）の Base64 を queries に入れます。アニメーションの長さは 3 秒以上、できれば 5〜6 秒、フレームレートは約 12 FPS を推奨します。

報告と返金

クリック後に検証に失敗した場合は、1 時間以内に report で報告できます。約 24 時間後に報告による返金が確定します。ルールは課金と返金をご覧ください。

関連チュートリアル

• hCaptcha 画像認識でクリックをシミュレートする（Selenium）