タスクタイプ

hCaptcha

このページは中国語版から機械翻訳されたもので、不正確な箇所がある可能性があります。中国語版を正としてください。

私は人間ですhCaptchaプライバシー - 利用規約

イメージ図hCaptcha：「私は人間です」のチェックボックスが表示されます。クリックすると、そのままチェックが入るか、画像チャレンジが表示されます。

hCaptcha タスクはトークン(gRecaptchaResponse)を返します。返された userAgent(場合によっては respKey も)と一緒に対象サイトへ送信すると、検証を通過できます。HCaptchaTaskProxyless は 1 タスクあたり 30 ポイント（約 $4.50 / 1k）、独自プロキシを使う HCaptchaTask は 1 タスクあたり 15 ポイント（約 $2.25 / 1k）です。どちらも非同期で、まず createTask を呼び出し、その後 5 秒ごとに getTaskResult を呼び出します。認識に失敗した場合やタイムアウトした場合は、自動的に返金されます。

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

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

リクエストボディは JSON で、clientKey で認証します。タスクを作成したエンドポイントと同じエンドポイントで結果を取得してください。

利用シーン

ページに hCaptcha の「私は人間です」チェックボックスがある場合や、hCaptcha の画像問題が表示される場合です。トークンを取得してそのまま送信したいときは、このページのタイプを使います。ブラウザ上で自分で画像をクリックしたいときは、hCaptcha 画像認識を使います。

タスクタイプと料金

タスクタイプ	価格	返却方式	備考
`HCaptchaTaskProxyless`	$4.50 / 1k; 30 ポイント/タスク · ¥30 / 1k	非同期
`HCaptchaTaskProxylessM1`	$4.50 / 1k; 30 ポイント/タスク · ¥30 / 1k	非同期	HCaptchaTaskProxyless とパラメータは同じで、経路が異なります。どちらか一方をバックアップとして使えます
`HCaptchaTask`	$2.25 / 1k; 15 ポイント/タスク · ¥15 / 1k	非同期	プロキシ持ち込み

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

HCaptchaTaskProxyless と HCaptchaTaskProxylessM1 はパラメーターが同じで、経路が異なります。互いのバックアップとして使えます。
HCaptchaTask は独自のプロキシでキャプチャを読み込むため、プロキシ関連のフィールドが必要です。対象サイトがアクセス元の IP を検査する場合に使います。

リクエストパラメーター

フィールド	型	必須	説明
`type`	string	はい	タスクタイプ。値はこのページの「タイプと料金」を参照してください
`websiteURL`	string	はい	キャプチャが表示されるページの完全な URL。キャプチャが表示されるサイトを指定し、キャプチャ提供元のドメインは指定しないでください
`websiteKey`	string	はい	hCaptcha のサイトキー（sitekey）。通常は UUID 形式です
`userAgent`	string	いいえ	ブラウザーの User-Agent。指定を推奨しますが、受け付けられるのは `GET https://api.yescaptcha.com/useragent` が返す値のみです。token は結果に含まれる `userAgent` を使って送信してください
`isInvisible`	boolean	いいえ	インビジブル版の場合は true を指定します。通常版では指定しません
`rqdata`	string	いいえ	エンタープライズ版 hCaptcha の rqdata。一部のサイトで必要で、通常はキャプチャを読み込むリクエストから確認できます
`proxyType`	string	一部のタイプ	プロキシのプロトコル: `http`、`https`、`socks4`、`socks5`（HCaptchaTask では必須）
`proxyAddress`	string	一部のタイプ	プロキシの IP アドレスまたはホスト名。127.0.0.1 や 192.168.x.x のようなローカルアドレスやプライベートアドレスは、当社のサーバーから到達できないため使用できません（HCaptchaTask では必須）
`proxyPort`	integer	一部のタイプ	プロキシのポート（HCaptchaTask では必須）
`proxyLogin`	string	いいえ	プロキシのユーザー名（プロキシが認証を必要とする場合）（HCaptchaTask のみ）
`proxyPassword`	string	いいえ	プロキシのパスワード（プロキシが認証を必要とする場合）（HCaptchaTask のみ）

websiteURL にはキャプチャが表示されるページを指定します。hcaptcha.com ではありません。
userAgent は指定を推奨します。指定できるのは /useragent が返す値のみです。
rqdata:hCaptcha Enterprise を使うサイト(一部のソーシャルサイトやチャットサイトなど)で必要になります。通常は、キャプチャを読み込むリクエストの中に含まれています。一般的なサイトでは指定しません。

パラメーターの見つけ方は、hCaptcha パラメーターの調べ方を参照してください。

リクエスト例

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
  }
}

curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
  }
}'

# Returns {"errorId":0,"taskId":"..."}; then poll every 5 seconds:
curl -s https://api.yescaptcha.com/getTaskResult \
  -H 'Content-Type: application/json' \
  -d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'

import os
import time

import requests

API = "https://api.yescaptcha.com"
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]  # Read the clientKey from an environment variable


def call(method, payload):
    r = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30)
    data = r.json()
    if data.get("errorId"):
        raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
    return data


def solve(task):
    task_id = call("createTask", {"task": task})["taskId"]
    for _ in range(36):  # Poll every 5 seconds, for up to about 3 minutes
        time.sleep(5)
        result = call("getTaskResult", {"taskId": task_id})
        if result.get("status") == "ready":
            return result["solution"]
    raise TimeoutError(task_id)


solution = solve({
    "type": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
})
print(solution["gRecaptchaResponse"])

const API = 'https://api.yescaptcha.com';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY; // Read the clientKey from an environment variable

async function call(method, payload) {
  const res = await fetch(`${API}/${method}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ clientKey: CLIENT_KEY, ...payload }),
  });
  const data = await res.json();
  if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
  return data;
}

async function solve(task) {
  const { taskId } = await call('createTask', { task });
  for (let i = 0; i < 36; i++) { // Poll every 5 seconds, for up to about 3 minutes
    await new Promise((r) => setTimeout(r, 5000));
    const result = await call('getTaskResult', { taskId });
    if (result.status === 'ready') return result.solution;
  }
  throw new Error(`timeout: ${taskId}`);
}

const solution = await solve({
  type: "HCaptchaTaskProxyless",
  websiteURL: "https://accounts.hcaptcha.com/demo",
  websiteKey: "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
});
console.log(solution.gRecaptchaResponse);

独自のプロキシを使う場合:

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaTask",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
    "proxyType": "http",
    "proxyAddress": "proxy.example.com",
    "proxyPort": 8080,
    "proxyLogin": "user",
    "proxyPassword": "pass"
  }
}

レスポンス

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36",
    "respKey": "E0_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
  }
}

フィールド	型	説明
`gRecaptchaResponse`	string	対象サイトに送信するトークン。1 回限りの使用で、有効期間は約 120 秒です。60 秒以内に使用してください
`userAgent`	string	トークンの取得に使用した User-Agent。トークンを送信する際はこの値を使用してください。送信した値と異なる場合もこちらが優先されます
`respKey`	string	サイトによってはトークンと一緒に送信する必要がある値。返された場合は一緒に送信してください

送信手順:

トークンを、ページ内の h-captcha-response フィールド(g-recaptcha-response がある場合はそのフィールドにも)、または対象サイトの API が要求するフィールドに設定します。
送信リクエストを送る際は、User-Agent に返された userAgent を使用します。
respKey が返された場合は、サイトの要件に従って一緒に送信します。

処理中は {"errorId": 0, "status": "processing"} が返されるので、5 秒後にもう一度取得してください。エラーが発生した場合は errorCode に従って対処します。詳しくはエラーコードを参照してください。

よくある質問

通過率が安定しないのはなぜですか?

hCaptcha は、サイトの設定、アクセス元の IP、ブラウザ環境をもとに判定するため、通過率はサイトによって異なります。返された userAgent を使用していることを確認してください。IP に敏感なサイトでは、独自プロキシを使う HCaptchaTask を使い、送信時も同じプロキシを経由させます。HCaptchaTaskProxylessM1 に切り替えて比較することもできます。

トークンの有効期間はどのくらいですか?

トークンは使い捨てで、有効期間は約 120 秒です。取得後はできるだけ早く送信してください。