# YesCaptcha Docs (full text)
> YesCaptcha はキャプチャ認識 API です。1 つの JSON インターフェースで reCAPTCHA、hCaptcha、Cloudflare Turnstile、FunCaptcha、AWS WAF、画像キャプチャを認識できます。課金はタスク単位で、認識に失敗した場合やタイムアウトした場合は自動で返金されます。
---
# 1 つの JSON インターフェースでキャプチャを認識
> YesCaptcha はキャプチャ認識 API です。1 つの JSON インターフェースで reCAPTCHA、hCaptcha、Cloudflare Turnstile、FunCaptcha、AWS WAF、画像キャプチャを認識できます。課金はタスク単位で、認識に失敗した場合やタイムアウトした場合は自動で返金されます。
Source: https://docs.yescaptcha.com/ja/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/
[キャプチャ認識 APIステータス](https://status.yescaptcha.com/?lang=en)
reCAPTCHA、hCaptcha、Cloudflare Turnstile、FunCaptcha、AWS WAF、画像の英数字キャプチャを認識します。課金はタスク単位で、1 元 = 1000 ポイント。認識に失敗した場合やタイムアウトした場合は自動で返金されます。
[クイックスタート](https://docs.yescaptcha.com/ja/getting-started/quickstart.md)[API リファレンス](https://docs.yescaptcha.com/ja/api/overview.md)
AI・プログラム向けのバージョン：[llms.txt](https://docs.yescaptcha.com/ja/llms.txt)[llms-full.txt](https://docs.yescaptcha.com/ja/llms-full.txt)[OpenAPI](https://docs.yescaptcha.com/openapi.json)[Markdown](https://docs.yescaptcha.com/ja/index.md)
YesCaptcha は合法的な用途に限り利用できます。違法な用途での利用は禁止です。
POSTapi.yescaptcha.com/createTask
```
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}
```
1. /createTasktaskId 61138bb6-19fb-11ec-a9c8-0242ac110006
2. /getTaskResultprocessing
3. /getTaskResultprocessing
4. /getTaskResultready
5. gRecaptchaResponse03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU...
1. 1タスク作成
2. 2結果取得
3. 3サイトに送信
例：reCAPTCHA v2、5 秒ごとに結果を取得
$0.30 / 1kから
タスクあたりの最低価格
1 元 = 1000 ポイント
失敗・タイムアウトは自動で返金
2 つのエンドポイント
グローバルエンドポイントと中国エンドポイント
9:00–21:00
有人サポート（UTC+8）
[クイックスタート登録して clientKey を取得し、5 分で最初のリクエストを送信](https://docs.yescaptcha.com/ja/getting-started/quickstart.md)[API リファレンスcreateTask、getTaskResult、エラーコード、同時実行数の上限](https://docs.yescaptcha.com/ja/api/overview.md)[タスクタイプと料金公開しているすべてのタイプの料金、返却方式、パラメーター](https://docs.yescaptcha.com/ja/tasks.md)[ブラウザ拡張機能コードを書かずに、Web ページ上で認証を自動で完了](https://docs.yescaptcha.com/ja/extension.md)
## 対応しているキャプチャ
[01reCAPTCHAv2、v3、Enterprise、および v2 の画像認識$0.90 / 1kから](https://docs.yescaptcha.com/ja/tasks/recaptcha-v2.md)[02hCaptchatoken を返す、または画像を認識して自分でクリック$1.20 / 1kから](https://docs.yescaptcha.com/ja/tasks/hcaptcha.md)[03Cloudflare TurnstileTurnstile の検証 token$3.75 / 1kから](https://docs.yescaptcha.com/ja/tasks/turnstile.md)[04FunCaptchaArkose Labs の画像問題を認識。すべての問題タイプに対応$0.45 / 1kから](https://docs.yescaptcha.com/ja/tasks/funcaptcha-classification.md)[05AWS WAF / bCaptcha3×3 グリッドの画像認識$1.20 / 1kから](https://docs.yescaptcha.com/ja/tasks/aws-bcaptcha-classification.md)[06画像の英数字通常の文字キャプチャ。同期で結果を返す$0.30 / 1kから](https://docs.yescaptcha.com/ja/tasks/image-to-text.md)
## 3 ステップで導入
1. 01
**タスクを作成**
`createTask` でタスクタイプとサイトのパラメーターを送信し、`taskId` を取得します。画像認識や画像の英数字などの同期タイプは、結果が直接返されます。
2. 02
**結果を取得**
5 秒ごとに `getTaskResult` を呼び出します。`status` が `ready` になると、結果は `solution` に入っています。
3. 03
**対象サイトに送信**
取得した token をページのフォームやリクエストに入力します。token は 1 回限り有効で、60 秒以内の使用を推奨します。
POST /createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}
```
POST /getTaskResult
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
}
}
```
## よく使うページ
- [**エラーコード**各エラーコードの意味と対処方法](https://docs.yescaptcha.com/ja/api/errors.md)
- [**同時実行数の上限と自動一時停止**上限を超えた場合やエラーが多すぎる場合の動作](https://docs.yescaptcha.com/ja/api/rate-limits.md)
- [**課金と返金**ポイント、事前課金、返金、報告後の返金](https://docs.yescaptcha.com/ja/getting-started/billing.md)
- [**お問い合わせ**WeChat、QQ、Telegram、メール。受付時間 9:00–21:00（UTC+8）](https://docs.yescaptcha.com/ja/help/contact.md)
- [**ダッシュボード**登録、clientKey の取得、チャージ](https://yescaptcha.com/)
---
# はじめに
> YesCaptcha とは。API またはブラウザ拡張機能で reCAPTCHA、hCaptcha、Turnstile、FunCaptcha、画像キャプチャを認識し、タスクごとにポイントを課金、失敗時は自動で返金します。
Source: https://docs.yescaptcha.com/ja/getting-started/introduction/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/getting-started/introduction/
YesCaptcha はキャプチャ認識サービスです。キャプチャの情報を YesCaptcha の API に送ると、対象サイトにそのまま送信できる token、または画像の認識結果が返ります。reCAPTCHA（v2、v3、Enterprise）、hCaptcha、Cloudflare Turnstile、Cloudflare チャレンジページ、FunCaptcha、AWS WAF、bCaptcha、英数字の画像キャプチャに対応しています。タスクごとにポイントを課金し（1 元 = 1,000 ポイント）、認識に失敗したタスクやタイムアウトしたタスクは自動で返金されます。
YesCaptcha は合法的な用途に限り利用できます。違法な用途での利用は禁止されています。
## 2 つの使い方
| | API | ブラウザ拡張機能（YesCaptcha Assistant） |
| --- | --- | --- |
| 向いている人 | コードを書ける開発者。プログラムで大量に処理したい場合 | コードを書かず、ブラウザ上で使いたい場合 |
| 使い方 | `clientKey` を使って `createTask`、`getTaskResult` を呼び出す | 拡張機能をインストールして `clientKey` を入力すると、キャプチャを自動で認識してクリックする |
| 対応範囲 | 本サイトに掲載しているすべてのタスクタイプ | reCAPTCHA v2、hCaptcha、FunCaptcha、AWS WAF、bCaptcha の画像問題と文字キャプチャ |
| 料金 | タスクタイプごとにポイントを課金 | 拡張機能は無料。認識に使った API の分だけポイントを課金 |
どちらの使い方でも、同じアカウント、同じ `clientKey`、同じ残高を使います。
## 認識結果は 3 種類
- **token**：reCAPTCHA、hCaptcha、Turnstile、FunCaptcha のほとんどのタスクタイプ。文字列が返り、ページのフォームやリクエストに入れるだけで検証を通過でき、画像のクリックは不要です。すべて非同期で、タスクを作成してから 5 秒ごとに結果を問い合わせます。
- **画像認識の結果**：名前が `Classification` で終わるタイプ。キャプチャの画像を送ると、クリックすべき画像や位置が返り、ブラウザ上でのクリックはお使いのプログラムが行います。同期で、1 回のリクエストで結果が得られます。
- **文字または Cookie**：英数字の画像認識は画像内の文字を返し、Cloudflare チャレンジページは検証通過後の Cookie を返します。
すべてのタイプと価格は [タスクタイプと価格](https://docs.yescaptcha.com/ja/tasks.md) を参照してください。
## ここから始める
[クイックスタート](https://docs.yescaptcha.com/ja/getting-started/quickstart.md)アカウント登録、clientKey の取得、最初のリクエスト
[エンドポイント](https://docs.yescaptcha.com/ja/getting-started/endpoints.md)グローバルエンドポイントと中国エンドポイント
[課金と返金](https://docs.yescaptcha.com/ja/getting-started/billing.md)ポイント、事前課金、返金、報告後の返金
[ブラウザ拡張機能](https://docs.yescaptcha.com/ja/extension.md)コード不要で、ブラウザ上で自動認識
## コミュニティ SDK
ユーザーが提供した SDK です。非公式のため、利用前にご自身で評価してください。[サンプルコードと SDK](https://docs.yescaptcha.com/ja/samples.md) を参照してください。
---
# クイックスタート
> 5 分で最初の YesCaptcha リクエストを送信します。アカウント登録、clientKey のコピー、チャージを行い、curl、Python、Node.js で画像キャプチャを認識します（ImageToTextTaskOcrBase、同期で結果を返し、1 回 2 ポイント）。
Source: https://docs.yescaptcha.com/ja/getting-started/quickstart/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/getting-started/quickstart/
このページでは、最もシンプルなタスクタイプ `ImageToTextTaskOcrBase`（画像内の英数字を認識します）で最初のリクエストを送信します。同期タイプなので、`createTask` リクエスト 1 回で結果が返ります。料金は 1 回 2 ポイント（約 $0.30 / 1k） で、サードパーティのサイトに依存しないため、アカウントとコードに問題がないかの確認に適しています。
1. **アカウントを登録する**
[yescaptcha.com](https://yescaptcha.com/) を開き、登録してログインします。
2. **clientKey をコピーする**
ログイン後、ダッシュボード（[yescaptcha.com/dashboard.html](https://yescaptcha.com/dashboard.html)）で「クライアントキー」を探してコピーします。全体をコピーしてください。
> **注意:** API リクエストはすべて clientKey で認証されます。第三者に知られると、あなたの残高を使われてしまいます。他人に送ったり、公開するコードに書き込んだりしないでください。漏えいした場合は、同じ場所でリセットできます。
3. **チャージする**
タスクを作成するには、残高が 10 ポイントを超えている必要があります。チャージ方法と VIP ボーナスについては [チャージと VIP](https://docs.yescaptcha.com/ja/account/recharge.md) を参照してください。
4. **clientKey が使えることを確認する**
`getBalance` で残高を確認します。ポイントは消費されません。
```bash
curl -s https://api.yescaptcha.com/getBalance \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY"}'
```
`{"errorId": 0, "balance": 12345, ...}` が返れば利用可能です。`balance` は残りのポイント数です。`ERROR_KEY_DOES_NOT_EXIST` が返った場合は、キーのコピーが間違っています。
5. **画像を認識する**
サンプル画像 [captcha.jpg](https://docs.yescaptcha.com/samples/captcha.jpg) をダウンロードし（自分のキャプチャ画像でも構いません）、clientKey を環境変数に設定してから実行します。
```bash
export YESCAPTCHA_CLIENT_KEY=你的clientKey
```
**curl**
quickstart.sh
```bash
#!/usr/bin/env bash
# First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase (synchronous, 2 points per image)
# Usage: YESCAPTCHA_CLIENT_KEY=your_client_key bash quickstart.sh captcha.png
set -euo pipefail
IMAGE="${1:-captcha.png}"
BODY=$(base64 < "$IMAGE" | tr -d '\n') # no "data:" prefix, no line breaks
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d "{\"clientKey\": \"${YESCAPTCHA_CLIENT_KEY}\", \"task\": {\"type\": \"ImageToTextTaskOcrBase\", \"body\": \"${BODY}\"}}"
echo
```
**Python**
quickstart.py
```python
"""First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase
(synchronous, 2 points per image).
Usage:
export YESCAPTCHA_CLIENT_KEY=your_client_key
python quickstart.py captcha.png
"""
import base64
import os
import sys
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
image_path = sys.argv[1] if len(sys.argv) > 1 else "captcha.png"
with open(image_path, "rb") as f:
body = base64.b64encode(f.read()).decode() # no "data:" prefix
r = requests.post(
"https://api.yescaptcha.com/createTask",
json={
"clientKey": CLIENT_KEY,
"task": {"type": "ImageToTextTaskOcrBase", "body": body},
},
timeout=30,
)
data = r.json()
if data.get("errorId"):
raise SystemExit(f"{data.get('errorCode')}: {data.get('errorDescription')}")
print("text:", data["solution"]["text"])
```
**Node.js**
quickstart.mjs
```js
// First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase (synchronous, 2 points per image).
// Usage: YESCAPTCHA_CLIENT_KEY=your_client_key node quickstart.mjs captcha.png
import { readFileSync } from 'node:fs';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;
const body = readFileSync(process.argv[2] ?? 'captcha.png').toString('base64'); // no "data:" prefix
const res = await fetch('https://api.yescaptcha.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY, task: { type: 'ImageToTextTaskOcrBase', body } }),
});
const data = await res.json();
if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
console.log('text:', data.solution.text);
```
実行コマンドは `bash quickstart.sh captcha.jpg`、`python quickstart.py captcha.jpg`、`node quickstart.mjs captcha.jpg` のいずれかです。Python は事前に `pip install requests` が必要で、Node.js は 18 以上のバージョンが必要です。
6. **結果を確認する**
成功すると次のように返ります。
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"text": "LMResm"
},
"taskId": "2376919c-1863-11ec-a012-94e6f7355a0b"
}
```
`errorId` が 0 なら成功で、認識された文字は `solution.text` に入っています。`errorId` が 1 の場合は `errorCode` を確認してください。意味は [エラーコード](https://docs.yescaptcha.com/ja/api/errors.md) を参照してください。
## 次のステップ
- reCAPTCHA や hCaptcha のように token を返すタスクは**非同期**です。`createTask` がまず `taskId` を返し、その後 5 秒ごとに `getTaskResult` を呼び出します。全体の流れは [リクエストとレスポンス](https://docs.yescaptcha.com/ja/api/overview.md)、例は [reCAPTCHA v2](https://docs.yescaptcha.com/ja/tasks/recaptcha-v2.md) を参照してください。
- タスクタイプを選ぶ：[タスクタイプと料金](https://docs.yescaptcha.com/ja/tasks.md)。
- プロジェクトにそのままコピーして使えるクライアント：[Python](https://docs.yescaptcha.com/ja/samples/python.md)、[Node.js](https://docs.yescaptcha.com/ja/samples/nodejs.md)。
- コードを書かない場合：[ブラウザ拡張機能](https://docs.yescaptcha.com/ja/extension.md)。
---
# エンドポイント
> YesCaptcha API の2つのエンドポイント、グローバルの api.yescaptcha.com と中国の cn.yescaptcha.com。HTTPS の POST と JSON のみ対応。タスクの作成と取得は同じエンドポイントで行います。
Source: https://docs.yescaptcha.com/ja/getting-started/endpoints/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/getting-started/endpoints/
YesCaptcha API には2つのエンドポイントがあり、メソッドとパラメータはまったく同じです。サーバーの所在地に合わせて選んでください。
| エンドポイント | アドレス | 適した用途 |
| --- | --- | --- |
| グローバルエンドポイント | `https://api.yescaptcha.com` | 中国本土以外のサーバー |
| 中国エンドポイント | `https://cn.yescaptcha.com` | 中国本土のサーバー |
メソッドの URL はエンドポイントにメソッド名を付けたものです。例としてタスクの作成は次のとおりです。
- POST `https://api.yescaptcha.com/createTask` (グローバルエンドポイント)
- POST `https://cn.yescaptcha.com/createTask` (中国エンドポイント)
## ルール
- HTTPS のみ使用できます。
- [/useragent](https://docs.yescaptcha.com/ja/api/useragent.md) 以外のすべてのメソッドは `POST` を使い、リクエストボディは JSON で、ヘッダー `Content-Type: application/json` を付けます。ボディは 6 MB 以内にしてください。
- 認証はボディ内の `clientKey` で行います。ほかのヘッダーは不要です。
> **ノート:** タスクを作成したエンドポイントと同じエンドポイントで `getTaskResult` を使って取得してください。2つのエンドポイントを混在させないでください。
## すべてのメソッド
| メソッド | 役割 | 説明 |
| --- | --- | --- |
| [createTask](https://docs.yescaptcha.com/ja/api/create-task.md) | タスクを作成 | 同期タイプは結果をそのまま返します |
| [getTaskResult](https://docs.yescaptcha.com/ja/api/get-task-result.md) | タスクの結果を取得 | 非同期タイプは 5 秒ごとにポーリングします |
| [getBalance](https://docs.yescaptcha.com/ja/api/get-balance.md) | 残高を取得 | 課金されません |
| [getSoftID](https://docs.yescaptcha.com/ja/api/get-soft-id.md) | 開発者 ID を取得 | 開発者収益分配に使います |
| [report](https://docs.yescaptcha.com/ja/api/report.md) | 認識結果を報告 | 画像認識タイプは報告による返金を申請できます |
| [useragent](https://docs.yescaptcha.com/ja/api/useragent.md) | 推奨の User-Agent を取得 | `GET`、hCaptcha で使います |
接続できない場合は、[接続とネットワークの問題](https://docs.yescaptcha.com/ja/help/troubleshooting.md)を参照してください。
---
# 課金と返金
> YesCaptcha の課金方法。1,000 ポイント = ¥1 で、タスクタイプごとに固定価格で課金されます。解析に失敗したタスクやタイムアウトしたタスクは返金され、エラーを返したリクエストには課金されません。残高は 10 ポイントより多い必要があります。画像認識で失敗を報告した場合は、約 24 時間後に返金されます。
Source: https://docs.yescaptcha.com/ja/getting-started/billing/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/getting-started/billing/
YesCaptcha はタスク単位で課金します。タスクタイプごとにポイントの固定価格が決まっており(1,000 ポイント = ¥1)、たとえば `NoCaptchaTaskProxyless` は 1 タスクあたり 15 ポイント（約 $2.25 / 1k） です。各タイプの価格は [タスクタイプと価格](https://docs.yescaptcha.com/ja/tasks.md) を参照してください。
> **ヒント:** 成功したタスクの分だけ支払います。解析に失敗したタスクやタイムアウトしたタスクは自動的に返金され、エラーを返したリクエストには課金されません。
## 課金されるタイミング
- **非同期タイプ**(token を返すタイプの大半): タスクの作成に成功した時点で課金されます。その後、解析に失敗した場合(`ERROR_CAPTCHA_UNSOLVABLE` など)やタイムアウトした場合(`ERROR_TASK_TIMEOUT`、通常 110 秒)は、ポイントが自動的に返金されます。
- **同期タイプ**(画像認識、`ImageToTextTaskOcrBase`、`ImageToTextTaskMuggle`): 認識に成功して結果を返した時点で課金されます。
- タスク作成時にエラーを返したリクエスト(パラメータの誤り、残高不足、同時実行数の上限超過など)には課金されません。
## 残高
- タスクを作成するには、残高が **10 ポイントより多い**必要があります。足りない場合は `ERROR_ZERO_BALANCE` が返されます。
- 残高は [getBalance](https://docs.yescaptcha.com/ja/api/get-balance.md) で確認できます。課金はされません。
- チャージと VIP ボーナスについては [チャージと VIP](https://docs.yescaptcha.com/ja/account/recharge.md) を参照してください。累計チャージ額が VIP ランクに達すると、以降のチャージごとに一定の割合でポイントが付与されます。
## 状況によって価格が変わるタイプ
- **reCAPTCHA v2 画像認識**(`ReCaptchaV2Classification`): 1x1 の小さな画像と、3x3・4x4 の大きな画像で価格が異なります。詳しくは [reCAPTCHA v2 画像認識](https://docs.yescaptcha.com/ja/tasks/recaptcha-classification.md) を参照してください。
- **hCaptcha 画像認識**(`HCaptchaClassification`): 対象が見つからなかった場合(結果が空)は課金されません。
## 認識ミスを報告した場合の返金
画像認識の結果が誤っていた場合は、[report](https://docs.yescaptcha.com/ja/api/report.md) で報告できます。条件を満たすものは返金されます。
- 対象は次の 5 種類の画像認識タイプのみです: `FunCaptchaClassification`、`HCaptchaClassification`、`ReCaptchaV2Classification`、`AwsClassification`、`bCaptchaClassification`。
- タスク作成後 **1 時間以内**に報告してください。同じタスクは 1 回だけ対象になります。
- 即時には返金されず、**約 24 時間後**にまとめて精算されます。
- 精算時には、同じ期間に同じ問題文を解いた他のユーザーと比較します。報告された失敗率が同期間の水準を明らかに上回る場合は、同期間の失敗率に基づいて返金します。
- 成功と失敗の両方を正直に報告してください。失敗だけを報告した場合、その報告は同期間の参考値として使われず、失敗率は作成したすべてのタスクをもとに計算されます。
- 精算結果に疑問がある場合は、[サポートに問い合わせ](https://docs.yescaptcha.com/ja/help/contact.md)て異議を申し立てられます。
token を返すタイプ(reCAPTCHA、hCaptcha、Turnstile など)は、通過できるかどうかを対象サイトが判定するため、報告しても返金されません。
## 課金されない場合
| 状況 | 返される内容 |
| --- | --- |
| パラメータの誤り、存在しないタイプ、`clientKey` の誤り | 対応するエラーコード |
| 残高が 10 ポイント以下 | `ERROR_ZERO_BALANCE` |
| 同時実行数の上限超過 | `ERROR_THREADS_MAXIMUM`。[同時実行数の上限と自動一時停止](https://docs.yescaptcha.com/ja/api/rate-limits.md) を参照 |
| 自動一時停止中 | `ERROR_IP_BLOCKED_5MIN` |
| 無効と判定済みの sitekey またはドメイン(キャッシュ期間中) | 元のエラーコード(`cached: true` 付き) |
| 解析の失敗、タイムアウト | 課金済みのポイントが自動的に返金される |
## 収益分配と報酬
- 他の人のソフトウェアや拡張機能を使うと、タスクに開発者 ID が付く場合があります。開発者は収益の分配を受けますが、あなたの課金額は変わりません。自分でソフトウェアを開発している場合は、[開発者収益分配](https://docs.yescaptcha.com/ja/account/developer.md) を参照してください。
- 他のユーザーを招待する場合は、[紹介報酬](https://docs.yescaptcha.com/ja/account/referral.md) を参照してください。
---
# リクエストとレスポンス
> YesCaptcha API の共通ルール。POST JSON、clientKey による認証、errorId のレスポンス形式、同期・非同期タスク、5 秒ごとのポーリング、110 秒のタイムアウト、結果の保持期間（約 10 分）、Accept-Language によるメッセージ言語。
Source: https://docs.yescaptcha.com/ja/api/overview/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/overview/
すべてのメソッドは HTTPS `POST` で JSON を送信し（`/useragent` のみ `GET`）、リクエストボディの `clientKey` で認証し、JSON を返します。`errorId` が 0 なら成功、1 なら失敗で `errorCode` が付きます。キャプチャの認識は 2 段階です。`createTask` でタスクを作成し、`getTaskResult` を 5 秒ごとに呼び出して結果を取得します。同期タイプは `createTask` が結果を直接返します。
## リクエスト
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY", "task": {"type": "ImageToTextTaskOcrBase", "body": "BASE64_IMAGE"}}'
```
- エンドポイント：`https://api.yescaptcha.com`（グローバル）または `https://cn.yescaptcha.com`（中国）。詳しくは[エンドポイント](https://docs.yescaptcha.com/ja/getting-started/endpoints.md)を参照してください。
- リクエストボディは JSON で、`Content-Type: application/json` ヘッダーを付け、6 MB 以内にします。JSON にコメントは書けません。
- すべてのリクエストに `clientKey` を含めます。ダッシュボードに表示される値をそのまま全体コピーしてください。
> **注意:** Python の requests では `json=data` を使い、`data=data` は使わないでください。後者はフォームとして送信されるため、`ERROR_TASK_ABSENT` または `ERROR_REQUIRED_FIELDS` が返ります。
## レスポンス
成功：
```json
{
"errorId": 0,
"taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```
失敗：
```json
{
"errorId": 1,
"errorCode": "ERROR_ZERO_BALANCE",
"errorDescription": "帐户余额不足"
}
```
| フィールド | 説明 |
| --- | --- |
| `errorId` | 0 は成功、1 は失敗 |
| `errorCode` | 失敗時のエラーコード。意味と対処法は[エラーコード](https://docs.yescaptcha.com/ja/api/errors.md)を参照 |
| `errorDescription` | 失敗理由の説明文 |
| `taskId` | タスク ID |
| `status` | `processing`（処理中）または `ready`（完了） |
| `solution` | 認識結果。フィールドはタスクタイプによって異なります（各タスクタイプのページを参照） |
結果の判定には `errorId` と `errorCode` を使い、`errorDescription` の文言は解析しないでください。変更される可能性があります。
## 同期と非同期
| | 非同期 | 同期 |
| --- | --- | --- |
| 対象タイプ | token を返すタイプ（reCAPTCHA、hCaptcha、Turnstile、FunCaptcha）、Cloudflare チャレンジページ、`ImageToTextTask`、`ImageToTextTaskM1` | 画像認識（名前が `Classification` で終わるもの）、`ImageToTextTaskOcrBase`、`ImageToTextTaskMuggle` |
| `createTask` の戻り値 | `taskId` | `status: "ready"` と `solution` |
| 結果の取得方法 | `getTaskResult` を 5 秒ごとに呼び出す | 追加の問い合わせは不要 |
各タイプがどちらに該当するかは、[タスクタイプと料金](https://docs.yescaptcha.com/ja/tasks.md)の「返却方式」列で確認できます。
## ポーリング
1. `createTask` が `taskId` を返したら、5 秒待ってから `getTaskResult` を呼び出します。
2. `status: "processing"` が返ったらさらに 5 秒待って再試行します。`status: "ready"` が返ったら、結果は `solution` に入っています。
3. `errorId: 1` が返ったらこのタスクのポーリングを止め、`errorCode` に従って対処します。
- 同じ `taskId` への 5 秒以内の重複した問い合わせには、すぐに `processing` が返ります。間隔を短くしても結果は早くなりません。
- タスクの処理時間は最長でおよそ 110 秒です（一部のタイプは 180〜220 秒）。超過すると `ERROR_TASK_TIMEOUT` が返り、ポイントは自動で返金されます。
- 結果はサーバー側で約 10 分間保持されます。その後 `taskId` は無効になり、問い合わせると `ERROR_TASKID_INVALID` が返ります。
- 結果の問い合わせは課金されません。課金されるのはタスク作成時のみです。
## メッセージの言語
自動一時停止、無効パラメーターのキャッシュ、ポーリング停止に関するメッセージでは、`errorDescription` の言語がリクエストヘッダー `Accept-Language` に従います。`zh` で始まる場合は中国語、それ以外の言語は英語を返し、このヘッダーがない場合は中国語と英語の両方を返します。その他のエラーコードの説明には影響しません。
## 次のステップ
- [createTask でタスクを作成](https://docs.yescaptcha.com/ja/api/create-task.md)
- [getTaskResult で結果を取得](https://docs.yescaptcha.com/ja/api/get-task-result.md)
- [同時実行数の上限と自動一時停止](https://docs.yescaptcha.com/ja/api/rate-limits.md)：エラーが多すぎると数分間一時停止されます
---
# createTask タスクの作成
> POST /createTask でキャプチャ認識タスクを作成します。リクエストパラメータ（clientKey、task、softID）、検証の順序、非同期タイプは taskId を返し、同期タイプは solution を直接返すこと、残高が 10 ポイントを超えている必要があることを説明します。
Source: https://docs.yescaptcha.com/ja/api/create-task/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/create-task/
`createTask` は認識タスクを作成します。`task.type` で、どの種類のキャプチャを認識するかを指定します。非同期タイプは `taskId` を返すので、その後 [getTaskResult](https://docs.yescaptcha.com/ja/api/get-task-result.md) で結果を取得します。同期タイプは結果を直接返します。
> **ノート:** タスクの作成に成功した時点で課金されます。タスクを作成するには、残高が 10 ポイントを超えている必要があります。認識に失敗したタスクやタイムアウトしたタスクは自動的に返金されます。
- POST `https://api.yescaptcha.com/createTask` (グローバルエンドポイント)
- POST `https://cn.yescaptcha.com/createTask` (中国エンドポイント)
## リクエストパラメータ
| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `clientKey` | string | はい | アカウントのキー。[yescaptcha.com](https://yescaptcha.com/) のダッシュボードでコピーします |
| `task` | object | はい | タスクオブジェクト。`type` が必須です。その他のフィールドはタスクタイプに応じて指定します。各タスクタイプのページを参照してください |
| `softID` | integer | いいえ | 開発者 ID。開発したソフトウェアを他の人が使う場合に指定すると、収益分配を受け取れます。[開発者収益分配](https://docs.yescaptcha.com/ja/account/developer.md) を参照してください |
## リクエスト例
画像キャプチャを認識する（同期）:
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "ImageToTextTaskOcrBase",
"body": "BASE64_IMAGE"
}
}
```
reCAPTCHA v2 の token を取得する（非同期）:
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}
```
各タスクタイプの `task` フィールドは、[タスクタイプと料金](https://docs.yescaptcha.com/ja/tasks.md) 配下の各ページを参照してください。
## レスポンス
非同期タイプ:
```json
{
"errorId": 0,
"taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```
`taskId` を控えておき、5 秒後から `getTaskResult` で問い合わせを始めます。
同期タイプ:
```json
{
"errorId": 0,
"status": "ready",
"taskId": "2376919c-1863-11ec-a012-94e6f7355a0b",
"solution": {
"text": "LMResm"
}
}
```
失敗:
```json
{
"errorId": 1,
"errorCode": "ERROR_TASK_NOT_SUPPORTED",
"errorDescription": "任务类型不正确或不受支持"
}
```
## 検証の順序
サーバーは次の順序でリクエストを検証し、最初に見つかった問題に対応するエラーコードを返します。この場合、課金されません。
1. リクエストボディが正しい JSON である: `ERROR_REQUEST_FORMATS`
2. `clientKey` が含まれている: `ERROR_REQUIRED_FIELDS`
3. `clientKey` が存在する: `ERROR_KEY_DOES_NOT_EXIST`
4. 自動一時停止されていない: `ERROR_IP_BLOCKED_5MIN`（[同時実行数の上限と自動一時停止](https://docs.yescaptcha.com/ja/api/rate-limits.md) を参照）
5. 残高が 10 ポイントを超えている: `ERROR_ZERO_BALANCE`
6. `task` が含まれている: `ERROR_TASK_ABSENT`
7. `task.type` が存在する: `ERROR_TASK_NOT_SUPPORTED`
8. 必須フィールドがすべて揃っている: `ERROR_REQUIRED_FIELDS`（不足しているフィールドは `errorDescription` に記載されます）
9. 画像系タスクの画像が正しい: `ERROR_ZERO_CAPTCHA_FILESIZE`、`ERROR_IMAGE_TYPE_NOT_SUPPORTED` など
## 完全な例
タスクを作成して結果をポーリングする（非同期タイプ）:
**curl**
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}'
# 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"}'
```
**Python**
solve.py
```python
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": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})
print(solution["gRecaptchaResponse"])
```
**Node.js**
solve.mjs
```js
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: "NoCaptchaTaskProxyless",
websiteURL: "https://www.google.com/recaptcha/api2/demo",
websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
console.log(solution.gRecaptchaResponse);
```
---
# getTaskResult 結果の取得
> POST /getTaskResult は非同期タスクの結果を取得します。5 秒ごとに問い合わせ、processing の間は待機、ready になったら solution を読み取り、エラーが返ったらポーリングを止めます。タスクの処理時間は最長で約 110 秒、結果の保持期間は約 10 分で、問い合わせに課金はありません。
Source: https://docs.yescaptcha.com/ja/api/get-task-result/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/get-task-result/
`getTaskResult` は非同期タスクの結果を取得します。タスクの作成後、5 秒ごとに呼び出してください。`processing` が返ったら待機を続け、`ready` が返ったら結果は `solution` に入っています。エラーが返ったらポーリングを止めます。問い合わせに課金はなく、何回呼び出しても同じです。
- POST `https://api.yescaptcha.com/getTaskResult` (グローバルエンドポイント)
- POST `https://cn.yescaptcha.com/getTaskResult` (中国エンドポイント)
## リクエストパラメータ
| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `clientKey` | string | はい | タスク作成時に使ったものと同じ `clientKey` |
| `taskId` | string | はい | [createTask](https://docs.yescaptcha.com/ja/api/create-task.md) が返したタスク ID |
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```
## レスポンス
| 状況 | レスポンス | 対応 |
| --- | --- | --- |
| 処理中 | `errorId` が 0、`status` が `processing` | 5 秒後に再度問い合わせる |
| 完了 | `errorId` が 0、`status` が `ready`、結果は `solution` に入っている | `solution` を読み取る。フィールドは各タスクタイプのページを参照 |
| 認識失敗 | `errorId` が 1、`errorCode` が `ERROR_CAPTCHA_UNSOLVABLE` | 自動的に返金済み。新しくタスクを作成できる |
| タイムアウト | `errorId` が 1、`errorCode` が `ERROR_TASK_TIMEOUT` | 自動的に返金済み。新しくタスクを作成できる |
| タスクが存在しない、または期限切れ | `errorId` が 1、`errorCode` が `ERROR_TASKID_INVALID` | この `taskId` の問い合わせを止める |
完了時の例（reCAPTCHA v2）:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
}
}
```
## ルール
- **5 秒ごとに問い合わせてください。** 同じ `taskId` への 5 秒以内の再問い合わせには、すぐに `processing` が返ります。頻繁に問い合わせても結果は早くなりません。
- **タスクの処理時間は最長で約 110 秒です**（一部のタイプは 180〜220 秒）。超過すると `ERROR_TASK_TIMEOUT` が返り、自動的に返金されます。プログラム側の待機の上限は 3 分程度に設定することをお勧めします。
- **結果の保持期間は約 10 分です。** その後は `taskId` が無効になり、`ERROR_TASKID_INVALID` が返ります。結果は取得したらすぐに使用してください。token 自体の有効期間はさらに短くなります（reCAPTCHA は約 120 秒）。
- **エラーが返ったら止めてください。** `errorId: 1` が返った後に同じ `taskId` を問い合わせ続けても結果は変わりません。終了済みの同じタスクを 3 回目に問い合わせると、`errorDescription` の末尾にポーリングを止めるよう促すメッセージが付きます。`ERROR_TASKID_INVALID` は、[自動一時停止](https://docs.yescaptcha.com/ja/api/rate-limits.md)の対象となるエラー回数に含まれます（同じ ID は最初の 1 回のみ数えます）。
- タスクを作成したエンドポイントと同じエンドポイントで問い合わせてください。
- `getTaskResult` は自動一時停止の影響を受けません。一時停止の前に作成したタスクは、これまでどおり問い合わせできます。
---
# getBalance 残高の照会
> POST /getBalance でアカウントの残高(ポイント、1,000 ポイント = ¥1)と、開発者収益分配・紹介報酬の残高を照会します。課金されないため、clientKey の確認にも使えます。
Source: https://docs.yescaptcha.com/ja/api/get-balance/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/get-balance/
`getBalance` はアカウントの残りポイント(1,000 ポイント = ¥1)と、開発者収益分配および紹介報酬の残高(元)を返します。課金されないため、`clientKey` が正しいかどうかの確認によく使われます。
- POST `https://api.yescaptcha.com/getBalance` (グローバルエンドポイント)
- POST `https://cn.yescaptcha.com/getBalance` (中国エンドポイント)
## リクエストパラメータ
| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `clientKey` | string | はい | アカウントの clientKey |
```json
{
"clientKey": "YOUR_CLIENT_KEY"
}
```
## レスポンス
```json
{
"errorId": 0,
"balance": 1071810,
"softBalance": 36.0098,
"inviteBalance": 0,
"inviteBy": 0
}
```
| フィールド | 型 | 説明 |
| --- | --- | --- |
| `balance` | integer | アカウントの残高。単位はポイント(1,000 ポイント = ¥1)。タスクを作成するには 10 ポイントを超えている必要があります |
| `softBalance` | number | 開発者収益分配の残高。単位は元。[開発者収益分配](https://docs.yescaptcha.com/ja/account/developer.md)を参照してください |
| `inviteBalance` | number | 紹介報酬の残高。単位は元。[紹介報酬](https://docs.yescaptcha.com/ja/account/referral.md)を参照してください |
| `inviteBy` | integer | あなたを招待したユーザーのユーザー ID。いない場合は 0 |
| `keyQuotaRemaining` | integer | この `clientKey` の今期の残り利用上限。単位はポイント。上限を設定した `clientKey` にのみ含まれ、その場合 `balance` はアカウント残高と残り上限のうち小さいほうになります。上限を設定していない場合、このフィールドは含まれません |
`clientKey` が正しくない場合は `ERROR_KEY_DOES_NOT_EXIST` が返ります。`clientKey` に IP ホワイトリストが設定されていて、リクエスト元の IP がその中にない場合は `ERROR_KEY_IP_NOT_ALLOWED` が返ります。`getBalance` は[自動一時停止](https://docs.yescaptcha.com/ja/api/rate-limits.md)の影響を受けます。一時停止中は `ERROR_IP_BLOCKED_5MIN` が返ります。
## 例
**curl**
get-balance.sh
```bash
#!/usr/bin/env bash
# Check the balance. getBalance is free and is a quick way to verify your clientKey
set -euo pipefail
curl -s https://api.yescaptcha.com/getBalance \
-H 'Content-Type: application/json' \
-d "{\"clientKey\": \"${YESCAPTCHA_CLIENT_KEY}\"}"
echo
```
**Python**
get_balance.py
```python
"""Check the balance. getBalance is free and is a quick way to verify your clientKey."""
import os
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
r = requests.post(
"https://api.yescaptcha.com/getBalance",
json={"clientKey": CLIENT_KEY},
timeout=30,
)
data = r.json()
if data.get("errorId"):
# e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
print("error:", data.get("errorCode"), data.get("errorDescription"))
else:
print("balance (points):", data["balance"])
```
**Node.js**
get-balance.mjs
```js
// Check the balance. getBalance is free and is a quick way to verify your clientKey. Node.js 18+
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;
const res = await fetch('https://api.yescaptcha.com/getBalance', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY }),
});
const data = await res.json();
if (data.errorId) {
// e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
console.log('error:', data.errorCode, data.errorDescription);
} else {
console.log('balance (points):', data.balance);
}
```
---
# getSoftID 開発者 ID の照会
> POST /getSoftID で開発者 ID(softID)と累計の収益分配額を照会します。他のユーザーがあなたのソフトウェアを使うときの createTask リクエストに softID を含めると、収益分配を受け取れます。
Source: https://docs.yescaptcha.com/ja/api/get-soft-id/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/get-soft-id/
`getSoftID` は、開発者 ID(`softID`)と累計の開発者収益分配額(元)を返します。開発したソフトウェアやプラグインを他のユーザーが使うとき、そのユーザーの `createTask` リクエストにこの ID を含めると、ユーザーの利用額に応じた収益分配を受け取れます。分配ルールと出金については [開発者収益分配](https://docs.yescaptcha.com/ja/account/developer.md) を参照してください。
- POST `https://api.yescaptcha.com/getSoftID` (グローバルエンドポイント)
- POST `https://cn.yescaptcha.com/getSoftID` (中国エンドポイント)
## リクエストパラメータ
| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `clientKey` | string | はい | 自分自身(開発者)の `clientKey` |
```json
{
"clientKey": "YOUR_CLIENT_KEY"
}
```
## レスポンス
```json
{
"errorId": 0,
"softID": 3,
"balance": 0.004
}
```
| フィールド | 型 | 説明 |
| --- | --- | --- |
| `softID` | integer | 開発者 ID |
| `balance` | number | 累計の開発者収益分配額。単位は元 |
## 使い方
ソフトウェアを使うユーザーが送る `createTask` リクエストに、トップレベルのフィールド `softID` を追加します。
```json
{
"clientKey": "THE_USERS_CLIENT_KEY",
"task": {
"type": "ImageToTextTaskOcrBase",
"body": "BASE64_IMAGE"
},
"softID": 3
}
```
> **注意:** `softID` はリクエストボディのトップレベルに、`clientKey` や `task` と同じ階層で、大文字・小文字を一致させて指定してください。`task` の中に入れても有効になりません。
`clientKey` は利用者自身のキーで、課金されるのは利用者のポイントです。`softID` はあなたの開発者 ID です。
---
# report 結果の報告
> POST /report でタスクの認識結果が正しかったかを報告します。成功も失敗も正直に報告してください。画像認識タイプはタスク作成後 1 時間以内に失敗を報告すると、約 24 時間後に返金が精算されます。
Source: https://docs.yescaptcha.com/ja/api/report/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/report/
`report` は、タスクの認識結果が正しかったかどうかを私たちに伝えるためのものです。**成功も失敗も報告してください。** 画像認識タイプで「誤り」と報告すると、条件を満たすものは約 24 時間後にポイントが返金されます。報告された結果は、認識の評価と改善にも使われます。
- POST `https://api.yescaptcha.com/report` (グローバルエンドポイント)
- POST `https://cn.yescaptcha.com/report` (中国エンドポイント)
## リクエストパラメータ
| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `id` | array of string | はい | タスク ID のリスト。一度に複数を報告できます |
| `isSuccess` | boolean | はい | `true` は認識が正しい、`false` は認識が誤り |
`clientKey` は不要です。タスク ID だけでタスクを特定できます。
```json
{
"id": ["610ff5e0-68eb-11ef-95a6-22e70a0b794d", "65b88c06-68eb-11ef-8e9a-52540023ccb3"],
"isSuccess": false
}
```
## レスポンス
```json
{
"errorId": 0,
"status": "success"
}
```
## 正直に報告してください
報告は、返金の精算にも、認識の評価と改善にも使われます。実際の結果のとおりに報告してください。
- 認識が正しいタスクは `isSuccess: true`、誤りは `false` で報告します。失敗だけを報告する、または正誤にかかわらずすべて失敗として報告する場合、その報告は統計や精算の参考にされません。
- 失敗率は、その期間に作成したすべてのタスクをもとに計算され、報告したタスクだけが対象ではありません。失敗を多く報告しても返金は増えません。失敗率が同期間の水準より明らかに高い場合は、同期間の失敗率で返金されます。
- 1 回の認証で複数の画像を使い（例：FunCaptcha は 1 回で 5 ラウンドを選択）、どれが誤りだったか分からない場合は、そのグループのタスクをまとめて失敗として報告できます。認証が通ったときも、同様にそのグループをまとめて成功として報告します。
## 失敗報告による返金
- 返金の対象になるのは、次の 5 種類の画像認識タイプのみです：`FunCaptchaClassification`、`HCaptchaClassification`、`ReCaptchaV2Classification`、`AwsClassification`、`bCaptchaClassification`。
- タスク作成後 **1 時間以内**の報告のみが対象で、同じタスクが返金されるのは 1 回だけです。
- 即時ではなく、**約 24 時間後**にまとめて精算されます。
- 精算時には、同じ期間・同じ問題文の他のユーザーと比較します。報告された失敗率が同期間の水準より明らかに高い場合は、同期間の失敗率で返金されます。
- 精算に疑問がある場合は、[サポートに問い合わせ](https://docs.yescaptcha.com/ja/help/contact.md)て申し立てできます。
token を返すタイプ（reCAPTCHA、hCaptcha、Turnstile、FunCaptcha など）は、token が通るかどうかを対象サイトが判定するため、報告しても返金されません。課金ルールのまとめは [課金と返金](https://docs.yescaptcha.com/ja/getting-started/billing.md) を参照してください。
---
# useragent（UA の取得）
> GET https://api.yescaptcha.com/useragent は、現在推奨されるブラウザの User-Agent をプレーンテキストで返します。hCaptcha タスクの userAgent フィールドで使用できるのはこの値だけです。
Source: https://docs.yescaptcha.com/ja/api/useragent/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/useragent/
`/useragent` は、現在推奨されるブラウザの User-Agent をプレーンテキストで返します。`clientKey` は不要で、課金されません。[hCaptcha](https://docs.yescaptcha.com/ja/tasks/hcaptcha.md) タスクの `userAgent` フィールドで使用できるのはこの値だけです。対象サイトにアクセスするときもこの値を使うと、token が通りやすくなります。
- GET `https://api.yescaptcha.com/useragent` (グローバルエンドポイント)
- GET `https://cn.yescaptcha.com/useragent` (中国エンドポイント)
## 例
```bash
curl -s https://api.yescaptcha.com/useragent
```
レスポンス（2026-10-15 時点の値。ブラウザのバージョン更新に合わせて変わります）:
```text
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36
```
> **ノート:** 返される値は随時更新されます。コードに固定せず、起動時に一度取得してください。
- 認識結果に `userAgent` が含まれている場合は、token を送信するときに結果の値を使ってください。
---
# エラーコード
> YesCaptcha API の全エラーコードの意味と対処方法を、リクエスト形式、アカウントと残高、同時実行と一時停止、タスク結果、サイトパラメータ、画像、プロキシ、サーバー側に分けて説明します。エラーを返したリクエストは課金されません。
Source: https://docs.yescaptcha.com/ja/api/errors/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/errors/
API がエラーを返すときは `errorId: 1` となり、`errorCode` にエラーコード、`errorDescription` に説明文が入ります。エラーを返したリクエストは課金されません。タスク作成時のエラーは課金されず、作成後に認識が失敗した場合やタイムアウトした場合は自動的に返金されます。
> **ヒント:** プログラムでは `errorCode` で判定してください。`errorDescription` の文言は変更されることがあるため、判定に使わないでください。
```json
{
"errorId": 1,
"errorCode": "ERROR_ZERO_BALANCE",
"errorDescription": "帐户余额不足"
}
```
## 対処方針
1. **パラメータ系のエラー**（リクエスト形式、clientKey、タスクタイプ、サイトパラメータ、画像）は、そのまま再送しても結果は変わりません。先にリクエストを修正してください。
2. **認識の失敗とタイムアウト**（`ERROR_CAPTCHA_UNSOLVABLE`、`ERROR_TASK_TIMEOUT`）は、新しいタスクを作成して再試行できます。
3. エラーが出たら、その `taskId` の**ポーリングを停止**してください。同じリクエストをそのまま高頻度で再送しないでください。
4. 「自動一時停止にカウント」と表示されているエラーは、同じ `clientKey` で 1 分間に 100 回発生すると、タスクの作成が 5 分間一時停止されます。「キャッシュ」と表示されているエラーはカウントされませんが、キャッシュ期間中は同じリクエストに対して元のエラーがそのまま返されます。詳しくは [同時実行数の上限と自動一時停止](https://docs.yescaptcha.com/ja/api/rate-limits.md) を参照してください。
## エラーコード一覧
### リクエスト形式
| エラーコード | 意味 | 対処方法 |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | 必須フィールドが不足しています(`clientKey` や、タスクタイプで必要な `websiteURL` / `websiteKey` など)。またはリクエストボディが JSON ではありません | タスクタイプのページに記載されている不足フィールドを追加し、`POST` と `Content-Type: application/json` で JSON を送信してください |
| `ERROR_REQUEST_FORMATS` (自動一時停止の対象) | リクエストボディが有効な JSON ではありません | 文字列を連結せず、JSON ライブラリでボディを生成してください。JSON に `//` コメントを含めることはできません |
| `ERROR_TASK_ABSENT` (自動一時停止の対象) | `createTask` の呼び出しに `task` フィールドがありません | タスクのパラメーターを `task` オブジェクトに入れてください。Python requests では `data=data` ではなく `json=data` を使用してください |
| `ERROR_TASK_NOT_SUPPORTED` (自動一時停止の対象) | `task.type` のスペルが間違っているか、そのタイプがすでに廃止されています | 「タスクタイプと料金」からタイプ名をコピーしてください。大文字と小文字は区別されます |
| `ERROR_PAGE_NOT_FOUND` | リクエストされたパスが存在しません | エンドポイントの URL(例: `https://api.yescaptcha.com/createTask`)を確認してください。メソッド名は大文字と小文字が区別されます |
| `ERROR_BAD_REQUEST` | リクエストを処理できません。多くの場合、HTTP メソッドの誤り(POST ではなく GET を使用)またはパラメーター値が無効であることが原因です | `POST` で JSON を送信し、パラメーターの型と値を確認してください |
| `ERROR_ILLEGAL_PARAMETERS` | パラメータの値が無効です。Cloudflare チャレンジページでよく発生します：`websiteURL` が公開された `http://` / `https://` の URL ではない、`postData` がオブジェクトではない、または `requiredCookies` が文字列の配列ではない場合（createTask が返し、課金されません）。あるいは、プロキシ経由で対象ドメインを名前解決できなかった場合（getTaskResult が返し、自動的に返金されます） | タスクタイプのページにあるパラメータ表に従って値を修正してください。ドメインを名前解決できなかった場合は、URL のスペルと、プロキシがそのサイトにアクセスできるかを確認してください |
### アカウントと残高
| エラーコード | 意味 | 対処方法 |
| --- | --- | --- |
| `ERROR_KEY_DOES_NOT_EXIST` (自動一時停止の対象) | `clientKey` が存在しません。コピー時に文字が増減した、またはダッシュボードでキーがリセットされた可能性があります | yescaptcha.com のダッシュボードからキーをもう一度コピーしてください。スペースや改行を含めないでください |
| `ERROR_KEY_EXPIRED` (自動一時停止の対象) | `clientKey` の有効期限が切れています（createTask と getBalance で返され、課金されません）。次のいずれかです。長期間使用されなかったため、アカウント保護のためにシステムが有効期限を設定した場合（期限前にメールで通知されます）、またはこの `clientKey` に設定した有効期限が過ぎた場合 | yescaptcha.com のダッシュボードにサインインします。長期間未使用で期限切れになった場合は、新しい `clientKey` を生成してください。残高は新しい `clientKey` に自動的に移行されます。有効期限を設定していた場合は、期限を変更するか、別の `clientKey` を使用してください。その後、プログラム内の `clientKey` を新しいものに更新してください |
| `ERROR_KEY_IP_NOT_ALLOWED` | この `clientKey` には IP 許可リストが設定されており、リクエスト元の IP がリストに含まれていません（createTask と getBalance で返されます。課金されず、自動一時停止の回数にも含まれません） | yescaptcha.com のダッシュボードにサインインし、リクエストを送信しているマシンのパブリック IP をこの `clientKey` の許可リストに追加するか、別の `clientKey` を使用してください。複数のマシンから API を呼び出す場合は、すべてのマシンのパブリック IP を追加してください（ここでの IP は YesCaptcha API を呼び出す側の IP であり、タスクパラメータ内のプロキシではありません） |
| `ERROR_KEY_QUOTA_EXCEEDED` | この `clientKey` には利用上限が設定されており、現在の期間の残り上限がこのタスクの課金額に足りません（createTask で返されます。課金されず、自動一時停止の回数にも含まれません）。上限は実際に課金されたポイントで計算され、失敗またはタイムアウトしたタスクで返金されたポイントは上限に戻ります | yescaptcha.com のダッシュボードにサインインしてこの `clientKey` の上限を引き上げるか、次の期間まで待つか（北京時間で毎日、毎週月曜日、または毎月 1 日にリセットされます。一回限りの上限はリセットされません）、別の `clientKey` を使用してください。この `clientKey` の残り上限は `getBalance` で取得できます（`keyQuotaRemaining`） |
| `ERROR_ZERO_BALANCE` | 残高が不足しています。タスクを作成するには、残高が 10 ポイントを超えている必要があります | チャージしてから再試行してください。`getBalance` で残高を確認できます |
### 同時実行数と一時停止
| エラーコード | 意味 | 対処方法 |
| --- | --- | --- |
| `ERROR_THREADS_MAXIMUM` (場合により自動一時停止の対象) | このアカウントで、このタイプのタスクが処理中の数が多すぎます。レスポンスの `limit` は現在の上限です。このリクエストは処理されず、課金もされません | 送信済みのリクエストが返るのを待つか、1〜2 秒待ってから再試行してください。同時に結果を待つリクエストの数を制限してください |
| `ERROR_IP_BLOCKED_5MIN` | この `clientKey` は短時間にエラーが多発したため、自動一時停止されました。`retryAfter` は残り秒数、`blockReason` は一時停止の原因となったエラーです | `blockReason` に従ってリクエストを修正し、`retryAfter` 秒待ってください。一時停止中にリクエストを送信しても、停止時間は延長されません |
| `ERROR_NO_SLOT_AVAILABLE` | 認識サービスが一時的に混雑しています。createTask が返した場合は課金されません。キューで長く待機したタスクも getTaskResult からこのエラーが返され、自動的に返金されます | 数秒待ってから、もう一度タスクを作成してください |
### タスクと結果
| エラーコード | 意味 | 対処方法 |
| --- | --- | --- |
| `ERROR_TASKID_INVALID` (自動一時停止の対象) | `taskId` が存在しない、有効期限が切れている(結果は約 10 分間保持されます)、別の `clientKey` のものである、または別のエンドポイントで作成されたものです | このタスクのポーリングを停止してください。作成時と同じエンドポイントと `clientKey` で照会してください |
| `ERROR_TASK_TIMEOUT` | タスクが制限時間内(通常は 110 秒)に完了しませんでした。ポイントは自動的に返金されました | 新しいタスクを作成してください。タイムアウトが続く場合は、同じキャプチャ向けの別のタスクタイプを試してください |
| `ERROR_CAPTCHA_UNSOLVABLE` | 今回はキャプチャを認識できなかったため、ポイントを返金しました。自動一時停止の対象にはなりません | タスクを作り直してください。失敗が続く場合は `websiteURL`、`websiteKey` などのパラメータを確認するか、同じ種類のキャプチャ向けの別のタスクタイプを試してください |
| `ERROR_SETTLEMENT_FAILED` (自動一時停止の対象) | 精算時に残高が不足していたため、結果は返されませんでした | チャージしてからタスクを作り直してください |
| `ERROR_NO_SUCH_CAPCHA_ID` | タスクはすでに無効です | このタスクのポーリングを止めて、新しく作り直してください |
| `ERROR_RECAPTCHA_TIMEOUT` | キャプチャの認識がタイムアウトしたため、ポイントを返金しました | タスクを作り直してください |
### 対象サイトのパラメーター
| エラーコード | 意味 | 対処方法 |
| --- | --- | --- |
| `ERROR_RECAPTCHA_INVALID_SITEKEY` (キャッシュ済み、一時停止の対象外) | `websiteKey` が無効です | ページから sitekey をもう一度探してください（パラメータの調べ方のガイドを参照）。同一のリクエストはキャッシュ期間中、このエラーがそのまま返され、レスポンスに `cached: true` が付きます |
| `ERROR_RECAPTCHA_INVALID_DOMAIN` (キャッシュ済み、一時停止の対象外) | `websiteURL` のドメインが `websiteKey` と一致しません | `websiteURL` にはキャプチャが表示されるページのアドレスを指定してください |
| `ERROR_INVALID_KEY_TYPE` (キャッシュ済み、一時停止の対象外) | sitekey が別の種類のキャプチャのものです。たとえば v3 のキーを v2 のタスクタイプで使っています | まずキャプチャの種類を判別し（「キャプチャの種類を判別する」を参照）、対応するタスクタイプを選んでください。v2 のインビジブル版では `isInvisible` を指定します |
| `ERROR_DOMAIN_NOT_ALLOWED` (キャッシュ済み、一時停止の対象外) | このサイトは現在サポートされていません | 同じ種類のキャプチャ向けの別のタスクタイプを試すか、サポートにお問い合わせください |
| `ERROR_HIGH_DEMAND_DOMAIN` (自動一時停止の対象) | このサイトは現在サポートされていません | このサイトのタスク送信を止めて、サポートにお問い合わせください |
| `ERROR_FAILED_LOADING_WIDGET` | 指定されたパラメータではキャプチャを読み込めませんでした | `websiteURL` と `websiteKey` を確認してください。独自のプロキシを使うタスクタイプでは、プロキシから対象サイトにアクセスできるかも確認してください |
### 画像
| エラーコード | 意味 | 対処方法 |
| --- | --- | --- |
| `ERROR_ZERO_CAPTCHA_FILESIZE` (自動一時停止の対象) | 画像が空、または小さすぎます | Base64 データが欠けていないか、`data:image/...;base64,` プレフィックスが付いていないか確認してください |
| `ERROR_TOO_BIG_CAPTCHA_FILESIZE` (自動一時停止の対象) | 画像が大きすぎます | 画像を圧縮または縮小してから送信してください。リクエストボディ全体を 6 MB 未満に収める必要があります |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` (自動一時停止の対象) | 画像形式がサポートされていないか、このタスクタイプで処理できない画像です。1 回発生すると 30 分間、クライアントキーが一時停止されます | JPG または PNG を使い、画像がタスクタイプに合っているか確認してください。たとえば reCAPTCHA の画像認識では 100x100、300x300、450x450 のいずれかが必要です |
| `ERROR_ILLEGAL_IMAGE` (自動一時停止の対象) | 画像サイズがこのタスクタイプの要件を満たしていません | タスクタイプのページの説明に従って画像サイズを調整してください |
| `ERROR_PARSE_IMAGE_FAIL` | 画像をデコードできませんでした。Base64 が途中で切れている、またはプレフィックスが付いている場合によく起こります | Base64 エンコードを確認し、`data:` プレフィックスと改行を取り除いてください |
| `ERROR_UNKNOWN_QUESTION` | `question` が間違っているか、この問題文にはまだ対応していません | タスクタイプのページにある問題文の一覧と照らして確認してください。未対応の問題文はサポートにお問い合わせください。新しい問題文は通常 3 営業日以内に対応します |
| `ERROR_UNKNOW_450x450_QUESTION` | この問題文は 4×4（450x450）の画像にはまだ対応していません | ページ上でチャレンジを再読み込みして、別の問題に切り替えてください |
### プロキシ
| エラーコード | 意味 | 対処方法 |
| --- | --- | --- |
| `ERROR_PROXY_CONNECT_REFUSED` | プロキシが接続を拒否しました | プロキシのアドレス、ポート、プロトコルを確認し、外部からの接続を許可していることを確かめてください（127.0.0.1 などのローカルアドレスは不可） |
| `ERROR_PROXY_CONNECT_TIMEOUT` | プロキシへの接続がタイムアウトしました | より安定したプロキシに変更してください |
| `ERROR_PROXY_READ_TIMEOUT` | プロキシ経由のデータ読み取りがタイムアウトしました | より高速なプロキシに変更してください |
| `ERROR_PROXY_BANNED` | プロキシが利用できないか、その IP が対象サイトにブロックされています | 別のプロキシに変更してください |
| `ERROR_PROXY_INCORRECT` | プロキシのパラメータの形式が正しくありません | `proxyType`、`proxyAddress`、`proxyPort`（または `proxy` 文字列）の形式を確認してください |
| `ERROR_PROXY_TRANSPARENT` | プロキシが透過プロキシで、実際の IP が露出します | 匿名（高匿名）プロキシに変更してください |
| `ERROR_PROXY_NOT_AUTHORISED` | プロキシのユーザー名またはパスワードが間違っています | `proxyLogin` と `proxyPassword`（または `proxy` 文字列内の認証情報）を確認してください |
| `ERROR_PROXY_TLS_ERROR` | プロキシとの TLS ハンドシェイクに失敗しました。`proxyType` の指定誤り（たとえば http プロキシに https を指定）でよく起こります | プロキシのプロトコルを確認してください |
| `ERROR_PROXY_CONNECTION_FAILED` | プロキシサーバーに接続できませんでした | プロキシのアドレスとポートを確認し、プロキシが正常に動作していることを確かめてください |
### サーバー
| エラーコード | 意味 | 対処方法 |
| --- | --- | --- |
| `ERROR_SERVICE_UNAVALIABLE` | サービスが一時的に利用できません（エラーコードのつづりは `UNAVALIABLE` です） | しばらくしてから再試行してください。続く場合はサポートにお問い合わせください |
| `ERROR_INTERNAL_SERVER_ERROR` | サーバー内部でエラーが発生しました | しばらくしてから再試行してください。続く場合は `taskId` を添えてサポートにお問い合わせください |
| `ERROR_UNKNOWN` | 分類されていないエラーです | しばらくしてから再試行してください。続く場合は `taskId` を添えてサポートにお問い合わせください |
## 追加フィールド
一部のエラーのレスポンスには、追加のフィールドが含まれます。
| フィールド | 返される場所 | 説明 |
| --- | --- | --- |
| `retryAfter` | `ERROR_IP_BLOCKED_5MIN`、キャッシュされたエラー | あと何秒待つ必要があるか |
| `blockReason` | `ERROR_IP_BLOCKED_5MIN` | 一時停止の原因となったエラーコード |
| `blockDetail` | `ERROR_IP_BLOCKED_5MIN` | 一時停止の原因となったリクエストのタイプ、URL、sitekey。原因の特定に使えます |
| `cached` | キャッシュされたエラー | `true` の場合、キャッシュされた結果であり、実際には認識していません |
| `badRequest` | キャッシュされたエラー | キャッシュに該当したパラメータ |
| `limit` | `ERROR_THREADS_MAXIMUM` | 現在の同時実行数の上限 |
`errorDescription` の言語に関するルールは [リクエストとレスポンス](https://docs.yescaptcha.com/ja/api/overview.md) を参照してください。
---
# 同時実行数の上限と自動一時停止
> YesCaptcha の同時実行数の上限（ERROR_THREADS_MAXIMUM、課金なし、一時停止の対象外）、エラーが多すぎる場合の自動一時停止（1 分間に 100 回で 5 分間停止、ERROR_IP_BLOCKED_5MIN）、無効なパラメータのキャッシュ（cached）について説明します。
Source: https://docs.yescaptcha.com/ja/api/rate-limits/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/rate-limits/
すべてのユーザーの認識速度を保つため、YesCaptcha には 3 つの保護ルールがあります。アカウントごとに**同時に処理中のタスク数**を制限します（同時実行数の上限）。同じ `clientKey` が短時間に**エラーを出しすぎると数分間一時停止**されます（自動一時停止）。**無効と判定済みのパラメータ**は、一定時間そのまま元のエラーを返します（無効パラメータのキャッシュ）。この 3 つのいずれも課金されません。
## 同時実行数の上限
アカウントごと、タスクタイプごとに、同時に処理中のタスク数を制限します。制限するのは同時実行数であり、1 分あたりのリクエスト数ではありません。
- `createTask` を呼び出してから、その呼び出しが返るまでの間、タスクは「処理中」として数えられます。画像認識タイプは `createTask` の中で直接結果を返すため、**同時実行数 ≈ 1 秒あたりに送信するタスク数 × 1 タスクあたりの所要時間**になります。例えば、1 タスク 0.5 秒で毎秒 40 個送信すると、同時実行数は約 20 です。
- 同じアカウントのリクエストは合算して数えます。タスクタイプごとに別々に数えます。
- 上限を超えたリクエストはすぐに `ERROR_THREADS_MAXIMUM` を返します。レスポンスの `limit` が現在の上限です。**課金されず、自動一時停止の対象にもなりません。**
- 認識サーバーの処理が追いつかないときは、認識時間を最も多く使っているアカウントの、そのタスクタイプの上限が**一時的に半分になり、10 分後に自動で元に戻ります**。速度が制限されるだけで、アカウントが停止されることはありません。
- より高い上限が必要な場合は、[サポートまでお問い合わせください](https://docs.yescaptcha.com/ja/help/contact.md)。各タイプの既定の上限が決まり次第、このページと[サービス更新履歴](https://docs.yescaptcha.com/ja/changelog.md)で公開します。
```json
{
"errorId": 1,
"errorCode": "ERROR_THREADS_MAXIMUM",
"errorDescription": "这个账号这种任务同时处理中的请求已达上限 30。请降低并发、等已发出的请求返回后再发；超额的请求不扣点，也不会导致封禁。",
"limit": 30
}
```
（例の数値はあくまでイメージです。）
### 推奨される対処
1. 毎秒の送信数だけを制御するのではなく、「結果待ちのリクエスト数」をプログラム側で制限します。例えばセマフォ（Semaphore）や固定サイズのスレッドプールを使います。
2. `ERROR_THREADS_MAXIMUM` を受け取ったら、送信済みのリクエストが返るのを待ってから新しいリクエストを送るか、1〜2 秒待って再試行します。すぐにループで再試行しないでください。
3. 大量のタスクは均等に送信し、数千、数万のタスクを一度に同時送信しないでください。
Python（asyncio）の例：
```python
import asyncio
import os
import aiohttp
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
LIMIT = 15 # 小于你的并发上限
sem = asyncio.Semaphore(LIMIT)
async def solve(session, task):
async with sem: # 同时最多 LIMIT 个请求在处理中
result = {}
for attempt in range(5):
async with session.post(
"https://api.yescaptcha.com/createTask",
json={"clientKey": CLIENT_KEY, "task": task},
) as resp:
result = await resp.json()
if result.get("errorCode") != "ERROR_THREADS_MAXIMUM":
return result
await asyncio.sleep(1 + attempt) # 超出额度：稍等再试
return result
```
## 自動一時停止
同じ `clientKey` が短時間に大量のエラーリクエストを送ると、タスクの作成が自動的に一時停止されます。
| 発動条件 | 停止時間 |
| --- | --- |
| 同じ暦上の 1 分間に、下記のエラーが合計 100 回発生 | 5 分 |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` が 1 回発生 | 30 分 |
| 同じ暦上の 1 分間に、「無効パラメータのキャッシュ」に 1000 回ヒット | 5 分 |
一時停止の対象となるエラー：
- [`ERROR_REQUEST_FORMATS`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_REQUEST_FORMATS)
- [`ERROR_TASK_ABSENT`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_TASK_ABSENT)
- [`ERROR_TASK_NOT_SUPPORTED`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_TASK_NOT_SUPPORTED)
- [`ERROR_KEY_DOES_NOT_EXIST`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_KEY_DOES_NOT_EXIST)
- [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_KEY_EXPIRED)
- [`ERROR_TASKID_INVALID`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_TASKID_INVALID)
- [`ERROR_SETTLEMENT_FAILED`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_SETTLEMENT_FAILED)
- [`ERROR_HIGH_DEMAND_DOMAIN`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_HIGH_DEMAND_DOMAIN)
- [`ERROR_ZERO_CAPTCHA_FILESIZE`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_ZERO_CAPTCHA_FILESIZE)
- [`ERROR_TOO_BIG_CAPTCHA_FILESIZE`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_TOO_BIG_CAPTCHA_FILESIZE)
- [`ERROR_IMAGE_TYPE_NOT_SUPPORTED`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_IMAGE_TYPE_NOT_SUPPORTED)
- [`ERROR_ILLEGAL_IMAGE`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_ILLEGAL_IMAGE)
アカウントの同時実行数超過で返される `ERROR_THREADS_MAXIMUM`（`limit` フィールド付き）は対象外です。認識サービスが混雑しているときに返される同名のエラー（`limit` なし）は対象になります。認識失敗（`ERROR_CAPTCHA_UNSOLVABLE`）、残高不足（`ERROR_ZERO_BALANCE`）、フィールド不足（`ERROR_REQUIRED_FIELDS`）、未対応の問題文（`ERROR_UNKNOWN_QUESTION`）などは対象外です。
一時停止中の動作：
- 影響を受けるのは `createTask` と `getBalance` のみで、`ERROR_IP_BLOCKED_5MIN` を返します。`getTaskResult` は影響を受けず、停止前に作成したタスクの結果は通常どおり取得できます。
- レスポンスには `retryAfter`（残り秒数）、`blockReason`（停止のきっかけとなったエラーコード）、`blockDetail`（該当リクエストのタイプ、URL、sitekey）が含まれます。これらを参考にプログラムを修正してください。
- 送信を続けても停止時間は延長されません。時間が経過すると自動で再開されるため、サポートへの連絡は不要です。
- [yescaptcha.com](https://yescaptcha.com/) のダッシュボードで、直近 24 時間の一時停止の記録を確認できます。
```json
{
"errorId": 1,
"errorCode": "ERROR_IP_BLOCKED_5MIN",
"errorDescription": "这个 clientKey 短时间内产生了 100 次 ERROR_TASK_NOT_SUPPORTED 错误，为保护服务已暂停创建任务，182 秒后自动恢复。",
"retryAfter": 182,
"blockReason": "ERROR_TASK_NOT_SUPPORTED"
}
```
## 無効パラメータのキャッシュ
エラーの中にはリクエストのパラメータで決まるものがあり、同じパラメータで再送しても結果は変わりません。
- [`ERROR_RECAPTCHA_INVALID_SITEKEY`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_RECAPTCHA_INVALID_SITEKEY)
- [`ERROR_RECAPTCHA_INVALID_DOMAIN`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_RECAPTCHA_INVALID_DOMAIN)
- [`ERROR_INVALID_KEY_TYPE`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_INVALID_KEY_TYPE)
- [`ERROR_DOMAIN_NOT_ALLOWED`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_DOMAIN_NOT_ALLOWED)
これらのエラーは自動一時停止の対象にはならず、代わりにサイト全体でキャッシュされます。最初に判定されてから 2 分間キャッシュされ、1 時間以内に再度確認された場合は 10 分間キャッシュされます。キャッシュ期間中は、同じリクエスト（同じタスクタイプと `websiteKey`、または同じサイトのドメイン）に対して元のエラーをそのまま返し、課金されません。レスポンスには `"cached": true`、`retryAfter`（キャッシュの残り秒数）、`badRequest`（ヒットしたパラメータ）が含まれます。`websiteKey` を修正するかタスクタイプを変更すると、すぐに反映されます。
## 同時実行数の上限と自動一時停止の違い
| | 同時実行数の上限 | 自動一時停止 |
| --- | --- | --- |
| 原因 | 同時に処理中のタスクが多すぎる | 短時間にエラーリクエストが多すぎる |
| 動作 | 超過した分のリクエストのみ拒否し、`ERROR_THREADS_MAXIMUM` を返す | その `clientKey` のタスク作成を一時停止し、`ERROR_IP_BLOCKED_5MIN` を返す |
| 復旧 | リクエストの処理が完了すれば新しく送信できる。一時的に半減した上限は 10 分後に復旧 | 時間が経過すると自動で再開 |
| 課金 | されない | されない |
---
# タスクタイプと料金
> YesCaptcha で公開しているすべてのタスクタイプの料金(ポイント、1 元 = 1000 ポイント)と返却方式。token を返す reCAPTCHA・hCaptcha・Turnstile、Cookie を返す Cloudflare チャレンジページ、認識結果を返す画像の英数字認識と画像認識。
Source: https://docs.yescaptcha.com/ja/tasks/ · Last verified: 2026-10-19
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/
各タスクはタイプごとに固定のポイントが課金されます。1 元 = 1000 ポイントで、認識に失敗したタスクやタイムアウトしたタスクは自動で返金されます。下の表は公開しているすべてのタスクタイプで、名前で検索できます。機械可読版:[/data/task-types.json](https://docs.yescaptcha.com/data/task-types.json)。
| キャプチャ | タスクタイプ | 価格 | 返却方式 |
| --- | --- | --- | --- |
| [reCAPTCHA v2](https://docs.yescaptcha.com/ja/tasks/recaptcha-v2.md) | `NoCaptchaTaskProxyless` | $2.25 / 1k; 15 ポイント/タスク · ¥15 / 1k | 非同期 |
| [reCAPTCHA v2](https://docs.yescaptcha.com/ja/tasks/recaptcha-v2.md) | `RecaptchaV2TaskProxyless` | $3.00 / 1k; 20 ポイント/タスク · ¥20 / 1k | 非同期 |
| [reCAPTCHA v2](https://docs.yescaptcha.com/ja/tasks/recaptcha-v2.md) | `NoCaptchaTask` プロキシ持ち込み | $2.25 / 1k; 15 ポイント/タスク · ¥15 / 1k | 非同期 |
| [reCAPTCHA v2](https://docs.yescaptcha.com/ja/tasks/recaptcha-v2.md) | `RecaptchaV2EnterpriseTaskProxyless` | $3.00 / 1k; 20 ポイント/タスク · ¥20 / 1k | 非同期 |
| [reCAPTCHA v2](https://docs.yescaptcha.com/ja/tasks/recaptcha-v2.md) | `RecaptchaV2EnterpriseTask` プロキシ持ち込み | $3.00 / 1k; 20 ポイント/タスク · ¥20 / 1k | 非同期 |
| [reCAPTCHA v3](https://docs.yescaptcha.com/ja/tasks/recaptcha-v3.md) | `RecaptchaV3TaskProxyless` | $3.00 / 1k; 20 ポイント/タスク · ¥20 / 1k | 非同期 |
| [reCAPTCHA v3](https://docs.yescaptcha.com/ja/tasks/recaptcha-v3.md) | `RecaptchaV3TaskProxylessM1` | $3.75 / 1k; 25 ポイント/タスク · ¥25 / 1k | 非同期 |
| [reCAPTCHA v3](https://docs.yescaptcha.com/ja/tasks/recaptcha-v3.md) | `RecaptchaV3TaskProxylessM1S7` | $4.50 / 1k; 30 ポイント/タスク · ¥30 / 1k | 非同期 |
| [reCAPTCHA v3](https://docs.yescaptcha.com/ja/tasks/recaptcha-v3.md) | `RecaptchaV3TaskProxylessM1S9` | $5.25 / 1k; 35 ポイント/タスク · ¥35 / 1k | 非同期 |
| [reCAPTCHA v3](https://docs.yescaptcha.com/ja/tasks/recaptcha-v3.md) | `RecaptchaV3EnterpriseTask` | $3.00 / 1k; 20 ポイント/タスク · ¥20 / 1k | 非同期 |
| [reCAPTCHA v3](https://docs.yescaptcha.com/ja/tasks/recaptcha-v3.md) | `RecaptchaV3EnterpriseTaskM1` | $3.75 / 1k; 25 ポイント/タスク · ¥25 / 1k | 非同期 |
| [hCaptcha](https://docs.yescaptcha.com/ja/tasks/hcaptcha.md) | `HCaptchaTaskProxyless` | $4.50 / 1k; 30 ポイント/タスク · ¥30 / 1k | 非同期 |
| [hCaptcha](https://docs.yescaptcha.com/ja/tasks/hcaptcha.md) | `HCaptchaTaskProxylessM1` | $4.50 / 1k; 30 ポイント/タスク · ¥30 / 1k | 非同期 |
| [hCaptcha](https://docs.yescaptcha.com/ja/tasks/hcaptcha.md) | `HCaptchaTask` プロキシ持ち込み | $2.25 / 1k; 15 ポイント/タスク · ¥15 / 1k | 非同期 |
| [Cloudflare Turnstile](https://docs.yescaptcha.com/ja/tasks/turnstile.md) | `TurnstileTaskProxyless` | $3.75 / 1k; 25 ポイント/タスク · ¥25 / 1k | 非同期 |
| [Cloudflare Turnstile](https://docs.yescaptcha.com/ja/tasks/turnstile.md) | `TurnstileTaskProxylessM1` | $4.50 / 1k; 30 ポイント/タスク · ¥30 / 1k | 非同期 |
| [Cloudflare Turnstile](https://docs.yescaptcha.com/ja/tasks/turnstile.md) | `TurnstileTask` プロキシ持ち込み | $3.75 / 1k; 25 ポイント/タスク · ¥25 / 1k | 非同期 |
| [Cloudflare チャレンジページ](https://docs.yescaptcha.com/ja/tasks/cloudflare-challenge.md) | `CloudFlareTaskS2` プロキシ持ち込み | $3.75 / 1k; 25 ポイント/タスク · ¥25 / 1k | 非同期 |
| [Cloudflare チャレンジページ](https://docs.yescaptcha.com/ja/tasks/cloudflare-challenge.md) | `CloudFlareTaskS3` プロキシ持ち込み | $3.00 / 1k; 20 ポイント/タスク · ¥20 / 1k | 非同期 |
| [画像から文字へ](https://docs.yescaptcha.com/ja/tasks/image-to-text.md) | `ImageToTextTaskOcrBase` | $0.30 / 1k; 2 ポイント/タスク · ¥2 / 1k | 同期 |
| [画像から文字へ](https://docs.yescaptcha.com/ja/tasks/image-to-text.md) | `ImageToTextTaskMuggle` | $0.30 / 1k; 2 ポイント/タスク · ¥2 / 1k | 同期 |
| [画像から文字へ](https://docs.yescaptcha.com/ja/tasks/image-to-text.md) | `ImageToTextTask` | $0.60 / 1k; 4 ポイント/タスク · ¥4 / 1k | 非同期 |
| [画像から文字へ](https://docs.yescaptcha.com/ja/tasks/image-to-text.md) | `ImageToTextTaskM1` | $2.25 / 1k; 15 ポイント/タスク · ¥15 / 1k | 非同期 |
| [reCAPTCHA v2 画像認識](https://docs.yescaptcha.com/ja/tasks/recaptcha-classification.md) | `ReCaptchaV2Classification` | $0.90 / 1k; 6 ポイント/タスク · ¥6 / 1k | 同期 |
| [hCaptcha 画像認識](https://docs.yescaptcha.com/ja/tasks/hcaptcha-classification.md) | `HCaptchaClassification` | $1.20 / 1k; 8 ポイント/タスク · ¥8 / 1k | 同期 |
| [FunCaptcha 画像認識](https://docs.yescaptcha.com/ja/tasks/funcaptcha-classification.md) | `FunCaptchaClassification` | $0.45 / 1k; 3 ポイント/タスク · ¥3 / 1k | 同期 |
| [AWS WAF / bCaptcha 画像認識](https://docs.yescaptcha.com/ja/tasks/aws-bcaptcha-classification.md) | `AwsClassification` | $1.20 / 1k; 8 ポイント/タスク · ¥8 / 1k | 同期 |
| [AWS WAF / bCaptcha 画像認識](https://docs.yescaptcha.com/ja/tasks/aws-bcaptcha-classification.md) | `bCaptchaClassification` | $1.20 / 1k; 8 ポイント/タスク · ¥8 / 1k | 同期 |
米ドル価格は US$1 ≈ ¥6.67（2026-10-27）での概算です。タスクはポイントで課金されます。人民元でチャージする場合は 1,000 ポイント = ¥1 です。米ドル（PayPal、暗号資産）でのチャージは、支払い時の為替レートで人民元に換算し、さらにポイントに換算します。
## 選び方
| やりたいこと | 使うタイプ | 返却されるもの |
| --- | --- | --- |
| 画像をクリックせず、token を取得してそのまま送信する | [reCAPTCHA v2](https://docs.yescaptcha.com/ja/tasks/recaptcha-v2.md)、[reCAPTCHA v3](https://docs.yescaptcha.com/ja/tasks/recaptcha-v3.md)、[hCaptcha](https://docs.yescaptcha.com/ja/tasks/hcaptcha.md)、[Turnstile](https://docs.yescaptcha.com/ja/tasks/turnstile.md) | token(非同期) |
| Cloudflare の「しばらくお待ちください」チェックページを通過する | [Cloudflare チャレンジページ](https://docs.yescaptcha.com/ja/tasks/cloudflare-challenge.md) | Cookie、User-Agent、ページの内容(非同期) |
| ブラウザ上で自分で画像をクリックする | [reCAPTCHA v2 画像認識](https://docs.yescaptcha.com/ja/tasks/recaptcha-classification.md)、[hCaptcha 画像認識](https://docs.yescaptcha.com/ja/tasks/hcaptcha-classification.md)、[FunCaptcha 画像認識](https://docs.yescaptcha.com/ja/tasks/funcaptcha-classification.md)、[AWS WAF / bCaptcha 画像認識](https://docs.yescaptcha.com/ja/tasks/aws-bcaptcha-classification.md) | クリックすべき画像や位置(同期) |
| 画像内の文字を認識する | [画像の英数字認識](https://docs.yescaptcha.com/ja/tasks/image-to-text.md) | 文字列(多くは同期) |
キャプチャの種類がわからない場合は、[キャプチャの種類を判別する](https://docs.yescaptcha.com/ja/guides/identify-captcha.md)を参照してください。
## 名前の規則
- **`Proxyless`**:当社のネットワークでキャプチャを読み込むため、プロキシは不要です。名前に `Proxyless` が付かないもの(`NoCaptchaTask`、`HCaptchaTask` など)は自分のプロキシを使用し、プロキシ関連のフィールドを渡す必要があります。対象サイトがアクセス元 IP を検査する場合に適しています。
- **`M1` などの接尾辞**:同じ種類のキャプチャに対する別系統のルートです。パラメータは同じで、料金が異なります。通過率が思わしくない場合は別のルートに切り替えられ、互いにバックアップとしても使えます。
- **`Classification`**:画像認識。token ではなく、クリックすべき位置を返します。
- **`Enterprise`**:reCAPTCHA Enterprise。
## 補足
- reCAPTCHA v2 画像認識は画像サイズに応じて課金され、hCaptcha 画像認識は対象が認識できなかった場合は課金されません。詳しくはそれぞれのページを参照してください。
- 料金はこのページが基準です。課金されるのはタスクの作成時のみで、結果の取得は課金されません。課金ルールは[課金と返金](https://docs.yescaptcha.com/ja/getting-started/billing.md)を参照してください。
---
# reCAPTCHA v2
> YesCaptcha で reCAPTCHA v2(通常版・非表示版・Enterprise 版)の token を取得する方法。タスクタイプと料金、リクエストパラメータ、curl/Python/Node.js のサンプル、返却結果を説明します。
Source: https://docs.yescaptcha.com/ja/tasks/recaptcha-v2/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/recaptcha-v2/
reCAPTCHA v2 のタスクは token(`gRecaptchaResponse`)を返します。この token を対象サイトに送信すれば認証を通過でき、画像をクリックする必要はありません。最もよく使う `NoCaptchaTaskProxyless` は 1 タスクあたり 15 ポイント（約 $2.25 / 1k） で、非同期で結果を返します。まず `createTask` でタスクを作成し、その後 5 秒ごとに `getTaskResult` を呼び出して結果を取得します。認識に失敗したタスクやタイムアウトしたタスクは自動的に返金されます。
- POST `https://api.yescaptcha.com/createTask` (グローバルエンドポイント)
- POST `https://cn.yescaptcha.com/createTask` (中国エンドポイント)
リクエストボディは JSON で、`clientKey`(ダッシュボードの [yescaptcha.com](https://yescaptcha.com/) からコピーできます)で認証します。タスクを作成したエンドポイントと同じエンドポイントで結果を取得してください。
## 利用シーン
- ページに「ロボットではありません」(I’m not a robot)のチェックボックスがある場合: 通常版。
- チェックボックスがなく、送信ボタンをクリックしたあとに画像の問題が表示される場合: 非表示版。`"isInvisible": true` を追加します。
- ページが `recaptcha/enterprise.js` を読み込んでいる、またはリクエスト URL に `enterprise` が含まれている場合: Enterprise 版。名前に `Enterprise` が付くタイプを使います。
どの種類か分からない場合は、[キャプチャの種類を判別する](https://docs.yescaptcha.com/ja/guides/identify-captcha.md)を参照してください。token 方式の通過率が思わしくない場合は、[reCAPTCHA v2 画像認識](https://docs.yescaptcha.com/ja/tasks/recaptcha-classification.md)に切り替えられます。API がクリックすべき画像を返すので、ブラウザ上で自分でクリックします。
## タイプと料金
| タスクタイプ | 価格 | 返却方式 | 備考 |
| --- | --- | --- | --- |
| `NoCaptchaTaskProxyless` | $2.25 / 1k; 15 ポイント/タスク · ¥15 / 1k | 非同期 | |
| `RecaptchaV2TaskProxyless` | $3.00 / 1k; 20 ポイント/タスク · ¥20 / 1k | 非同期 | NoCaptchaTaskProxyless とパラメータは同じで、経路が異なります。どちらか一方をバックアップとして使えます |
| `NoCaptchaTask` | $2.25 / 1k; 15 ポイント/タスク · ¥15 / 1k | 非同期 | プロキシ持ち込み |
| `RecaptchaV2EnterpriseTaskProxyless` | $3.00 / 1k; 20 ポイント/タスク · ¥20 / 1k | 非同期 | |
| `RecaptchaV2EnterpriseTask` | $3.00 / 1k; 20 ポイント/タスク · ¥20 / 1k | 非同期 | プロキシ持ち込み |
米ドル価格は US$1 ≈ ¥6.67 での概算です。タスクはポイントで課金されます。
- `NoCaptchaTaskProxyless` と `RecaptchaV2TaskProxyless` はパラメータが同じで、経路が異なります。一方の通過率が思わしくない場合は、もう一方を試してください。
- 名前に `Proxyless` が付かないタイプ(`NoCaptchaTask`、`RecaptchaV2EnterpriseTask`)は、お客様自身のプロキシでキャプチャを読み込みます。`proxyType`、`proxyAddress`、`proxyPort` などのフィールドを渡す必要があります。対象サイトがアクセス元 IP を制限している場合に使います。
## リクエストパラメータ
`createTask` の `task` オブジェクト:
| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `type` | string | はい | タスクタイプ。値はこのページの「タイプと料金」を参照してください |
| `websiteURL` | string | はい | キャプチャが表示されるページの完全な URL。キャプチャが表示されるサイトを指定し、キャプチャ提供元のドメインは指定しないでください |
| `websiteKey` | string | はい | サイトキー（sitekey）。ページのソースまたはネットワークリクエストから確認できます。通常は変わりません |
| `isInvisible` | boolean | いいえ | インビジブル版の場合は true を指定します。通常版では指定しません |
| `proxyType` | string | 一部のタイプ | プロキシのプロトコル: `http`、`https`、`socks4`、`socks5`（NoCaptchaTask、RecaptchaV2EnterpriseTask では必須） |
| `proxyAddress` | string | 一部のタイプ | プロキシの IP アドレスまたはホスト名。127.0.0.1 や 192.168.x.x のようなローカルアドレスやプライベートアドレスは、当社のサーバーから到達できないため使用できません（NoCaptchaTask、RecaptchaV2EnterpriseTask では必須） |
| `proxyPort` | integer | 一部のタイプ | プロキシのポート（NoCaptchaTask、RecaptchaV2EnterpriseTask では必須） |
| `proxyLogin` | string | いいえ | プロキシのユーザー名（プロキシが認証を必要とする場合）（NoCaptchaTask、RecaptchaV2EnterpriseTask のみ） |
| `proxyPassword` | string | いいえ | プロキシのパスワード（プロキシが認証を必要とする場合）（NoCaptchaTask、RecaptchaV2EnterpriseTask のみ） |
| `userAgent` | string | いいえ | ブラウザーの User-Agent。結果に `userAgent` が含まれている場合は、token を送信するときにその値を使用してください（NoCaptchaTask、RecaptchaV2EnterpriseTask のみ） |
| `enterprisePayload` | object | いいえ | エンタープライズ版の追加パラメータ。例: reCAPTCHA Enterprise の `s` の値 `{"s": "..."}`。ページで使われていない場合は指定しません（RecaptchaV2EnterpriseTaskProxyless、RecaptchaV2EnterpriseTask のみ） |
`websiteURL` と `websiteKey` の調べ方は、[reCAPTCHA のパラメータを調べる](https://docs.yescaptcha.com/ja/guides/find-recaptcha-parameters.md)を参照してください。
## リクエスト例
Google 公式のデモページを例にします:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}
```
タスクの作成、5 秒ごとの結果取得、token の出力までを含む完全なコードです。実行前に clientKey を環境変数 `YESCAPTCHA_CLIENT_KEY` に設定してください:
**curl**
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}'
# 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"}'
```
**Python**
solve.py
```python
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": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})
print(solution["gRecaptchaResponse"])
```
**Node.js**
solve.mjs
```js
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: "NoCaptchaTaskProxyless",
websiteURL: "https://www.google.com/recaptcha/api2/demo",
websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
console.log(solution.gRecaptchaResponse);
```
Enterprise 版で、ページが reCAPTCHA に `s` 値を渡している場合は、`enterprisePayload` に指定します:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "RecaptchaV2EnterpriseTaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "SITE_KEY_OF_THE_PAGE",
"enterprisePayload": {
"s": "S_VALUE_FROM_THE_PAGE"
}
}
}
```
自分のプロキシを使う場合:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTask",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
"proxyType": "http",
"proxyAddress": "proxy.example.com",
"proxyPort": 8080,
"proxyLogin": "user",
"proxyPassword": "pass"
}
}
```
## 返却結果
`createTask` はタスク ID を返します:
```json
{
"errorId": 0,
"taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```
このタスク ID で `getTaskResult` を呼び出します。処理中は `{"errorId": 0, "status": "processing"}` が返るので、5 秒後に再度取得してください。完了すると次のように返ります:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
}
}
```
| フィールド | 型 | 説明 |
| --- | --- | --- |
| `gRecaptchaResponse` | string | 対象サイトに送信するトークン。1 回限りの使用で、有効期間は約 120 秒です。60 秒以内に使用してください |
タスクの処理時間は最長で約 110 秒です。タイムアウトすると `ERROR_TASK_TIMEOUT` が返り、ポイントが返金されます。エラー時は `errorId` が 1 になるので、`errorCode` に応じて処理してください。詳しくは[エラーコード](https://docs.yescaptcha.com/ja/api/errors.md)を参照してください。token を取得したあとの送信方法は、[token で reCAPTCHA を完了する](https://docs.yescaptcha.com/ja/guides/submit-recaptcha-token.md)を参照してください。
> **ヒント:** token は 1 回限り使用でき、有効期間は約 120 秒です。取得後 60 秒以内に送信することをおすすめします。
## よくある質問
### 同じサイトなのに、token が通ったり通らなかったりするのはなぜですか?
通過できるかどうかは対象サイトが判定します。サイトは認証ごとにスコアを付けて基準値を設けており、この基準値はいつでも変更される可能性があります。そのため通過率はサイトによって異なり、すべての token が通るわけではありません。同種の別のタスクタイプで通過率を比較するか、[画像認識](https://docs.yescaptcha.com/ja/tasks/recaptcha-classification.md)に切り替えてください。
### token はどのくらいの間有効ですか?
1 回限り使用でき、有効期間は約 120 秒です。取得後 60 秒以内の送信をおすすめします。有効期間は Google が決めています。
### 認識に失敗した場合も課金されますか?
課金されません。`ERROR_CAPTCHA_UNSOLVABLE` を返したタスクやタイムアウトしたタスクは自動的に返金されます。詳しくは[課金と返金](https://docs.yescaptcha.com/ja/getting-started/billing.md)を参照してください。
## 関連チュートリアル
- [キャプチャの種類を判別する](https://docs.yescaptcha.com/ja/guides/identify-captcha.md)
- [reCAPTCHA のパラメータを調べる](https://docs.yescaptcha.com/ja/guides/find-recaptcha-parameters.md)
- [token で reCAPTCHA を完了する](https://docs.yescaptcha.com/ja/guides/submit-recaptcha-token.md)
- [reCAPTCHA v2 画像認識によるクリックのシミュレーション(Selenium)](https://docs.yescaptcha.com/ja/guides/recaptcha-click-selenium.md)
---
# reCAPTCHA v3
> YesCaptcha で reCAPTCHA v3(Enterprise 版を含む)の token を取得する方法。pageAction の指定方法、固定スコア 0.7・0.9 のタイプ、タスクタイプと料金、パラメータ、リクエスト例、返却結果を説明します。
Source: https://docs.yescaptcha.com/ja/tasks/recaptcha-v3/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/recaptcha-v3/
reCAPTCHA v3 にはチェックボックスも画像もなく、ページがバックグラウンドで訪問者をスコアリングします。YesCaptcha は token(`gRecaptchaResponse`)を返すので、それを対象サイトに送信してください。`RecaptchaV3TaskProxyless` は 1 タスクあたり 20 ポイント（約 $3.00 / 1k） で、非同期で結果を返します。まず `createTask` を呼び、その後 5 秒ごとに `getTaskResult` を呼びます。認識に失敗した場合やタイムアウトした場合は、自動的に返金されます。
- POST `https://api.yescaptcha.com/createTask` (グローバルエンドポイント)
- POST `https://cn.yescaptcha.com/createTask` (中国エンドポイント)
リクエストボディは JSON で、`clientKey` で認証します。タスクを作成したエンドポイントと同じエンドポイントで結果を取得してください。
## 利用シーン
- ページのソースに `grecaptcha.execute(...)` がある、または `recaptcha/api.js?render=サイトキー` を読み込んでいる場合: 通常版の v3 です。
- `grecaptcha.enterprise.execute(...)` を呼んでいる、または `recaptcha/enterprise.js` を読み込んでいる場合: Enterprise 版の v3 です。`RecaptchaV3EnterpriseTask` または `RecaptchaV3EnterpriseTaskM1` を使います。
判別方法は [キャプチャの種類を判別する](https://docs.yescaptcha.com/ja/guides/identify-captcha.md) を参照してください。
## タイプと料金
| タスクタイプ | 価格 | 返却方式 | 備考 |
| --- | --- | --- | --- |
| `RecaptchaV3TaskProxyless` | $3.00 / 1k; 20 ポイント/タスク · ¥20 / 1k | 非同期 | |
| `RecaptchaV3TaskProxylessM1` | $3.75 / 1k; 25 ポイント/タスク · ¥25 / 1k | 非同期 | |
| `RecaptchaV3TaskProxylessM1S7` | $4.50 / 1k; 30 ポイント/タスク · ¥30 / 1k | 非同期 | スコア 0.7 を要求します。追加のパラメータは不要です |
| `RecaptchaV3TaskProxylessM1S9` | $5.25 / 1k; 35 ポイント/タスク · ¥35 / 1k | 非同期 | スコア 0.9 を要求します。追加のパラメータは不要です |
| `RecaptchaV3EnterpriseTask` | $3.00 / 1k; 20 ポイント/タスク · ¥20 / 1k | 非同期 | |
| `RecaptchaV3EnterpriseTaskM1` | $3.75 / 1k; 25 ポイント/タスク · ¥25 / 1k | 非同期 | |
米ドル価格は US$1 ≈ ¥6.67 での概算です。タスクはポイントで課金されます。
- `RecaptchaV3TaskProxyless` と `RecaptchaV3TaskProxylessM1` はパラメータが同じで、経路が異なります。互いのバックアップとして使えます。
- 対象サイトが高いスコアを要求する場合は、固定スコアの `RecaptchaV3TaskProxylessM1S7`(0.7)または `RecaptchaV3TaskProxylessM1S9`(0.9)を使います。追加のパラメータは不要です。
## リクエストパラメータ
| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `type` | string | はい | タスクタイプ。値はこのページの「タイプと料金」を参照してください |
| `websiteURL` | string | はい | キャプチャが表示されるページの完全な URL。キャプチャが表示されるサイトを指定し、キャプチャ提供元のドメインは指定しないでください |
| `websiteKey` | string | はい | サイトキー（sitekey）。ページのソースまたはネットワークリクエストから確認できます。通常は変わりません |
| `pageAction` | string | いいえ | reCAPTCHA v3 の action。ページが `grecaptcha.execute` に渡す値と一致させる必要があります。一致しないと token が無効になる場合があります |
`pageAction` は、ページが `grecaptcha.execute(サイトキー, {action: '...'})` を呼ぶ際に渡す `action` と一致させる必要があります。誤っていると、token がサイトに拒否されることがあります。確認方法は [reCAPTCHA のパラメータを調べる](https://docs.yescaptcha.com/ja/guides/find-recaptcha-parameters.md) を参照してください。
## リクエスト例
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "SITE_KEY_OF_THE_PAGE",
"pageAction": "login"
}
}
```
**curl**
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "SITE_KEY_OF_THE_PAGE",
"pageAction": "login"
}
}'
# 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"}'
```
**Python**
solve.py
```python
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": "RecaptchaV3TaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "SITE_KEY_OF_THE_PAGE",
"pageAction": "login",
})
print(solution["gRecaptchaResponse"])
```
**Node.js**
solve.mjs
```js
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: "RecaptchaV3TaskProxyless",
websiteURL: "https://example.com/login",
websiteKey: "SITE_KEY_OF_THE_PAGE",
pageAction: "login",
});
console.log(solution.gRecaptchaResponse);
```
`websiteURL`、`websiteKey`、`pageAction` は、対象サイトの値に置き換えてください。
## 返却結果
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
}
}
```
| フィールド | 型 | 説明 |
| --- | --- | --- |
| `gRecaptchaResponse` | string | 対象サイトに送信するトークン。1 回限りの使用で、有効期間は約 120 秒です。60 秒以内に使用してください |
処理中の場合は `{"errorId": 0, "status": "processing"}` が返るので、5 秒後に再度取得してください。エラーが返った場合は `errorCode` に従って対処します。詳しくは [エラーコード](https://docs.yescaptcha.com/ja/api/errors.md) を参照してください。取得した token の送信方法は [token で reCAPTCHA を完了する](https://docs.yescaptcha.com/ja/guides/submit-recaptcha-token.md) を参照してください。
## よくある質問
### token がサイトに受け入れられないことがあるのはなぜですか?
v3 では、対象サイトがスコアに基づいて判定します。サイト側のしきい値はいつでも変更できるため、すべての token が通るわけではありません。`pageAction` が正しいことを確認してください。サイトが高いスコアを要求する場合は `M1S7` や `M1S9` を試すか、同系統の他のタイプと比較してください。
### Enterprise 版の v3 はどう指定しますか?
通常版と同様に `websiteURL`、`websiteKey`、`pageAction` を指定し、タイプを `RecaptchaV3EnterpriseTask` または `RecaptchaV3EnterpriseTaskM1` に変更します。
### token の有効期間はどのくらいですか?
1 回限りの使い捨てで、有効期間は約 120 秒です。60 秒以内に送信することをおすすめします。
## 関連チュートリアル
- [キャプチャの種類を判別する](https://docs.yescaptcha.com/ja/guides/identify-captcha.md)
- [reCAPTCHA のパラメータを調べる](https://docs.yescaptcha.com/ja/guides/find-recaptcha-parameters.md)(`pageAction` の調べ方を含む)
- [token で reCAPTCHA を完了する](https://docs.yescaptcha.com/ja/guides/submit-recaptcha-token.md)
---
# hCaptcha
> YesCaptcha で hCaptcha のトークンを取得します。HCaptchaTaskProxyless、HCaptchaTaskProxylessM1、独自プロキシを使う HCaptchaTask、userAgent と rqdata の指定方法、返される respKey の使い方を説明します。
Source: https://docs.yescaptcha.com/ja/tasks/hcaptcha/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/hcaptcha/
hCaptcha タスクはトークン(`gRecaptchaResponse`)を返します。返された `userAgent`(場合によっては `respKey` も)と一緒に対象サイトへ送信すると、検証を通過できます。`HCaptchaTaskProxyless` は 1 タスクあたり 30 ポイント（約 $4.50 / 1k）、独自プロキシを使う `HCaptchaTask` は 1 タスクあたり 15 ポイント（約 $2.25 / 1k） です。どちらも非同期で、まず `createTask` を呼び出し、その後 5 秒ごとに `getTaskResult` を呼び出します。認識に失敗した場合やタイムアウトした場合は、自動的に返金されます。
- POST `https://api.yescaptcha.com/createTask` (グローバルエンドポイント)
- POST `https://cn.yescaptcha.com/createTask` (中国エンドポイント)
リクエストボディは JSON で、`clientKey` で認証します。タスクを作成したエンドポイントと同じエンドポイントで結果を取得してください。
## 利用シーン
ページに hCaptcha の「私は人間です」チェックボックスがある場合や、hCaptcha の画像問題が表示される場合です。トークンを取得してそのまま送信したいときは、このページのタイプを使います。ブラウザ上で自分で画像をクリックしたいときは、[hCaptcha 画像認識](https://docs.yescaptcha.com/ja/tasks/hcaptcha-classification.md)を使います。
> **ノート:** 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](https://docs.yescaptcha.com/ja/api/useragent.md) が返す値のみです。
- `rqdata`:hCaptcha Enterprise を使うサイト(一部のソーシャルサイトやチャットサイトなど)で必要になります。通常は、キャプチャを読み込むリクエストの中に含まれています。一般的なサイトでは指定しません。
パラメーターの見つけ方は、[hCaptcha パラメーターの調べ方](https://docs.yescaptcha.com/ja/guides/find-hcaptcha-parameters.md)を参照してください。
## リクエスト例
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "HCaptchaTaskProxyless",
"websiteURL": "https://accounts.hcaptcha.com/demo",
"websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
}
}
```
**curl**
```bash
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"}'
```
**Python**
solve.py
```python
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"])
```
**Node.js**
solve.mjs
```js
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);
```
独自のプロキシを使う場合:
POST https://api.yescaptcha.com/createTask
```json
{
"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"
}
}
```
## レスポンス
```json
{
"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 | サイトによってはトークンと一緒に送信する必要がある値。返された場合は一緒に送信してください |
送信手順:
1. トークンを、ページ内の `h-captcha-response` フィールド(`g-recaptcha-response` がある場合はそのフィールドにも)、または対象サイトの API が要求するフィールドに設定します。
2. 送信リクエストを送る際は、User-Agent に返された `userAgent` を使用します。
3. `respKey` が返された場合は、サイトの要件に従って一緒に送信します。
処理中は `{"errorId": 0, "status": "processing"}` が返されるので、5 秒後にもう一度取得してください。エラーが発生した場合は `errorCode` に従って対処します。詳しくは[エラーコード](https://docs.yescaptcha.com/ja/api/errors.md)を参照してください。
## よくある質問
### 通過率が安定しないのはなぜですか?
hCaptcha は、サイトの設定、アクセス元の IP、ブラウザ環境をもとに判定するため、通過率はサイトによって異なります。返された `userAgent` を使用していることを確認してください。IP に敏感なサイトでは、独自プロキシを使う `HCaptchaTask` を使い、送信時も同じプロキシを経由させます。`HCaptchaTaskProxylessM1` に切り替えて比較することもできます。
### トークンの有効期間はどのくらいですか?
トークンは使い捨てで、有効期間は約 120 秒です。取得後はできるだけ早く送信してください。
## 関連チュートリアル
- [hCaptcha パラメーターの調べ方](https://docs.yescaptcha.com/ja/guides/find-hcaptcha-parameters.md)
- [hCaptcha 画像認識でクリックをシミュレートする(Selenium)](https://docs.yescaptcha.com/ja/guides/hcaptcha-click-selenium.md)
---
# Cloudflare Turnstile
> YesCaptcha で Cloudflare Turnstile のトークンを取得します。TurnstileTaskProxyless、TurnstileTaskProxylessM1、独自プロキシを使う TurnstileTask のパラメーター、リクエスト例、返却結果と、Cloudflare チャレンジページとの違いを説明します。
Source: https://docs.yescaptcha.com/ja/tasks/turnstile/ · Last verified: 2026-10-21
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/turnstile/
Cloudflare Turnstile タスクはトークン(`token`)を返します。これを対象サイトに送信すると検証を通過できます。`TurnstileTaskProxyless` は 1 タスクあたり 25 ポイント（約 $3.75 / 1k） で、非同期で結果を返します。まず `createTask` を呼び、その後 5 秒ごとに `getTaskResult` を呼びます。認識に失敗した場合やタイムアウトした場合は、自動で返金されます。
- POST `https://api.yescaptcha.com/createTask` (グローバルエンドポイント)
- POST `https://cn.yescaptcha.com/createTask` (中国エンドポイント)
リクエストボディは JSON で、`clientKey` で認証します。タスクを作成したエンドポイントと同じエンドポイントで結果を取得してください。
## 利用シーン
ページのフォームに Cloudflare の検証ウィジェット(「人間であることを確認します」)が埋め込まれており、ページが `challenges.cloudflare.com/turnstile` のスクリプトを読み込んでいる場合です。
ページ全体が Cloudflare に遮られ、「しばらくお待ちください…」「ブラウザを確認しています」と表示される場合は、Turnstile ではなく Cloudflare チャレンジページです。[Cloudflare チャレンジページ](https://docs.yescaptcha.com/ja/tasks/cloudflare-challenge.md)を使用してください。違いは[キャプチャの種類の見分け方](https://docs.yescaptcha.com/ja/guides/identify-captcha.md)を参照してください。
## タスクタイプと料金
| タスクタイプ | 価格 | 返却方式 | 備考 |
| --- | --- | --- | --- |
| `TurnstileTaskProxyless` | $3.75 / 1k; 25 ポイント/タスク · ¥25 / 1k | 非同期 | |
| `TurnstileTaskProxylessM1` | $4.50 / 1k; 30 ポイント/タスク · ¥30 / 1k | 非同期 | |
| `TurnstileTask` | $3.75 / 1k; 25 ポイント/タスク · ¥25 / 1k | 非同期 | プロキシ持ち込み |
米ドル価格は US$1 ≈ ¥6.67 での概算です。タスクはポイントで課金されます。
- `TurnstileTaskProxyless` と `TurnstileTaskProxylessM1` はパラメーターが同じで、経路が異なります。お互いにバックアップとして使えます。
- `TurnstileTask` は独自のプロキシでキャプチャを読み込みます。プロキシ関連のフィールドを渡す必要があります。
## リクエストパラメーター
| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `type` | string | はい | タスクタイプ。値はこのページの「タイプと料金」を参照してください |
| `websiteURL` | string | はい | キャプチャが表示されるページの完全な URL。キャプチャが表示されるサイトを指定し、キャプチャ提供元のドメインは指定しないでください |
| `websiteKey` | string | はい | Turnstile のサイトキー（sitekey）。通常は 0x で始まります |
| `pageAction` | string | いいえ | ページが Turnstile に渡す `action`（`turnstile.render` のオプション、またはウィジェット要素の `data-action`）。例：`login`。ほとんどの場合は不要です。タスクが失敗し続ける場合にのみ追加してください |
| `data` | string | いいえ | ページが Turnstile に渡す `cData`（`turnstile.render` のオプション、またはウィジェット要素の `data-cdata`）。例：`c0bd4b36-7419-4e18-83c6-378699f2a9a2`。ほとんどの場合は不要です。タスクが失敗し続ける場合にのみ追加してください |
| `proxyType` | string | 一部のタイプ | プロキシのプロトコル: `http`、`https`、`socks4`、`socks5`（TurnstileTask では必須） |
| `proxyAddress` | string | 一部のタイプ | プロキシの IP アドレスまたはホスト名。127.0.0.1 や 192.168.x.x のようなローカルアドレスやプライベートアドレスは、当社のサーバーから到達できないため使用できません（TurnstileTask では必須） |
| `proxyPort` | integer | 一部のタイプ | プロキシのポート（TurnstileTask では必須） |
| `proxyLogin` | string | いいえ | プロキシのユーザー名（プロキシが認証を必要とする場合）（TurnstileTask のみ） |
| `proxyPassword` | string | いいえ | プロキシのパスワード（プロキシが認証を必要とする場合）（TurnstileTask のみ） |
| `userAgent` | string | いいえ | ブラウザーの User-Agent。結果に `userAgent` が含まれている場合は、token を送信するときにその値を使用してください（TurnstileTask のみ） |
`websiteKey` は通常 `0x` で始まります。見つけ方は [Turnstile パラメーターの見つけ方](https://docs.yescaptcha.com/ja/guides/find-turnstile-parameters.md)を参照してください。
### どうしても通らない場合:pageAction と data
ほとんどの場合、`websiteURL` と `websiteKey` だけで十分で、この 2 つのパラメーターは不要です。`websiteURL` と `websiteKey` が正しいことを確認してもタスクが通らない場合は、ページが Turnstile を呼び出すときに `action` と `cData` を渡しているかを確認してください(`turnstile.render` のパラメーター、または検証ウィジェット要素の `data-action`、`data-cdata`)。渡している場合は、そのまま指定します。
- `pageAction`:ページの `action` を指定します(例:`login`)
- `data`:ページの `cData` を指定します(例:`c0bd4b36-7419-4e18-83c6-378699f2a9a2`)
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "TurnstileTaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "0x4AAAAAAA_SITE_KEY",
"pageAction": "login",
"data": "c0bd4b36-7419-4e18-83c6-378699f2a9a2"
}
}
```
## リクエスト例
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "TurnstileTaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "0x4AAAAAAA_SITE_KEY"
}
}
```
**curl**
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "TurnstileTaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "0x4AAAAAAA_SITE_KEY"
}
}'
# 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"}'
```
**Python**
solve.py
```python
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": "TurnstileTaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "0x4AAAAAAA_SITE_KEY",
})
print(solution["token"])
```
**Node.js**
solve.mjs
```js
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: "TurnstileTaskProxyless",
websiteURL: "https://example.com/login",
websiteKey: "0x4AAAAAAA_SITE_KEY",
});
console.log(solution.token);
```
`websiteURL` と `websiteKey` は、対象サイトの値に置き換えてください。
## 返却結果
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"token": "0.ufq5RgSVZd11DPSX1brdrxnEs28KcVlKj2ORchqxSy2q9yAW6ciq3hriXDF4x...",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36"
}
}
```
| フィールド | 型 | 説明 |
| --- | --- | --- |
| `token` | string | 対象サイトに送信するトークン。1 回限りの使用です。できるだけ早く送信してください |
| `userAgent` | string | トークンの取得に使用した User-Agent。トークンを送信する際はこの値を使用してください。送信した値と異なる場合もこちらが優先されます |
`token` をページの `cf-turnstile-response` フィールド(または対象サイトの API が要求するフィールド)に設定して送信します。送信リクエストの User-Agent には、返却された `userAgent` を使用してください。
処理中の場合は `{"errorId": 0, "status": "processing"}` が返るので、5 秒後に再度取得してください。エラーが発生した場合は `errorCode` に応じて対処してください。[エラーコード](https://docs.yescaptcha.com/ja/api/errors.md)を参照してください。
## よくある質問
### token の有効期間はどれくらいですか?
1 回限り有効です。取得後はできるだけ早く送信してください(Turnstile の token は通常数分以内に失効します。失効時間は Cloudflare が決定します)。
### 送信してもサイトで通過しません
`websiteURL` が検証ウィジェットの表示されるページであること、`websiteKey` が正しいことを確認し、送信時には返却された `userAgent` を使用してください。ページが `action` や `cData` を渡している場合は、`pageAction` と `data` として指定してください。上記の[どうしても通らない場合](#%E3%81%A9%E3%81%86%E3%81%97%E3%81%A6%E3%82%82%E9%80%9A%E3%82%89%E3%81%AA%E3%81%84%E5%A0%B4%E5%90%88pageaction-%E3%81%A8-data)を参照してください。サイトが IP も検査している場合は、`TurnstileTask` を使用し、送信時にも同じプロキシを経由してください。
## 関連チュートリアル
- [キャプチャの種類の見分け方](https://docs.yescaptcha.com/ja/guides/identify-captcha.md)
- [Turnstile パラメーターの見つけ方](https://docs.yescaptcha.com/ja/guides/find-turnstile-parameters.md)
---
# Cloudflare チャレンジページ
> YesCaptcha で Cloudflare の「しばらくお待ちください」チェックページ(Cloudflare チャレンジページ)を通過し、cf_clearance などの Cookie、User-Agent、ページ内容を取得します。CloudFlareTaskS2、CloudFlareTaskS3 のパラメーター、プロキシの要件、返却結果、結果の使い方、よくあるエラーを解説します。
Source: https://docs.yescaptcha.com/ja/tasks/cloudflare-challenge/ · Last verified: 2026-10-19
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/cloudflare-challenge/
Cloudflare チャレンジページは、サイト全体が Cloudflare にブロックされ、「しばらくお待ちください…」「ブラウザを確認しています」と表示されるチェックページです。YesCaptcha は指定されたプロキシ経由でページを開いてチェックを通過し、`cf_clearance` などの Cookie、使用した User-Agent、リクエストヘッダー、レスポンスヘッダー、通過後のページ HTML を返します。`CloudFlareTaskS2` は 1 タスクあたり 25 ポイント（約 $3.75 / 1k）、`CloudFlareTaskS3` は 1 タスクあたり 20 ポイント（約 $3.00 / 1k） です。2 つのタイプはパラメーター、返却結果、効果が同じで、価格だけが異なります。非同期で結果を返し、1 タスクあたり通常 6〜35 秒かかります(サイトによって大きく異なります)。認識に失敗した場合やタイムアウトした場合は自動で返金されます。
- POST `https://api.yescaptcha.com/createTask` (グローバルエンドポイント)
- POST `https://cn.yescaptcha.com/createTask` (中国エンドポイント)
## 利用場面
- ページのソースに `__cf_chl_rt_tk` または `cdn-cgi/challenge-platform` が含まれ、タイトルが `Just a moment...` / 「しばらくお待ちください」の場合は、Cloudflare チャレンジページです。チェックページ上で「人間であることを確認します」のチェックボックスをクリックする形式も、このページの対象です。
- フォームに Cloudflare の認証ウィジェットが埋め込まれているだけの場合は [Turnstile](https://docs.yescaptcha.com/ja/tasks/turnstile.md) です。このページの対象ではありません。
- requests などのライブラリでリクエストすると 403 と「Just a moment…」が返るのに、ブラウザでは直接開ける場合は、多くの場合 TLS フィンガープリントでブロックされているだけです。ブラウザの TLS フィンガープリントを模倣できるライブラリ(curl\_cffi など)に切り替えればリクエストできます。チャレンジの通過は不要です。
## タイプと価格
| タスクタイプ | 価格 | 返却方式 | 備考 |
| --- | --- | --- | --- |
| `CloudFlareTaskS2` | $3.75 / 1k; 25 ポイント/タスク · ¥25 / 1k | 非同期 | プロキシ持ち込み |
| `CloudFlareTaskS3` | $3.00 / 1k; 20 ポイント/タスク · ¥20 / 1k | 非同期 | プロキシ持ち込み |
米ドル価格は US$1 ≈ ¥6.67 での概算です。タスクはポイントで課金されます。
## リクエストパラメーター
| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `type` | string | はい | タスクタイプ。値はこのページの「タイプと料金」を参照してください |
| `websiteURL` | string | はい | チャレンジページの背後にあるページの完全な URL。公開された `http://` または `https://` の URL のみ指定できます。プライベート IP アドレスや、`localhost` などのローカル・内部ホスト名は拒否されます |
| `proxy` | string | はい | プロキシを 1 つの文字列で指定します：`http://user:pass@proxy.example.com:8080`（HTTP プロキシ、認証情報は省略可）または `socks5://proxy.example.com:1080`（認証情報なし）。`https://` プロキシおよび認証情報付きの SOCKS5 はサポートされず、ローカルアドレスやプライベートアドレスは拒否されます。対象ページへのすべてのリクエストはこのプロキシ経由で送信されます |
| `userAgent` | string | いいえ | 通常は指定不要です。Linux デスクトップ版 Chrome の User-Agent のみが使用され、それ以外（Windows、macOS、モバイル、他のブラウザ）は無視されます。以降のリクエストでは、必ず結果に含まれる `user_agent` を使用してください |
| `waitLoad` | boolean | いいえ | デフォルトは false。true を指定すると、チェック通過後にページのネットワーク通信が落ち着くまで待ってから結果を返すため、`content` に動的に読み込まれたコンテンツがより多く含まれます。数秒長くかかります |
| `requiredCookies` | array | いいえ | 必ず取得する Cookie 名のリスト（文字列の配列）。例：`["cf_clearance"]`。指定した場合は、すべて取得できたときのみ成功となり、取得できなければ `ERROR_CAPTCHA_UNSOLVABLE` を返して返金されます。省略した場合も `cf_clearance` の取得を試みますが、取得できず他の Cookie だけを取得した場合でも成功として課金されます。`cf_clearance` が必要な場合は明示的に指定してください |
| `blockImage` | boolean | いいえ | true を指定すると、対象ページの画像を読み込みません（Cloudflare のチェック自体に必要なものを除く）。プロキシのトラフィックを節約できます |
| `postData` | object | いいえ | 指定すると、通常の HTML フォームの POST として `websiteURL` に送信されます（`application/x-www-form-urlencoded`）。各キーがフォームのフィールドとなり、値は文字列として送信されます。例：`{"name": "hi"}`。オブジェクトである必要があります |
### プロキシの要件
`proxy` は必須です。対象ページを開くすべてのリクエストがこのプロキシ経由になります。`cf_clearance` は出口 IP に紐づくため、その後に対象サイトへアクセスするときも同じプロキシを使ってください。
| 書式 | 対応状況 |
| --- | --- |
| `http://user:pass@proxy.example.com:8080` | 対応: http プロキシ(ユーザー名・パスワードあり) |
| `http://proxy.example.com:8080` | 対応: http プロキシ(ユーザー名・パスワードなし) |
| `socks5://proxy.example.com:1080` | 対応: socks5 プロキシ(ユーザー名・パスワードなし)。`socks5h://` は `socks5://` として扱われます |
| `socks5://user:pass@proxy.example.com:1080` | 非対応。`ERROR_PROXY_INCORRECT` を返します。ユーザー名・パスワードが必要な場合は http プロキシを使用してください |
| `https://proxy.example.com:443` などのその他のプロトコル、またはポートなし | 非対応。`ERROR_PROXY_INCORRECT` を返します |
| `127.0.0.1`、`192.168.x.x`、`10.x.x.x` などのローカル、内部ネットワーク、予約アドレス、またはそれらに解決されるドメイン | 拒否。`ERROR_PROXY_BANNED` を返します |
> **タスク作成時にチェックされます:** URL やプロキシが不正な場合、`createTask` はすぐにエラーを返し、課金されません。同じプロキシで短時間に何度も接続に失敗すると、しばらくの間そのプロキシでタスクを作成しても `ERROR_PROXY_BANNED` が直接返されます。プロキシを変更するか、しばらくしてからもう一度お試しください。
### User-Agent
通常、`userAgent` は指定しません。チェックの通過には Linux デスクトップ版の Chrome を使用するため、同じ Linux デスクトップ版 Chrome の User-Agent だけが採用され、それ以外(Windows、macOS、モバイル、他のブラウザー)は無視されます。実測では、ブラウザーの実際の環境と User-Agent が一致しない場合、Cloudflare のチェックを通過できませんでした。以降のリクエストでは、必ず結果に含まれる `user_agent` を使用してください。
## リクエスト例
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "CloudFlareTaskS3",
"websiteURL": "https://example.com/",
"proxy": "http://user:pass@proxy.example.com:8080",
"requiredCookies": ["cf_clearance"]
}
}
```
- `CloudFlareTaskS2` を使う場合は `type` だけを変更し、他はそのままにします。
- `requiredCookies` に `["cf_clearance"]` を指定すると、`cf_clearance` を取得できなかった場合にタスクが失敗し、返金されます。指定しない場合は、`cf_clearance` を取得できず他の Cookie だけを取得した場合も成功とみなされ、課金されます。
- フォームを送信する場合は `postData` を追加します(例: `{"name": "hi"}`)。`websiteURL` に POST フォームとして送信されます。
作成後は 5 秒ごとに `getTaskResult` を呼び出します。流れは他の非同期タスクと同じです。[getTaskResult](https://docs.yescaptcha.com/ja/api/get-task-result.md) を参照してください。
## 返却結果
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36",
"cookies": {
"cf_clearance": "Wq3vXk9...-1760860800-1.2.1.1-..."
},
"request_headers": {
"accept-language": "en-US,en;q=0.9",
"user-agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36"
},
"headers": {
"content-type": "text/html; charset=UTF-8",
"server": "cloudflare"
},
"content": "..."
}
}
```
上記の Cookie 値とリクエストヘッダーは例です。実際の値は返却結果に従ってください。
| フィールド | 型 | 説明 |
| --- | --- | --- |
| `cookies` | object | チェック通過後のブラウザ内のすべての Cookie（名前から値へのオブジェクト）。通常は `cf_clearance` を含みます。`requiredCookies` を指定した場合は、そのすべてが含まれます。返された `user_agent` および指定したプロキシと併せて使用してください |
| `user_agent` | string | ブラウザがチェック通過時に実際に使用した User-Agent（Linux デスクトップ版 Chrome）。`cf_clearance` はこれに紐づいているため、以降のすべてのリクエストでこの値を使用してください |
| `request_headers` | object | ブラウザが対象ページに対して最後に送信したリクエストヘッダー。以降のリクエストでも同じものを付けて再利用してください |
| `headers` | object | チェック通過後の対象ページのレスポンスヘッダー |
| `content` | string | チェック通過後の対象ページの HTML ソース |
## 結果の使い方
1. 以降のリクエストでは、返された `cookies`、返された `user_agent`、タスク作成時と同じプロキシを**すべて同時に**使用してください。`cf_clearance` は User-Agent と出口 IP に紐づいており、どれか 1 つでも一致しないと、再びチャレンジページが表示されます。
2. リクエストヘッダーは、できるだけ `request_headers` のとおりに付与し、ブラウザーと同じ TLS フィンガープリントを使用してください(例: curl\_cffi の `impersonate` パラメーター)。
3. `cf_clearance` には有効期限があります(対象サイトが設定し、最長 1 時間のサイトもあります)。有効期間内は再度チャレンジを通過する必要はありませんが、リクエストの頻度が高すぎると Cloudflare に IP をブロックされる場合があります。
4. ページ内容だけが必要な場合は、`content` をそのまま使えます。もう一度ページをリクエストする必要はありません。
## よくあるエラー
タスク作成時に返されたエラーは課金されません。作成後に失敗またはタイムアウトしたタスクは自動で返金されます。API が返すのはエラーコードと汎用的な説明のみのため、具体的な原因は次の表で確認してください。
| エラーコード | 返される場面 | 対処 |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | タスク作成時: `websiteURL` または `proxy` がない | 必須の 2 つのフィールドを追加する |
| `ERROR_ILLEGAL_PARAMETERS` | タスク作成時: `websiteURL` が `http://` / `https://` で始まる公開 URL ではない、`postData` がオブジェクトではない、`requiredCookies` が文字列の配列ではない。結果取得時: プロキシ経由で対象 URL のドメインを解決できない | パラメーターを修正する。URL のスペルと、プロキシからそのサイトにアクセスできるかを確認する |
| `ERROR_PROXY_INCORRECT` | タスク作成時: プロキシの書式が正しくない、ポートがない、`https://` プロキシまたはユーザー名・パスワード付きの socks5 を使用している | 上記「プロキシの要件」の書式に修正する。ユーザー名・パスワードが必要な場合は http プロキシを使用する |
| `ERROR_PROXY_BANNED` | タスク作成時: プロキシがローカル、内部ネットワーク、予約アドレスである、またはこのプロキシが短時間に何度も接続に失敗した。結果取得時: 対象サイトの Cloudflare がこのプロキシの IP を直接ブロックした(「Sorry, you have been blocked」「Access denied」ページ) | プロキシを変更する。IP の品質が高いほど通過しやすい |
| `ERROR_PROXY_CONNECT_REFUSED` | プロキシに接続できない(接続拒否、プロキシのドメインを解決できない)、またはプロキシ経由でページを開く際に接続が拒否・リセットされた | プロキシのアドレスとポートを確認し、プロキシがオンラインで外部からのアクセスを許可しているかを確認する。それでも失敗する場合はプロキシを変更する |
| `ERROR_PROXY_CONNECT_TIMEOUT` | プロキシへの接続、またはプロキシ経由でのページ表示がタイムアウトした | より高速で安定したプロキシに変更する |
| `ERROR_PROXY_NOT_AUTHORISED` | プロキシのユーザー名またはパスワードが正しくない | `proxy` 内のユーザー名とパスワードを確認する。特殊文字は URL エンコードする |
| `ERROR_PROXY_TLS_ERROR` | プロキシ経由でページを開く際に TLS ハンドシェイクでエラーが発生した | プロキシのアドレス、ポート、プロトコルに誤りがないか確認する。それでも失敗する場合はプロキシを変更する |
| `ERROR_CAPTCHA_UNSOLVABLE` | 規定時間内にチェックを通過できなかった、通過後もチェックページのままだった、または `requiredCookies` で指定した Cookie を取得できなかった | まずプロキシを変更して再試行する。特定のサイトについてはサポートにお問い合わせください |
| `ERROR_NO_SLOT_AVAILABLE` | タスク作成時: キューが満杯。結果取得時: キューで長く待機しても開始されず、返金済み | 数秒待ってからタスクを作り直す |
| `ERROR_TASK_TIMEOUT` | タスクが規定時間内に完了しなかった | タスクを作り直す。タイムアウトが続く場合は、多くはプロキシが遅すぎることが原因 |
すべてのエラーコードは[エラーコード](https://docs.yescaptcha.com/ja/api/errors.md)を参照してください。
## 関連
- [キャプチャの種類を見分ける](https://docs.yescaptcha.com/ja/guides/identify-captcha.md): Cloudflare チャレンジページと Turnstile の違い
- [Cloudflare Turnstile](https://docs.yescaptcha.com/ja/tasks/turnstile.md)
---
# 画像の英数字認識
> YesCaptcha で画像内の英字と数字を認識します。ImageToTextTaskOcrBase と ImageToTextTaskMuggle は同期で結果を返し、ImageToTextTask と ImageToTextTaskM1 は非同期で、大文字小文字の区別、数字のみ、計算式などの条件に対応します。モデルのカスタマイズも可能です。
Source: https://docs.yescaptcha.com/ja/tasks/image-to-text/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/image-to-text/
文字キャプチャの画像を Base64 に変換して送信すると、画像内の英字と数字(`solution.text`)が返ります。`ImageToTextTaskOcrBase` は 1 枚あたり 2 ポイント（約 $0.30 / 1k） で、同期で結果を返します。つまり 1 回の `createTask` リクエストで結果を取得できます。大文字小文字の区別、数字のみ、計算式などの条件を指定する場合は、非同期の `ImageToTextTask` を使用してください。
- POST `https://api.yescaptcha.com/createTask` (グローバルエンドポイント)
- POST `https://cn.yescaptcha.com/createTask` (中国エンドポイント)
リクエストボディは JSON で、`clientKey` で認証します。
## タイプと価格
| タスクタイプ | 価格 | 返却方式 | 備考 |
| --- | --- | --- | --- |
| `ImageToTextTaskOcrBase` | $0.30 / 1k; 2 ポイント/タスク · ¥2 / 1k | 同期 | |
| `ImageToTextTaskMuggle` | $0.30 / 1k; 2 ポイント/タスク · ¥2 / 1k | 同期 | case や numeric などのオプションには対応していません。project\_name でカスタムモデルを指定できます |
| `ImageToTextTask` | $0.60 / 1k; 4 ポイント/タスク · ¥4 / 1k | 非同期 | |
| `ImageToTextTaskM1` | $2.25 / 1k; 15 ポイント/タスク · ¥15 / 1k | 非同期 | |
米ドル価格は US$1 ≈ ¥6.67 での概算です。タスクはポイントで課金されます。
| 用途 | 使用するタイプ |
| --- | --- |
| 一般的な英数字キャプチャ(最も安価で高速) | `ImageToTextTaskOcrBase`、`ImageToTextTaskMuggle`(同期) |
| 専用にカスタマイズしたモデルで認識する | `ImageToTextTaskMuggle` に `project_name` を指定 |
| 大文字小文字の区別、数字のみ、計算式の評価、文字数の制限が必要 | `ImageToTextTask`、`ImageToTextTaskM1`(非同期) |
タイプごとにモデルと経路が異なるため、同じ種類の画像でも結果が変わることがあります。いくつか試してから選んでください。
## リクエストパラメータ
| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `type` | string | はい | タスクタイプ。値はこのページの「タイプと料金」を参照してください |
| `body` | string | はい | 画像の Base64 エンコード文字列。`data:image/...;base64,` のプレフィックスと改行は含めないでください |
| `project_name` | string | いいえ | カスタムモデルの名前。`ImageToTextTaskMuggle` のみ対応しています。指定しない場合は汎用の英数字モデルが使われます。カスタムモデルが必要な場合はサポートまでお問い合わせください（ImageToTextTaskMuggle のみ） |
| `phrase` | boolean | いいえ | true の場合、答えに少なくとも 1 つのスペースが含まれます（ImageToTextTask、ImageToTextTaskM1 のみ） |
| `case` | boolean | いいえ | true の場合、答えは大文字と小文字を区別します（ImageToTextTask、ImageToTextTaskM1 のみ） |
| `numeric` | integer | いいえ | 0 は指定なし、1 は数字のみ、2 は数字を含まない（ImageToTextTask、ImageToTextTaskM1 のみ） |
| `math` | boolean | いいえ | true の場合、画像は計算式であり、答えはその計算結果です（ImageToTextTask、ImageToTextTaskM1 のみ） |
| `minLength` | integer | いいえ | 答えの最小の長さ。0 は制限なし（ImageToTextTask、ImageToTextTaskM1 のみ） |
| `maxLength` | integer | いいえ | 答えの最大の長さ。0 は制限なし（ImageToTextTask、ImageToTextTaskM1 のみ） |
`body` は画像ファイルの Base64 エンコードです。WebP 画像は自動的に変換されます。
> **注意:** Base64 に `data:image/...;base64,` プレフィックスや改行を含めないでください。
## リクエスト例
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "ImageToTextTaskOcrBase",
"body": "BASE64_IMAGE"
}
}
```
完全なコード(カレントディレクトリの `captcha.png` を読み込みます):
**curl**
```bash
# Replace BASE64_IMAGE with the Base64-encoded image
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "ImageToTextTaskOcrBase",
"body": "BASE64_IMAGE"
}
}'
```
**Python**
solve.py
```python
import os
import base64
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):
return call("createTask", {"task": task})["solution"]
# Base64-encode the image (no data: prefix)
with open("captcha.png", "rb") as f:
image_b64 = base64.b64encode(f.read()).decode()
solution = solve({
"type": "ImageToTextTaskOcrBase",
"body": image_b64,
})
print(solution["text"])
```
**Node.js**
solve.mjs
```js
import { readFileSync } from 'node:fs';
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 { solution } = await call('createTask', { task });
return solution;
}
// Base64-encode the image (no data: prefix)
const imageB64 = readFileSync('captcha.png').toString('base64');
const solution = await solve({
type: "ImageToTextTaskOcrBase",
body: imageB64,
});
console.log(solution.text);
```
条件付きの非同期タスク:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "ImageToTextTask",
"body": "BASE64_IMAGE",
"case": true,
"numeric": 0,
"minLength": 4,
"maxLength": 6
}
}
```
## レスポンス
同期タイプは `createTask` のレスポンスで直接結果を返します。
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"text": "LMResm"
},
"taskId": "2376919c-1863-11ec-a012-94e6f7355a0b"
}
```
非同期タイプ(`ImageToTextTask`、`ImageToTextTaskM1`)はまず `taskId` を返します。その後 5 秒ごとに `getTaskResult` でポーリングしてください。完了時の `solution` の形式は同じです。
| フィールド | 型 | 説明 |
| --- | --- | --- |
| `text` | string | 認識されたテキスト |
## カスタムモデル
汎用モデルはあらゆる英数字キャプチャに使えますが、特定のスタイル向けに学習したモデルよりは精度がやや下がります。認識したい画像が常に同じスタイルであれば、[サポートに問い合わせて](https://docs.yescaptcha.com/ja/help/contact.md)モデルをカスタマイズできます。作成後は `ImageToTextTaskMuggle` に `project_name` を指定して使用します。
## よくある質問
### 認識結果が間違っていた場合も課金されますか?
同期タイプは、結果が返された時点で課金されます。結果が誤っていても同様です。別のタイプで比較するか、モデルのカスタマイズをご検討ください。
### `ERROR_ZERO_CAPTCHA_FILESIZE` または `ERROR_PARSE_IMAGE_FAIL` が返ります
画像の Base64 が不完全であるか、`data:` プレフィックスや改行が含まれています。エンコードを確認してください。詳しくは[エラーコード](https://docs.yescaptcha.com/ja/api/errors.md)をご覧ください。
## 関連サンプル
- [クイックスタート](https://docs.yescaptcha.com/ja/getting-started/quickstart.md): `ImageToTextTaskOcrBase` で最初のリクエストを送信
- [Python サンプル](https://docs.yescaptcha.com/ja/samples/python.md)
---
# reCAPTCHA v2 画像認識
> YesCaptcha で reCAPTCHA v2 の画像問題（ReCaptchaV2Classification）を認識。3x3、4x4、1x1 の画像と問題 ID を送信すると、クリックするマスが同期で返ります。料金は画像サイズ別、問題 ID 対応表つき。
Source: https://docs.yescaptcha.com/ja/tasks/recaptcha-classification/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/recaptcha-classification/
`ReCaptchaV2Classification` は reCAPTCHA v2 に表示される画像問題を認識します。画像と問題 ID を送信すると、クリックすべきマスが返るので、ブラウザ上でのクリックはご自身のプログラムで行います。**token は返しません**。同期で結果が返り、`createTask` を 1 回呼ぶだけで取得できます。3x3、4x4 の画像は 1 枚あたり 6 ポイント（約 $0.90 / 1k）、1x1 の小さな画像はそれより安くなります（下表参照）。
> **ヒント:** クリック処理を自分で書きたくない場合は、このインターフェースを使って自動でクリックする [ブラウザ拡張機能](https://docs.yescaptcha.com/ja/extension.md) を利用できます。
- POST `https://api.yescaptcha.com/createTask` (グローバルエンドポイント)
- POST `https://cn.yescaptcha.com/createTask` (中国エンドポイント)
## タイプと料金
| タスクタイプ | 価格 | 返却方式 | 備考 |
| --- | --- | --- | --- |
| `ReCaptchaV2Classification` | $0.90 / 1k; 6 ポイント/タスク · ¥6 / 1k | 同期 | 1x1 のタイル（100x100）は 2 ポイント、3x3（300x300）と 4x4（450x450）は 6 ポイント |
米ドル価格は US$1 ≈ ¥6.67 での概算です。タスクはポイントで課金されます。
## リクエストパラメータ
| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `type` | string | はい | タスクタイプ。値はこのページの「タイプと料金」を参照してください |
| `image` | string | はい | 問題画像の Base64 エンコード文字列。`data:` のプレフィックスは含めないでください |
| `question` | string | はい | `/m/0k4j` のような問題 ID。このページの「問題 ID」を参照してください |
| `confidence` | number | いいえ | 信頼度のしきい値（0〜1）。3x3 の画像にのみ使用されます。指定すると（0.5 から試すのがおすすめ）、この値を超えるすべてのタイルが返されます。省略すると、可能性の高い上位 3 つのタイルが返されます |
> **注意:** 画像は下表の標準サイズに縮小・拡大してください。サーバーはサイズから問題の種類を判断します。
| 問題の種類 | 画像サイズ | 返り値 |
| --- | --- | --- |
| 3x3 グリッド（「該当する画像をすべて選択」） | 300 × 300 | `objects`：クリックするマス |
| 4x4 グリッド（「該当するタイルをすべて選択」） | 450 × 450 | `objects`：クリックするマス |
| 1x1 小画像（3x3 をクリックした後に更新されて表示される単一の画像） | 100 × 100 | `hasObject`：この画像をクリックすべきか |
スクリーンショットの場合は問題文で判断してください。3x3 は「該当する画像をすべて選択」（Select all images with …）、4x4 は「該当するタイルをすべて選択」（Select all squares with …）です。
## リクエスト例
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "ReCaptchaV2Classification",
"image": "BASE64_IMAGE",
"question": "/m/0k4j"
}
}
```
## 返り値
3x3、4x4：
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"objects": [1, 5, 8],
"type": "multi"
},
"taskId": "3a9e8cb8-3871-11ec-9794-94e6f7355a0b"
}
```
1x1 小画像：
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"hasObject": true,
"type": "single"
}
}
```
| フィールド | 型 | 説明 |
| --- | --- | --- |
| `objects` | array | クリックするタイルのインデックス。0 から始まり、左から右、上から下の順です |
| `hasObject` | boolean | 1x1 のタイルの場合に返されます。タイルに対象が含まれているかどうかを示します |
| `type` | string | 問題タイプ: `multi`(3x3 または 4x4 の画像。`objects` を参照)、`single`(1x1 のタイル。`hasObject` を参照)。hCaptcha のドラッグ問題は `drag` です |
マスの番号は 0 から始まり、左から右、上から下の順です。
## confidence：該当するマスを一度にすべて取得
3x3 の問題はクリック後に 1x1 の小画像が更新表示され、続けて判定が必要になることがあります。小画像の取得が難しい場合（モバイル端末での開発など）は、`confidence` を指定できます。
- 指定しない場合、3x3 の画像ではスコアが最も高い 3 つのマスを返します（reCAPTCHA は最低 3 つのクリックを要求します）。
- 指定した場合（`0.5` を推奨）、この値を超えるスコアのマスをすべて返します。3 つより多くなることも少なくなることもあり、該当がなければ空配列が返ります。これにより 1x1 小画像を別途キャプチャする必要がなくなります。
- 4x4 と 1x1 の画像には効果がありません。
## 問題 ID
`question` には問題文ではなく、問題の ID（`/m/` で始まるもの）を指定します。ID は、reCAPTCHA が問題を読み込むリクエスト（`reload` または `userverify`）のレスポンスに、画像と一緒に含まれています。下表はよくある問題です。中国語の表記は参考用です。
全 16 種類
| 問題 ID | 問題文（英語） |
| --- | --- |
| `/m/0pg52` | `taxis` |
| `/m/01bjv` | `bus` |
| `/m/04_sv` | `motorcycles` |
| `/m/013xlm` | `tractors` |
| `/m/01jk_4` | `chimneys` |
| `/m/014xcs` | `crosswalks` |
| `/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` |
一致する問題文がありません
`ERROR_UNKNOWN_QUESTION` が返る場合は、ID が誤っているか、この問題が未対応です。`ERROR_UNKNOW_450x450_QUESTION` が返る場合は、この問題が 4x4 画像に未対応です。ページ上で更新して別の問題に切り替えてください。
## 報告と返金
クリック後に認証が失敗した場合は、1 時間以内に [report](https://docs.yescaptcha.com/ja/api/report.md) で報告できます。約 24 時間後に返金が確定します。ルールは [課金と返金](https://docs.yescaptcha.com/ja/getting-started/billing.md) を参照してください。認証に成功した場合も、report で `isSuccess: true` を報告してください。
## 関連チュートリアル
- [reCAPTCHA v2 画像認識によるクリックのシミュレーション（Selenium）](https://docs.yescaptcha.com/ja/guides/recaptcha-click-selenium.md)
- [reCAPTCHA v2（token を返す）](https://docs.yescaptcha.com/ja/tasks/recaptcha-v2.md)
---
# hCaptcha 画像認識
> YesCaptcha で hCaptcha の画像問題（HCaptchaClassification）を認識します。3×3 グリッドの選択、指定位置のクリック、指定位置へのドラッグ、アニメーション問題に対応。同期で結果を返し、対象が見つからなかった場合は課金されません。
Source: https://docs.yescaptcha.com/ja/tasks/hcaptcha-classification/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/hcaptcha-classification/
`HCaptchaClassification` は hCaptcha が表示する画像問題を認識します。問題文と画像を送ると、どの画像を選ぶか、どの位置をクリックするか、どこからどこへドラッグするかが返ります。ブラウザ上での操作はお使いのプログラムで行います。**token は返しません**。同期で結果を返し、1 回あたり 8 ポイント（約 $1.20 / 1k）。対象が見つからなかった場合（結果が空の場合）は課金されません。
> **ヒント:** クリック処理を自分で書きたくない場合は、[ブラウザ拡張機能](https://docs.yescaptcha.com/ja/extension.md)をそのまま使えます。ここで説明する問題形式にはすべて対応しています。クリック位置ではなく token が必要な場合は [hCaptcha](https://docs.yescaptcha.com/ja/tasks/hcaptcha.md) を使ってください。
- POST `https://api.yescaptcha.com/createTask` (グローバルエンドポイント)
- POST `https://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
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "HCaptchaClassification",
"question": "Please click each image containing a bicycle",
"queries": ["BASE64_IMAGE_1", "BASE64_IMAGE_2"]
}
}
```
レスポンス:
```json
{
"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
```json
{
"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"]
}
}
```
レスポンス:
```json
{
"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 つずつドラッグします。
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"type": "drag",
"box": [
{
"start": [644, 218],
"end": [239, 315]
}
]
}
}
```
スクリーンショットではなくプロトコルのデータ（ピースの画像、ピースの座標、背景の大きな画像）を取得している場合は、座標に従ってピースを背景画像に合成し、ページのスクリーンショットと同じ見た目の画像にしてから送信してください。
## アニメーション問題
問題の画像がアニメーションの場合は、アニメーション（GIF などの形式）の Base64 を `queries` に入れます。アニメーションの長さは 3 秒以上、できれば 5〜6 秒、フレームレートは約 12 FPS を推奨します。
## 報告と返金
クリック後に検証に失敗した場合は、1 時間以内に [report](https://docs.yescaptcha.com/ja/api/report.md) で報告できます。約 24 時間後に報告による返金が確定します。ルールは[課金と返金](https://docs.yescaptcha.com/ja/getting-started/billing.md)をご覧ください。
## 関連チュートリアル
- [hCaptcha 画像認識でクリックをシミュレートする（Selenium）](https://docs.yescaptcha.com/ja/guides/hcaptcha-click-selenium.md)
---
# FunCaptcha 画像認識
> YesCaptcha で FunCaptcha（Arkose Labs）の画像問題（FunCaptchaClassification）を認識します。問題画像（6 分割グリッド、または左右に結合した矢印問題）と英語の問題文を送信すると、選ぶべき画像の番号が同期で返ります。すべての問題タイプに対応しています。
Source: https://docs.yescaptcha.com/ja/tasks/funcaptcha-classification/ · Last verified: 2026-10-16
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/funcaptcha-classification/
`FunCaptchaClassification` は FunCaptcha（Arkose Labs）の画像問題を認識します。問題画像と英語の問題文を送信すると、選ぶべき画像の番号が返るので、プログラムでブラウザ上のその画像をクリックします。token は**返しません**。同期で結果が返り、1 回あたり 3 ポイント（約 $0.45 / 1k） です。
> **ヒント:** コードを書かない場合は[ブラウザ拡張機能](https://docs.yescaptcha.com/ja/extension.md)を使うと、ページ上で自動的に処理できます。
- POST `https://api.yescaptcha.com/createTask` (グローバルエンドポイント)
- POST `https://cn.yescaptcha.com/createTask` (中国エンドポイント)
## タスクタイプと料金
| タスクタイプ | 価格 | 返却方式 | 備考 |
| --- | --- | --- | --- |
| `FunCaptchaClassification` | $0.45 / 1k; 3 ポイント/タスク · ¥3 / 1k | 同期 | |
米ドル価格は US$1 ≈ ¥6.67 での概算です。タスクはポイントで課金されます。
## リクエストパラメーター
| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `type` | string | はい | タスクタイプ。値はこのページの「タイプと料金」を参照してください |
| `image` | string | はい | 問題画像の Base64 エンコード文字列。`data:` のプレフィックスは含めないでください |
| `question` | string | はい | 英語の問題文（例: `Pick the image that is the correct way up`）。対応している問題はこのページに記載しています |
- `image` には問題の画像部分（6 分割グリッド、または左右に結合した矢印問題の画像）だけを入れてください。上のタイトルやボタンは含めないでください。スクリーンショットは欠けがないようにしてください。一部でも欠けると認識精度に影響します。縦並びの 6 分割グリッドは元の画像をそのままアップロードできます。
- `question` にはページに表示されている英語の問題文を全文そのまま、大文字と小文字も正確に指定してください。自分で翻訳しないでください。ページが他の言語の場合は、先にキャプチャの言語を英語に切り替えてください。サーバー側は問題文から問題タイプを判定するため、問題文は正確である必要があります。
## リクエスト例
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "FunCaptchaClassification",
"image": "BASE64_IMAGE",
"question": "Pick the bread"
}
}
```
## 返却結果
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"objects": [4],
"labels": ["parrot", "panda", "octopus", "owl", "bread", "dog"]
},
"taskId": "04a3fa76-11a0-11ed-a58c-0ef20f419382"
}
```
| フィールド | 型 | 説明 |
| --- | --- | --- |
| `objects` | array | 選択する画像のインデックス。0 から始まり、左から右、上から下の順です |
| `labels` | array | 認識されたラベル |
`objects: [4]` は 5 番目の画像を選ぶことを表します（番号は 0 から始まり、左から右、上から下の順）。1 つのチャレンジは何ラウンドも続くことが多く、ラウンドごとにスクリーンショットを撮り直して、そのつどリクエストしてください。
## 対応する問題
**すべての問題タイプに対応**しているため、事前に問題の一覧を確認する必要はありません。ページ上の英語の問題文と問題画像をそのまま送信してください。`ERROR_UNKNOWN_QUESTION` が返った場合は、[サポートにお問い合わせ](https://docs.yescaptcha.com/ja/help/contact.md)ください。
現在よく出るのは、左右に結合した矢印問題です。左側が照合する例、右側が現在の画像で、ページ上の矢印で右側の画像を切り替え、問題文に合う画像を探します。ページに表示されているとおり、画像全体（左右両方）をアップロードしてください。例：
`Use the arrows to change the number of objects until it matches the left image`数が左の画像と一致する
`use the arrows to choose the image where all the darts add up to the number in the left image`ダーツの数字の合計が左の画像の数になる
`use the arrows to find the jigsaw puzzle that is missing the puzzle piece shown on the left`足りないのがまさに左のピース
`find the image that has the prize on the left held by the claw in the machine on the right`アームが左の景品をつかんでいる
もう 1 つは 6 分割グリッドの画像選択問題（`Pick the bread` など）です。6 分割グリッドの部分をアップロードしてください。上のリクエスト例を参照してください。
## 報告と返金
1 組の問題で最終的な送信に失敗し、どのラウンドが誤っていたか分からない場合は、その組のタスク ID をまとめて [report](https://docs.yescaptcha.com/ja/api/report.md) で報告できます（1 時間以内）。約 24 時間後に報告による返金が精算されます。ルールは[課金と返金](https://docs.yescaptcha.com/ja/getting-started/billing.md)を参照してください。
---
# AWS WAF / bCaptcha 画像認識
> YesCaptcha で AWS WAF CAPTCHA と bCaptcha の 3×3 グリッド画像問題を認識します（AwsClassification、bCaptchaClassification）。画像全体と問題文を送信すると、クリックするマスが同期で返ります。
Source: https://docs.yescaptcha.com/ja/tasks/aws-bcaptcha-classification/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/aws-bcaptcha-classification/
`AwsClassification` は AWS WAF CAPTCHA の 3×3 グリッド画像問題を、`bCaptchaClassification` は bCaptcha の 3×3 グリッド画像問題を認識します。画像全体と問題文を送ると、クリックすべきマスが返るので、そのマスをお使いのプログラムでブラウザ上でクリックします。**token は返しません**。同期で返り、1 回あたり 8 ポイント（約 $1.20 / 1k） です。
コードを書かない場合は[ブラウザ拡張機能](https://docs.yescaptcha.com/ja/extension.md)を使えます。
- POST `https://api.yescaptcha.com/createTask` (グローバルエンドポイント)
- POST `https://cn.yescaptcha.com/createTask` (中国エンドポイント)
## タスクタイプと料金
| タスクタイプ | 価格 | 返却方式 | 備考 |
| --- | --- | --- | --- |
| `AwsClassification` | $1.20 / 1k; 8 ポイント/タスク · ¥8 / 1k | 同期 | |
| `bCaptchaClassification` | $1.20 / 1k; 8 ポイント/タスク · ¥8 / 1k | 同期 | |
米ドル価格は US$1 ≈ ¥6.67 での概算です。タスクはポイントで課金されます。
2 つのタイプはパラメータも返却形式も同じです。キャプチャの種類に合わせて選んでください。AWS WAF なら `AwsClassification`、bCaptcha なら `bCaptchaClassification` を使います。
## リクエストパラメータ
| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `type` | string | はい | タスクタイプ。値はこのページの「タイプと料金」を参照してください |
| `queries` | string | はい | 3×3 グリッド画像全体の Base64(画像 1 枚) |
| `question` | string | いいえ | ページに表示されている問題文の全文。例: `Select all hats`。他の言語は自動的に翻訳されます |
`queries` には 3×3 グリッドの画像を**全体**で 1 枚渡します（9 枚に分割した小さな画像ではありません）。`question` はページ上の問題文をそのまま渡してください。中国語・英語に対応しており、その他の言語は自動的に翻訳されます。
## リクエスト例
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "AwsClassification",
"queries": "BASE64_IMAGE",
"question": "Select all hats"
}
}
```
## レスポンス
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"label": "Select All Hats",
"objects": [false, true, false, false, true, true, true, true, false],
"top_k": [1, 4, 5, 6, 7],
"confidences": [0.0, 1.0, 0.0, 0.255, 1.0, 1.0, 0.9637, 0.9999, 0.0]
},
"taskId": "2053f690-3c3b-11f0-8ffb-d2c180657082"
}
```
| フィールド | 型 | 説明 |
| --- | --- | --- |
| `label` | string | 認識された問題の対象 |
| `objects` | array | 9 つのセルそれぞれが対象かどうか(true / false)。左から右、上から下の順です |
| `top_k` | array | 対象である画像のインデックス(0 から開始)。`objects` と意味は同じで、どちらか一方を使用すれば十分です |
| `confidences` | array | 各結果の信頼度 |
9 つのマスは 3×3 グリッドで、左から右、上から下の順に 0 から 8 の番号が付きます。`objects` と `top_k` は同じ内容を表すので、どちらか一方を使ってください。`objects` が `true` のマスをクリックするか、`top_k` に含まれる番号のマスをクリックします。
## 報告と返金
クリック後に検証が失敗した場合は、1 時間以内に [report](https://docs.yescaptcha.com/ja/api/report.md) で報告できます。約 24 時間後に報告による返金が精算されます。ルールは[課金と返金](https://docs.yescaptcha.com/ja/getting-started/billing.md)を参照してください。
---
# YesCaptcha Assistant
> YesCaptcha Assistant（ブラウザ拡張機能）は、Chrome と Firefox で reCAPTCHA、hCaptcha、FunCaptcha、AWS WAF などのキャプチャを自動で認識してクリックします。拡張機能は無料で、使用した API の分だけ課金されます。ストアのリンク、インストールパッケージのダウンロード、Chrome・BitBrowser・Kiwi Browser でのインストール動画を掲載しています。
Source: https://docs.yescaptcha.com/ja/extension/ · Last verified: 2026-10-24
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/extension/
YesCaptcha Assistant は、Chrome と Firefox 向けのブラウザ拡張機能です。キャプチャのあるページを開くと、キャプチャの画像を YesCaptcha に送って認識し、自動でクリックします。コードを書く必要はありません。拡張機能自体は無料で、認識時に使用した API の分だけポイントが課金されます。アカウントと残高は API と共通です。
## できること
- reCAPTCHA v2、hCaptcha、FunCaptcha、AWS WAF、bCaptcha の画像問題を自動で認識してクリックします。
- 通常の文字キャプチャ：画像を右クリックして「Mark as captcha source」を選び、入力欄を右クリックして「Put captcha answer here」を選ぶと、拡張機能が認識して入力します。
- 設定で、キャプチャの種類ごとにオン・オフを切り替えたり、クリック速度や失敗時のリトライを調整したりできます。
> **ノート:** すべてのサイトを通過できるわけではありません。まず試してみることをおすすめします。
## インストール
**ストアからインストール（推奨。自動で更新されます）：**
- Chrome（および Edge などの Chromium 系ブラウザ）：[Chrome ウェブストア](https://chromewebstore.google.com/detail/yescaptcha-assistant/jiofmdifioeejeilfkpegipdjiopiekl)
- Firefox：[Firefox アドオン](https://addons.mozilla.org/firefox/addon/yescaptcha-assistant/)
Chrome ウェブストアで拡張機能のページを開き、「Chrome に追加」をクリックします。続いてツールバーの拡張機能アイコンをクリックし、`clientKey` を入力します。
お使いのブラウザでは動画を再生できません。ダウンロードしてご覧ください： [動画：Chrome ウェブストアからのインストール（34 秒）](https://docs.yescaptcha.com/videos/extension-chrome-store.mp4)
動画：Chrome ウェブストアからのインストール（34 秒）
**ストアを開けない場合は、インストールパッケージをダウンロードします：**
Chrome 版
バージョン
1.4.12
サイズ
1.1 MB
更新日
2026-11-10
[ダウンロード](https://api.yescaptcha.com/extension/chrome/latest)[Chrome ウェブストア](https://chromewebstore.google.com/detail/yescaptcha-assistant/jiofmdifioeejeilfkpegipdjiopiekl)
Firefox 版
バージョン
0.4.6
サイズ
0.9 MB
更新日
2026-10-31
[ダウンロード](https://api.yescaptcha.com/extension/firefox/latest)[Firefox アドオン](https://addons.mozilla.org/firefox/addon/yescaptcha-assistant/)
Firefox のストアのバージョンは、ここのパッケージより古い場合があります。最新版が必要な場合はパッケージを使ってください。
### Chrome にパッケージでインストールする
1. zip ファイルをダウンロードし、常設のフォルダに展開します。
2. アドレスバーで `chrome://extensions` を開き、右上の「デベロッパー モード」をオンにします。
3. 「パッケージ化されていない拡張機能を読み込む」をクリックし、展開したフォルダを選択します。
4. ツールバーの拡張機能アイコンをクリックし、`clientKey` を入力します。
読み込む前に、展開した `config.js` をテキストエディタで開き、`clientKey: ''` の引用符の間に `clientKey` を入力して保存しておくこともできます。インストール後に入力する必要がなくなります。複数のブラウザ環境に拡張機能をインストールするときに便利です。
お使いのブラウザでは動画を再生できません。ダウンロードしてご覧ください： [動画：Chrome にパッケージでインストール。先に config.js に clientKey を入力しておく方法（44 秒。動画は旧バージョンですが、手順は同じです）](https://docs.yescaptcha.com/videos/extension-chrome-zip.mp4)
動画：Chrome にパッケージでインストール。先に config.js に clientKey を入力しておく方法（44 秒。動画は旧バージョンですが、手順は同じです）
> **注意:** 展開したフォルダは、その後削除したり移動したりしないでください。ブラウザが拡張機能を読み込めなくなります。パッケージでインストールした場合は自動更新されないため、新しいバージョンが出たら再度ダウンロードしてください。
### Firefox にパッケージでインストールする
1. `.xpi` ファイルをダウンロードします。
2. アドレスバーで `about:addons` を開き、歯車アイコンをクリックして「ファイルからアドオンをインストール」を選び、ダウンロードしたファイルを選択します。
3. ツールバーの拡張機能アイコンをクリックし、`clientKey` を入力します。
## BitBrowser にインストールする
BitBrowser などのアンチディテクトブラウザは Chrome をベースにしています。拡張機能は Extension Center（扩展中心）で追加し、追加後にすべてのウィンドウ、または指定したウィンドウで有効にできます。以下の手順と動画は BitBrowser 6.0 の中国語インターフェースで録画したもので、新しいバージョンでは画面が少し異なる場合があります。
### Chrome ウェブストアから追加する
1. BitBrowser の左側で「Extension Center（扩展中心）」をクリックし、「Add custom extension（添加自定义扩展）」をクリックして、「Add Chrome Web Store extension（添加 Chrome 商店扩展）」を選びます。
2. URL 入力欄に、拡張機能の Chrome ウェブストアのアドレス `https://chromewebstore.google.com/detail/yescaptcha-assistant/jiofmdifioeejeilfkpegipdjiopiekl` を貼り付け、入力欄の右にあるボタンをクリックして認識させます。「YesCaptcha Assistant」が認識されたら「OK（确定）」をクリックします。
3. 追加後、YesCaptcha Assistant のカードで「Settings（设置）」をクリックし、有効にする範囲として「すべてのウィンドウ」を選ぶか、「指定ウィンドウ」を選んで使用するウィンドウにチェックを入れ、「OK（确定）」をクリックします。
4. ブラウザのウィンドウを開き、ツールバーの拡張機能アイコンをクリックして YesCaptcha Assistant を探し、`clientKey` を入力します。残高が表示されれば設定完了です。
お使いのブラウザでは動画を再生できません。ダウンロードしてご覧ください： [動画：BitBrowser で Chrome ウェブストアから追加する（30 秒）](https://docs.yescaptcha.com/videos/extension-bit-store.mp4)
動画：BitBrowser で Chrome ウェブストアから追加する（30 秒）
### パッケージから追加する
1. 上の Chrome 版パッケージをダウンロードし、常設のフォルダに展開します。
2. （任意）フォルダ内の `config.js` をテキストエディタで開き、`clientKey: ''` の引用符の間に `clientKey` を入力して保存します。こうしておくと、各ウィンドウにインストールした後で入力する必要がありません。
3. Extension Center で「Add custom extension（添加自定义扩展）」をクリックし、「Add local extension（添加本地扩展）」を選びます。「Upload extension（上传扩展）」で、展開したフォルダ（`manifest.json` が入っている階層）を選択し、「OK（确定）」をクリックします。
4. アップロードに成功したら、YesCaptcha Assistant のカードで「Settings（设置）」をクリックし、有効にする範囲（すべてのウィンドウまたは指定ウィンドウ）を選んで「OK（确定）」をクリックします。
5. ブラウザのウィンドウを開き、拡張機能アイコンから YesCaptcha Assistant をクリックします。キーと残高が表示されれば設定完了です。
お使いのブラウザでは動画を再生できません。ダウンロードしてご覧ください： [動画：BitBrowser にパッケージで追加する（46 秒。動画は旧バージョンですが、手順は同じです）](https://docs.yescaptcha.com/videos/extension-bit-zip.mp4)
動画：BitBrowser にパッケージで追加する（46 秒。動画は旧バージョンですが、手順は同じです）
## Android スマートフォンで使う（Kiwi Browser）
> **注意:** Kiwi Browser は 2025 年 1 月にメンテナンスが終了し、Google Play からも削除されました。以降、更新やセキュリティパッチは提供されません。以下の手順と動画は旧ドキュメントのもので、今も Kiwi Browser を使っているユーザー向けの参考情報です。現行バージョンの拡張機能は Kiwi Browser で再テストしていません。
1. Chrome 版パッケージ（`.zip`）をスマートフォンにダウンロードします。展開は不要です。キーをあらかじめ入力しておきたい場合は、先にパソコンで展開して `config.js` を編集し、zip に圧縮し直してください（`manifest.json` を圧縮ファイルの最上位に置く必要があります）。
2. Kiwi Browser の右上のメニューをタップし、「Extensions」（拡張機能）を選びます。
3. 「Developer mode」（開発者モード）をオンにし、「+ (from .zip/.crx/.user.js)」をタップして、ダウンロードしたパッケージを選択します。
4. もう一度右上のメニューをタップすると、一番下に YesCaptcha Assistant が表示されます。タップして開き、`clientKey` を入力します。残高が表示されれば設定完了です。
お使いのブラウザでは動画を再生できません。ダウンロードしてご覧ください： [動画：Kiwi Browser でのインストール（16 秒。動画は旧バージョンですが、手順は同じです）](https://docs.yescaptcha.com/videos/extension-kiwi.mp4)
動画：Kiwi Browser でのインストール（16 秒。動画は旧バージョンですが、手順は同じです）
## 設定
1. [yescaptcha.com](https://yescaptcha.com/) でアカウントを登録してチャージし、ダッシュボードで `clientKey` をコピーします。詳しくは [クイックスタート](https://docs.yescaptcha.com/ja/getting-started/quickstart.md) を参照してください。
2. 拡張機能アイコンをクリックし、設定パネルにキーを入力します。残高が表示されれば設定完了です。
3. キャプチャのあるページを開くと、拡張機能が自動で認識を始めます。
## 料金
拡張機能は無料です。認識時には、使用したタイプに応じてポイントが課金されます。たとえば reCAPTCHA の画像問題は [reCAPTCHA v2 画像認識](https://docs.yescaptcha.com/ja/tasks/recaptcha-classification.md) の料金、hCaptcha は [hCaptcha 画像認識](https://docs.yescaptcha.com/ja/tasks/hcaptcha-classification.md) の料金で計算されます。誤って認識された場合は報告して返金を申請できます。詳しくは [課金と返金](https://docs.yescaptcha.com/ja/getting-started/billing.md) を参照してください。
---
# キャプチャの種類を見分ける
> ページ上のキャプチャが何かを見分ける方法。reCAPTCHA v2、v2 非表示版、v3、エンタープライズ版、hCaptcha、Cloudflare Turnstile と Cloudflare チャレンジページの違い、対応する YesCaptcha のタスクタイプを説明します。
Source: https://docs.yescaptcha.com/ja/guides/identify-captcha/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/guides/identify-captcha/
適切なタスクタイプを選ぶ第一歩は、キャプチャを見分けることです。最も確実なのは、ブラウザの開発者ツール（F12）を開き、Network（ネットワーク）パネルでページがどのキャプチャのスクリプトを読み込んでいるかを確認する方法です。見た目から判断することもできます。
## 見た目で見分ける
各キャプチャがウェブページ上でどう見えるかを示したアニメーションのイラストです（スクリーンショットではありません）。カードをクリックすると対応するタスクタイプのページを開きます。見た目で判断しにくい場合は、下の早見表と Network パネルで確認してください。
- [reCAPTCHA v2: チェックボックス · 非表示型](https://docs.yescaptcha.com/ja/tasks/recaptcha-v2.md)
- [reCAPTCHA v3](https://docs.yescaptcha.com/ja/tasks/recaptcha-v3.md)
- [reCAPTCHA v2 画像認識: 3×3 グリッド · 4×4 グリッド · 1×1 単一画像](https://docs.yescaptcha.com/ja/tasks/recaptcha-classification.md)
- [hCaptcha](https://docs.yescaptcha.com/ja/tasks/hcaptcha.md)
- [hCaptcha 画像認識: 画像グリッド · 指定位置をクリック · ドラッグ＆ドロップ · アニメーション](https://docs.yescaptcha.com/ja/tasks/hcaptcha-classification.md)
- [Cloudflare Turnstile: 自動 · チェックボックス](https://docs.yescaptcha.com/ja/tasks/turnstile.md)
- [Cloudflare チャレンジページ: 自動 · チェックボックス](https://docs.yescaptcha.com/ja/tasks/cloudflare-challenge.md)
- [FunCaptcha 画像認識: 矢印 · 6 枚グリッド](https://docs.yescaptcha.com/ja/tasks/funcaptcha-classification.md)
- [AWS WAF / bCaptcha 画像認識: AWS WAF · bCaptcha](https://docs.yescaptcha.com/ja/tasks/aws-bcaptcha-classification.md)
- [画像の英数字認識: ノイズあり · ノイズライン · 計算式](https://docs.yescaptcha.com/ja/tasks/image-to-text.md)
## 早見表
| 見えるもの | 種類 | 使うタスクタイプ |
| --- | --- | --- |
| 「私はロボットではありません / I’m not a robot」のチェックボックス | reCAPTCHA v2 | [reCAPTCHA v2](https://docs.yescaptcha.com/ja/tasks/recaptcha-v2.md) |
| チェックボックスはなく、送信を押すと画像の問題が表示される。右下に reCAPTCHA のバッジがある | reCAPTCHA v2 非表示版（または v3） | 下記「reCAPTCHA のバージョン」を参照 |
| 操作が一切なく、右下に reCAPTCHA のバッジだけがある | reCAPTCHA v3 | [reCAPTCHA v3](https://docs.yescaptcha.com/ja/tasks/recaptcha-v3.md) |
| 「私は人間です」のチェックボックスがあり、画像の問題に hCaptcha と表示されている | hCaptcha | [hCaptcha](https://docs.yescaptcha.com/ja/tasks/hcaptcha.md) |
| フォームの中に Cloudflare の認証ボックスが埋め込まれており、チェック後もページが遷移しない | Cloudflare Turnstile | [Turnstile](https://docs.yescaptcha.com/ja/tasks/turnstile.md) |
| ページ全体に「お待ちください… / 接続を確認しています」と表示され、自動で遷移する | Cloudflare チャレンジページ | [Cloudflare チャレンジページ](https://docs.yescaptcha.com/ja/tasks/cloudflare-challenge.md) |
| Arkose Labs のパズルや画像選択問題（「正しい向きの画像を選んでください」など） | FunCaptcha | [FunCaptcha 画像認識](https://docs.yescaptcha.com/ja/tasks/funcaptcha-classification.md) |
| 歪んだ英数字が書かれた画像 | 文字キャプチャ | [画像の英数字認識](https://docs.yescaptcha.com/ja/tasks/image-to-text.md) |
## reCAPTCHA のバージョン
Network パネルで `api.js` または `enterprise.js` を検索します。
| 読み込まれるスクリプト | バージョン |
| --- | --- |
| `recaptcha/api.js`、`render` パラメータなし、または `render=explicit` | v2 通常版 |
| 上記と同じで、`anchor` リクエストの URL に `size=invisible` がある | v2 非表示版。タスクに `"isInvisible": true` を追加 |
| `recaptcha/api.js?render=サイトキー`（`render` が `explicit` ではない） | v3 通常版 |
| `recaptcha/enterprise.js`、`render` パラメータなし、または `render=explicit` | v2 エンタープライズ版 |
| `recaptcha/enterprise.js?render=サイトキー` | v3 エンタープライズ版 |
例：
```text
https://www.google.com/recaptcha/api.js?onload=onloadcallback&render=explicit → v2 普通版
https://www.google.com/recaptcha/api.js?render=6LdyC2cUAAAAACGuDKpXeDorzUDWXmdqeg-xy696 → v3 普通版
https://www.google.com/recaptcha/enterprise.js?render=explicit → v2 企业版
```
v2 非表示版は、v3 のタスクタイプでないと通らない場合があります。両方試してみてください。
コンソール（Console）で次のコードを実行すると、ページ上のすべての reCAPTCHA について、バージョン、サイトキー、ページ URL、コールバック関数を一覧表示できます。
find-recaptcha-clients.js
```js
// Paste into the browser DevTools console on a page with reCAPTCHA, then run findRecaptchaClients().
// Lists every reCAPTCHA on the page: version (V2/V3), sitekey, page URL and the callback function.
function findRecaptchaClients() {
if (typeof ___grecaptcha_cfg === 'undefined') return [];
return Object.entries(___grecaptcha_cfg.clients).map(([cid, client]) => {
const data = { id: cid, version: cid >= 10000 ? 'V3' : 'V2' };
const objects = Object.entries(client).filter(([, value]) => value && typeof value === 'object');
objects.forEach(([toplevelKey, toplevel]) => {
const found = Object.entries(toplevel).find(
([, value]) => value && typeof value === 'object' && 'sitekey' in value && 'size' in value,
);
if (toplevel instanceof HTMLElement && toplevel.tagName === 'DIV') data.pageurl = toplevel.baseURI;
if (found) {
const [sublevelKey, sublevel] = found;
data.sitekey = sublevel.sitekey;
const callbackKey = data.version === 'V2' ? 'callback' : 'promise-callback';
const callback = sublevel[callbackKey];
if (!callback) {
data.callback = null;
data.function = null;
} else {
data.function = callback;
const keys = [cid, toplevelKey, sublevelKey, callbackKey].map((key) => `['${key}']`).join('');
data.callback = `___grecaptcha_cfg.clients${keys}`;
}
}
});
return data;
});
}
findRecaptchaClients();
```
実行結果の例：
```json
[
{
"id": "0",
"version": "V2",
"sitekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
"function": "onSuccess",
"callback": "___grecaptcha_cfg.clients['0']['l']['l']['callback']",
"pageurl": "https://www.google.com/recaptcha/api2/demo"
}
]
```
比較には Google 公式のデモページが使えます。v2 通常版は `https://www.google.com/recaptcha/api2/demo`、v2 非表示版は `https://www.google.com/recaptcha/api2/demo?invisible=true` です。
## Turnstile と Cloudflare チャレンジページ
どちらも Cloudflare のものですが、別物です。
- **Turnstile** は、ページのフォームに埋め込まれた認証ボックスです。認証が完了するとチェックマークが付き、ページ自体は遷移しません。ページは `challenges.cloudflare.com/turnstile/v0/api.js` を読み込みます。[Turnstile](https://docs.yescaptcha.com/ja/tasks/turnstile.md) を使います。
- **Cloudflare チャレンジページ** は、ページ全体が Cloudflare の確認ページに置き換わり、「お待ちください…」「xx.com は接続のセキュリティを確認する必要があります」と表示されます。中に認証ボックスが含まれることもあります。通過すると本来のページへ自動で遷移します。ソースに `__cf_chl_rt_tk` または `cdn-cgi/challenge-platform` が含まれています。[Cloudflare チャレンジページ](https://docs.yescaptcha.com/ja/tasks/cloudflare-challenge.md) を使います。
プログラムからのリクエストでは 403 と「Just a moment…」が返るのに、ブラウザでは直接開ける場合は、多くの場合 TLS フィンガープリントでブロックされているだけです。ブラウザの TLS フィンガープリントを模倣できるライブラリ（curl\_cffi など）に切り替えればリクエストでき、チャレンジの突破は不要です。
---
# reCAPTCHA パラメータの調べ方
> reCAPTCHA の websiteKey（sitekey）、websiteURL、v3 の pageAction、コールバック関数を、開発者ツールの Network・Sources・Console で調べる方法です。自動検出スクリプト付き。
Source: https://docs.yescaptcha.com/ja/guides/find-recaptcha-parameters/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/guides/find-recaptcha-parameters/
reCAPTCHA のタスクを作成するには、`websiteURL`（キャプチャが表示されるページの URL）と `websiteKey`（サイトキー）が必要です。v3 ではさらに `pageAction` が必要です。Selenium などでブラウザを操作して送信する場合は、コールバック関数も必要になります。これらはすべてブラウザの開発者ツール（F12）で確認できます。
## 最も簡単な方法：自動検出スクリプト
キャプチャが表示されているページを開き、F12 でコンソール（Console）を開いて、次のスクリプトを貼り付けて実行します。
find-recaptcha-clients.js
```js
// Paste into the browser DevTools console on a page with reCAPTCHA, then run findRecaptchaClients().
// Lists every reCAPTCHA on the page: version (V2/V3), sitekey, page URL and the callback function.
function findRecaptchaClients() {
if (typeof ___grecaptcha_cfg === 'undefined') return [];
return Object.entries(___grecaptcha_cfg.clients).map(([cid, client]) => {
const data = { id: cid, version: cid >= 10000 ? 'V3' : 'V2' };
const objects = Object.entries(client).filter(([, value]) => value && typeof value === 'object');
objects.forEach(([toplevelKey, toplevel]) => {
const found = Object.entries(toplevel).find(
([, value]) => value && typeof value === 'object' && 'sitekey' in value && 'size' in value,
);
if (toplevel instanceof HTMLElement && toplevel.tagName === 'DIV') data.pageurl = toplevel.baseURI;
if (found) {
const [sublevelKey, sublevel] = found;
data.sitekey = sublevel.sitekey;
const callbackKey = data.version === 'V2' ? 'callback' : 'promise-callback';
const callback = sublevel[callbackKey];
if (!callback) {
data.callback = null;
data.function = null;
} else {
data.function = callback;
const keys = [cid, toplevelKey, sublevelKey, callbackKey].map((key) => `['${key}']`).join('');
data.callback = `___grecaptcha_cfg.clients${keys}`;
}
}
});
return data;
});
}
findRecaptchaClients();
```
結果の `sitekey` が `websiteKey`、`pageurl` が `websiteURL` です。`version` は v2 か v3 かを示し、`function` と `callback` がコールバック関数です。
```json
[
{
"id": "0",
"version": "V2",
"sitekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
"function": "onSuccess",
"callback": "___grecaptcha_cfg.clients['0']['l']['l']['callback']",
"pageurl": "https://www.google.com/recaptcha/api2/demo"
}
]
```
空の配列が返る場合は、ページで reCAPTCHA がまだ読み込まれていません。キャプチャが表示されてから再度実行してください。
## websiteKey と websiteURL
Network パネルで `anchor` を検索し、次のようなリクエストを探します。
```text
https://www.google.com/recaptcha/api2/anchor?ar=1&k=6LfW6wATAAAAAHLqO2pb8bDBahxlMxNdo9g947u9&co=...&hl=en&size=normal
```
- `k=` の後ろの値が `websiteKey` です。
- `websiteURL` には、キャプチャが表示されているページの完全な URL を指定します（このリクエストの `Referer` が通常それに当たります）。
ページのソースで `data-sitekey` を検索しても見つかります。
## pageAction（v3）
`pageAction` は、ページが `grecaptcha.execute(サイトキー, {action: '...'})` を呼ぶ際に渡す `action` のことで、ページ側と一致させる必要があります。
**方法 1：ソースを検索する。** 開発者ツールの Sources パネルで右クリックし、「Search in all files」を選びます。通常の v3 は `.execute(`、Enterprise 版 v3 は `.enterprise.execute` を検索し、続く `action` を確認します。
```js
grecaptcha.ready(function () {
grecaptcha.execute('6LdpS-gUAAAAAL3Qr2yP7rkrQjkKBVvEY_48JS5l', { action: 'login' }).then(function (token) {
// ...
});
});
```
この例では `pageAction` は `login` です。
**方法 2：ブレークポイントを使う。** コードが難読化されていて検索で見つからない場合は、コンソールで `debug(grecaptcha.execute)`（Enterprise 版は `debug(grecaptcha.enterprise.execute)`）を実行し、ページ上で検証が発生する操作（ログインのクリックなど）を行います。ブレークポイントで停止したら、右側の Scope で `action` の値を確認します。
サイトによっては、ステップごとに異なる `action` を使います（例：登録時に `signup/submit_email` の後に `signup/success`）。通過したいステップの値を使用してください。F8 キーで実行を再開すると、次の `action` を確認できます。
## コールバック関数
Selenium などでブラウザ上のページに token を入力する場合、入力後にページのコールバック関数を呼び出して、検証が完了したことをページに伝えます。
- Elements パネルで `data-callback` を検索します。その値がコールバック関数名です（例：`data-callback="onSuccess"`）。
- または `grecaptcha.render` を検索し、引数の `callback` を確認します。
- または、コンソールで `___grecaptcha_cfg.clients` を確認するか、上記の自動検出スクリプトを使います。
呼び出し方：
```python
driver.execute_script("onSuccess(arguments[0])", g_recaptcha_response)
```
コールバック関数のないページもあります。その場合は、token を `g-recaptcha-response` のテキストボックスに入力して、そのままフォームを送信してください。全体の流れは [token で reCAPTCHA を通過する](https://docs.yescaptcha.com/ja/guides/submit-recaptcha-token.md) を参照してください。
---
# hCaptcha のパラメータの見つけ方
> hCaptcha の websiteKey（sitekey）、websiteURL、Enterprise 版の rqdata の見つけ方。ページソースで data-sitekey を検索するか、Network パネルで checksiteconfig や getcaptcha のリクエストを探します。
Source: https://docs.yescaptcha.com/ja/guides/find-hcaptcha-parameters/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/guides/find-hcaptcha-parameters/
[hCaptcha](https://docs.yescaptcha.com/ja/tasks/hcaptcha.md) のタスクを作成するには、`websiteURL`（キャプチャが表示されるページの URL）と `websiteKey`（サイトキー、UUID 形式）が必要です。Enterprise 版では `rqdata` も必要になる場合があります。いずれもブラウザの開発者ツール（F12）で確認できます。
## websiteKey
**方法 1：ページソースを検索する。** Elements パネルで Ctrl+F（Mac では Cmd+F）を押し、`data-sitekey` を検索します。
```html
```
`data-sitekey` の値が `websiteKey` です。
**方法 2：ネットワークリクエストを確認する。** Network パネルで `hcaptcha` を検索し、`checksiteconfig` リクエストを探します。URL の `sitekey=` の後ろの値が `websiteKey` です。
```text
https://api.hcaptcha.com/checksiteconfig?v=...&host=example.com&sitekey=51829642-2cda-4b09-896c-594f89d700cc&sc=1&swa=1
```
## websiteURL
キャプチャが表示されるページの完全な URL を指定します。`hcaptcha.com` では**ありません**。上のリクエストの `host=` が、そのページのドメインです。
## rqdata（Enterprise 版）
一部のサイトは hCaptcha Enterprise を使っており、キャプチャを読み込むたびにサイトが `rqdata` を発行します。これを送らないと通過できません。多くの場合、サイト自身の API のレスポンス（例：ログイン API が返す `captcha_rqdata`）に含まれているか、`hcaptcha.render` / `hcaptcha.setData` の呼び出し時に渡されています。取得した値はタスクの `rqdata` フィールドに指定してください。`rqdata` は通常 1 回しか使えないため、毎回新しい値を取得する必要があります。
## userAgent
`userAgent` には [/useragent](https://docs.yescaptcha.com/ja/api/useragent.md) が返す値のみを指定できます。token を送信するときは、認識結果で返される `userAgent` を使用してください。
---
# Turnstile パラメータの調べ方
> Cloudflare Turnstile の websiteKey（sitekey、0x で始まる）と websiteURL の調べ方。ページのソースで data-sitekey や turnstile.render を検索するか、Network パネルで challenges.cloudflare.com へのリクエストを確認します。
Source: https://docs.yescaptcha.com/ja/guides/find-turnstile-parameters/ · Last verified: 2026-10-21
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/guides/find-turnstile-parameters/
[Turnstile](https://docs.yescaptcha.com/ja/tasks/turnstile.md) のタスクを作成するには、`websiteURL`（認証ウィジェットが表示されるページの URL）と `websiteKey`（サイトキー。通常は `0x` で始まります）が必要です。まず Cloudflare チャレンジページではなく Turnstile であることを確認してください。[キャプチャの種類を判別する](https://docs.yescaptcha.com/ja/guides/identify-captcha.md) を参照してください。
## websiteKey
**方法 1：ページのソースを検索する。** 開発者ツール（F12）の Elements パネルで `data-sitekey` を検索します。
```html
```
**方法 2：スクリプトを検索する。** JavaScript で描画されるウィジェットの場合は、Sources パネルで右クリックして「Search in all files」を選び、`turnstile.render` を検索します。引数の `sitekey` を確認してください。
```js
turnstile.render('#container', { sitekey: '0x4AAAAAAAxxxxxxxxxxxxxx', callback: onDone });
```
**方法 3：ネットワークリクエストを確認する。** Network パネルで `challenges.cloudflare.com` を検索します。ウィジェットの iframe の URL に、`0x` で始まるサイトキーが含まれています。
## websiteURL
ウィジェットが表示されるページの完全な URL を指定します。例：`https://example.com/login`
## action と cData（通常は不要）
ほとんどの場合は不要です。`websiteKey` と `websiteURL` が正しいことを確認したうえで、それでもタスクが通らない場合にのみ調べてください。`turnstile.render` の引数またはウィジェットの要素に `action` と `cData` があるかを確認します（要素上では `data-action` と `data-cdata`）。
```js
turnstile.render('#container', { sitekey: '0x4AAAAAAAxxxxxxxxxxxxxx', action: 'login', cData: 'c0bd4b36-7419-4e18-83c6-378699f2a9a2' });
```
ある場合は、タスク作成時に `action` を `pageAction` に、`cData` を `data` に指定します。[Turnstile](https://docs.yescaptcha.com/ja/tasks/turnstile.md) を参照してください。
## token の送信
認識が完了したら、`token` をフォームの `cf-turnstile-response` という名前の hidden フィールドに設定します（`turnstile.render` で `callback` を指定している場合は、そのコールバック関数に token を渡して呼び出します）。そのあとフォームを送信してください。送信リクエストの User-Agent には、認識結果の `userAgent` を使用します。
---
# token で reCAPTCHA を通過する
> reCAPTCHA の token（gRecaptchaResponse）を取得した後の使い方。仕組み、リクエストを直接送信する方法（g-recaptcha-response フィールド）、ブラウザに入力してコールバック関数を呼び出す方法を、Google のデモページを使った Python の完全なサンプル付きで解説します。
Source: https://docs.yescaptcha.com/ja/guides/submit-recaptcha-token/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/guides/submit-recaptcha-token/
YesCaptcha が返す `gRecaptchaResponse` は、ページ上でキャプチャを完了したときに Google がページへ渡す結果と同じものです。取得したら、ブラウザと同じように**対象のウェブサイトへ送信**する必要があります（Google や YesCaptcha には送信しません）。サイトはそれを Google に照会して検証し、通過させます。方法は 2 つあります。リクエストを直接送信する方法と、ブラウザのページに入力して送信する方法です。
## 仕組み
通常のアクセスでは、次の流れになります。
1. ページが reCAPTCHA を読み込み、ユーザーが認証を完了する。
2. Google がページに token を渡し、ページがそれを `g-recaptcha-response` テキストボックスに入れる（またはコールバック関数に渡す）。
3. ユーザーがフォームを送信すると、token もフォームと一緒にサイトのサーバーへ送られる。
4. サイトのサーバーが token を Google に照会して検証し、問題なければ通過させる。
YesCaptcha を使う場合、手順 1 と 2 は YesCaptcha が行います。`websiteURL` と `websiteKey` でタスクを作成して token を取得し、手順 3 から続けてください。
> **注意:** token は 1 回限りで、有効期間は約 120 秒です。取得後 60 秒以内の送信を推奨します。期限切れの token はサイトに受け付けられません。
## 方法 1：リクエストを直接送信する（推奨）
1. ブラウザで一度通常どおり操作します。F12 で Network パネルを開き、キャプチャを完了してフォームを送信し、フォームを送信しているリクエストを探します。
2. リクエストの Payload（または Form Data）から token を持つフィールドを探します。通常は `g-recaptcha-response` で、token は `03A` で始まります。サイトによっては `grecaptcharesponse` や `captcha` のように名前が変更されています。
3. プログラムから同じリクエストを送り、そのフィールドの値を YesCaptcha が返した token に置き換えます。その他のフィールド、Cookie、リクエストヘッダーもブラウザのものと一致させてください。サイトは多くの場合、これらも同時に検査します。
Google のデモページを使った完全な例です。認識を行ってから、token を `g-recaptcha-response` フィールドでデモページに送り返します。
recaptcha_requests.py
```python
"""Solve reCAPTCHA v2 on Google's demo page and submit the token with plain HTTP (no browser).
Run: pip install requests
export YESCAPTCHA_CLIENT_KEY=your_client_key
python recaptcha_requests.py
Each run creates one NoCaptchaTaskProxyless task (charged per the price list).
"""
import os
import time
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
API = "https://api.yescaptcha.com"
WEBSITE_URL = "https://www.google.com/recaptcha/api2/demo"
WEBSITE_KEY = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
def call(method, payload):
data = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30).json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data
def get_token():
task = {"type": "NoCaptchaTaskProxyless", "websiteURL": WEBSITE_URL, "websiteKey": WEBSITE_KEY}
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"]["gRecaptchaResponse"]
raise TimeoutError(task_id)
token = get_token()
print("token:", token[:40], "...")
# Submit the token the same way the browser does: the demo form posts the field
# "g-recaptcha-response" back to the page. Check your own site's request in DevTools > Network.
page = requests.post(WEBSITE_URL, data={"g-recaptcha-response": token}, timeout=30)
print("passed" if "Verification Success" in page.text else "not passed", page.status_code)
```
## 方法 2：ブラウザに入力する（Selenium など）
Selenium や Playwright などで実際のブラウザを操作する場合は、次の手順で行います。
1. ページから `data-sitekey` を読み取り、それでタスクを作成して token を取得します。
2. token をページ内の `g-recaptcha-response` テキストボックスに書き込みます。
3. ページにコールバック関数（`data-callback="..."`）が設定されている場合は、token を渡して呼び出します。サイトによっては、コールバックを呼び出して初めて送信ボタンがクリック可能になります。
4. フォームを送信します。
```js
// 第 2 步：写入 token（在页面里执行）
document.getElementById('g-recaptcha-response').value = 'TOKEN';
// 第 3 步：有回调函数时调用，例如 data-callback="onSuccess"
onSuccess('TOKEN');
```
ページに複数の reCAPTCHA がある場合、テキストボックスの id は `g-recaptcha-response-1` のようになっていることがあります。このテキストボックスが見つからないときは、まず手動で認証を一度完了し、Elements パネルで `03A` を検索して、結果がどこに置かれているかを確認してください。コールバック関数の見つけ方は [reCAPTCHA パラメータの調べ方](https://docs.yescaptcha.com/ja/guides/find-recaptcha-parameters.md) を参照してください。
完全な例（Selenium 4）：
recaptcha_selenium.py
```python
"""Solve reCAPTCHA v2 on Google's demo page in a real browser with Selenium 4:
get a token from YesCaptcha, put it into the page, then submit the form.
Run: pip install requests selenium
export YESCAPTCHA_CLIENT_KEY=your_client_key
python recaptcha_selenium.py
Each run creates one NoCaptchaTaskProxyless task (charged per the price list).
"""
import os
import time
import requests
from selenium import webdriver
from selenium.webdriver.common.by import By
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
API = "https://api.yescaptcha.com"
WEBSITE_URL = "https://www.google.com/recaptcha/api2/demo"
def call(method, payload):
data = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30).json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data
def get_token(website_url, website_key):
task = {"type": "NoCaptchaTaskProxyless", "websiteURL": website_url, "websiteKey": website_key}
task_id = call("createTask", {"task": task})["taskId"]
for _ in range(36):
time.sleep(5)
result = call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]["gRecaptchaResponse"]
raise TimeoutError(task_id)
driver = webdriver.Chrome() # Selenium 4 downloads a matching chromedriver automatically
try:
driver.get(WEBSITE_URL)
site_key = driver.find_element(By.CSS_SELECTOR, "[data-sitekey]").get_attribute("data-sitekey")
token = get_token(WEBSITE_URL, site_key)
# Put the token where reCAPTCHA keeps it ...
driver.execute_script(
"document.getElementById('g-recaptcha-response').value = arguments[0];", token
)
# ... and, if the page uses a callback (data-callback="..."), call it:
callback = driver.find_element(By.CSS_SELECTOR, "[data-sitekey]").get_attribute("data-callback")
if callback:
driver.execute_script(f"window[{callback!r}](arguments[0]);", token)
driver.find_element(By.ID, "recaptcha-demo-submit").click()
time.sleep(2)
print("passed" if "Verification Success" in driver.page_source else "not passed")
finally:
driver.quit()
```
## reCAPTCHA v3
v3 にはチェックボックスがありません。ページは必要なときに `grecaptcha.execute(サイトキー, {action: '...'})` を呼び出して token を取得し、その token を自身のリクエストに含めます（フィールド名はサイトによって異なり、よくあるのは `g-recaptcha-response`、`token`、`recaptchaToken` です）。方法は方法 1 と同じです。Network パネルで token を含むリクエストを見つけ、その通りに送信します。タスク作成時の `pageAction` は、ページの `action` と一致させる必要があります。
## 送信しても通らない場合
- token の期限切れ：取得後はできるだけ早く、60 秒以内に送信してください。
- サイトが検査しているフィールドと違うフィールドに送信している、または他のフィールドや Cookie が欠けている：ブラウザのリクエストと項目ごとに照らし合わせてください。
- サイトが IP や User-Agent なども同時に検査している：プロキシを自前で指定するタイプ（`NoCaptchaTask` など）を使い、送信時も同じプロキシを経由してください。
- v3 のスコアが足りない：`pageAction` を確認するか、高スコア固定のタイプに切り替えてください。詳しくは [reCAPTCHA v3](https://docs.yescaptcha.com/ja/tasks/recaptcha-v3.md) を参照してください。
- サイトのリスク制御がほかの行動シグナルも見ている：token 方式の通過率が低い場合は、[画像認識](https://docs.yescaptcha.com/ja/tasks/recaptcha-classification.md) を使ってブラウザで実際にクリックするか、[YesCaptcha Assistant（ブラウザ拡張機能）](https://docs.yescaptcha.com/ja/extension.md) を使ってください。
---
# reCAPTCHA v2 画像認識によるクリック操作（Selenium）
> Python Selenium 4 と ReCaptchaV2Classification を使い、ブラウザ上で reCAPTCHA v2 の画像問題を自動でクリックします。キャプチャの表示、問題文と画像の取得、認識 API の呼び出し、マスのクリック、送信までの完全なサンプルコードを掲載しています。
Source: https://docs.yescaptcha.com/ja/guides/recaptcha-click-selenium/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/guides/recaptcha-click-selenium/
このチュートリアルでは、Selenium 4 で Google の reCAPTCHA デモページを開き、実際のブラウザ上で画像問題を解きます。問題文と画像を読み取り、[reCAPTCHA v2 画像認識](https://docs.yescaptcha.com/ja/tasks/recaptcha-classification.md)（`ReCaptchaV2Classification`）でクリックすべきマスを判定し、クリックを再現します。token を取得する方式と異なり、ブラウザ内で実際に検証を完了するため、token の通過率が低いサイトに適しています。
コードを書きたくない場合は、同じ API を使って自動クリックする [ブラウザ拡張機能](https://docs.yescaptcha.com/ja/extension.md) をそのままご利用ください。
## 準備
```bash
pip install requests selenium pillow
export YESCAPTCHA_CLIENT_KEY=你的clientKey
```
Chrome のインストールが必要です。Selenium 4 は、バージョンが一致する chromedriver を自動でダウンロードします。
## 手順
1. **チェックボックスをクリックする。** チェックボックスは `title="reCAPTCHA"` の iframe 内にあります。iframe に切り替えて `#recaptcha-anchor` をクリックします。
2. **問題の iframe に切り替える。** 問題は別の iframe（title に “challenge” を含む）内にあります。
3. **問題文を読み取る。** `.rc-imageselect-desc-wrapper strong` 内の太字が探す対象です（例: “traffic lights”）。API が必要とするのは問題 ID なので、対応表で名称を ID（`/m/015qff`）に変換します。[問題 ID](https://docs.yescaptcha.com/ja/tasks/recaptcha-classification.md) を参照してください。ブラウザの表示言語を英語にすると照合しやすくなります。
4. **画像を取得する。** 各マスの画像は実際には 1 枚の大きな画像です。`td.rc-imageselect-tile img` の `src` をダウンロードします。9 マス（3x3）は 300×300、16 マス（4x4）は 450×450 にリサイズし、Base64 に変換します。
5. **認識する。** タイプ `ReCaptchaV2Classification` で `createTask` を呼び出し、`image` と `question` を渡します。`"confidence": 0.5` を加えると、3x3 の画像では該当するマスがすべて一度に返されるため、クリック後に更新される小さな画像を処理する必要がなくなります。
6. **クリックする。** 返された `objects` はマスの番号で、0 から始まり、左から右、上から下の順です。対応する `td` を順にクリックします。
7. **検証する。** `#recaptcha-verify-button` をクリックします。新しい問題が表示された場合は手順 3 に戻ります。問題のウィンドウが閉じれば通過です。
8. **フォームを送信する。** メインページに戻り、送信ボタンをクリックします。
## 完全なコード
recaptcha_click_selenium.py
```python
"""Click through a reCAPTCHA v2 image challenge with Selenium 4 and ReCaptchaV2Classification.
Flow: open the page -> click the checkbox -> read the target name and the grid image ->
ask YesCaptcha which tiles to click -> click them -> press Verify. Repeat if a new challenge appears.
Run: pip install requests selenium pillow
export YESCAPTCHA_CLIENT_KEY=your_client_key
python recaptcha_click_selenium.py
Each recognized image is charged (see the price list). reCAPTCHA's page structure can change;
adjust the selectors below if a step stops working.
"""
import base64
import io
import os
import time
import requests
from PIL import Image
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.wait import WebDriverWait
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
PAGE_URL = "https://www.google.com/recaptcha/api2/demo"
# Target names shown in the challenge (English UI) -> question IDs.
# Full list: https://docs.yescaptcha.com/en/tasks/recaptcha-classification/
QUESTION_IDS = {
"taxis": "/m/0pg52", "bus": "/m/01bjv", "buses": "/m/01bjv", "motorcycles": "/m/04_sv",
"tractors": "/m/013xlm", "chimneys": "/m/01jk_4", "crosswalks": "/m/014xcs",
"traffic lights": "/m/015qff", "bicycles": "/m/0199g", "parking meters": "/m/015qbp",
"cars": "/m/0k4j", "bridges": "/m/015kr", "boats": "/m/019jd", "palm trees": "/m/0cdl1",
"mountains or hills": "/m/09d_r", "fire hydrants": "/m/01pns0", "a fire hydrant": "/m/01pns0",
"stairs": "/m/01lynh",
}
def classify(image_b64, question):
task = {"type": "ReCaptchaV2Classification", "image": image_b64, "question": question, "confidence": 0.5}
data = requests.post(
"https://api.yescaptcha.com/createTask",
json={"clientKey": CLIENT_KEY, "task": task},
timeout=30,
).json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data["solution"] # synchronous: the solution comes back right away
def grid_image_b64(url, size):
"""Download the challenge image and scale it to the standard size (300 for 3x3, 450 for 4x4)."""
img = Image.open(io.BytesIO(requests.get(url, timeout=30).content)).convert("RGB")
img = img.resize((size, size))
buf = io.BytesIO()
img.save(buf, format="JPEG")
return base64.b64encode(buf.getvalue()).decode()
driver = webdriver.Chrome()
wait = WebDriverWait(driver, 15)
try:
driver.get(PAGE_URL)
# 1. Click the checkbox (inside the "reCAPTCHA" iframe)
wait.until(EC.frame_to_be_available_and_switch_to_it((By.CSS_SELECTOR, 'iframe[title="reCAPTCHA"]')))
wait.until(EC.element_to_be_clickable((By.ID, "recaptcha-anchor"))).click()
driver.switch_to.default_content()
# 2. Switch to the challenge iframe and solve rounds until it closes
wait.until(EC.frame_to_be_available_and_switch_to_it(
(By.XPATH, '//iframe[contains(@title, "challenge")]')))
for _ in range(5):
target = wait.until(EC.presence_of_element_located(
(By.CSS_SELECTOR, ".rc-imageselect-desc-wrapper strong"))).text.strip().lower()
question = QUESTION_IDS.get(target)
if not question:
print("unsupported target, reloading:", target)
driver.find_element(By.ID, "recaptcha-reload-button").click()
time.sleep(2)
continue
tiles = driver.find_elements(By.CSS_SELECTOR, "td.rc-imageselect-tile")
size = 450 if len(tiles) == 16 else 300
url = driver.find_element(By.CSS_SELECTOR, "td.rc-imageselect-tile img").get_attribute("src")
solution = classify(grid_image_b64(url, size), question)
for index in solution.get("objects", []):
tiles[index].click()
time.sleep(0.3)
time.sleep(1)
driver.find_element(By.ID, "recaptcha-verify-button").click()
time.sleep(3)
driver.switch_to.default_content()
frame = driver.find_element(By.XPATH, '//iframe[contains(@title, "challenge")]')
if not frame.is_displayed(): # challenge closed: passed
break
driver.switch_to.frame(frame)
driver.switch_to.default_content()
driver.find_element(By.ID, "recaptcha-demo-submit").click()
time.sleep(2)
print("passed" if "Verification Success" in driver.page_source else "not passed")
finally:
driver.quit()
```
## 注意
- reCAPTCHA のページ構造は更新されます。コード内のセレクタが機能しなくなった場合は、実際のページに合わせて調整してください。
- 画像 1 枚を認識するたびに課金されます（料金は [reCAPTCHA v2 画像認識](https://docs.yescaptcha.com/ja/tasks/recaptcha-classification.md) を参照）。クリック後に検証に失敗したタスクは、1 時間以内に [報告](https://docs.yescaptcha.com/ja/api/report.md) すると、報告による返金を申請できます。
- 対応表にない問題が出た場合は、更新ボタンを押して別の問題に切り替えるか、サポートに連絡して対応を追加してもらってください。
---
# hCaptcha 画像認識によるクリック操作の自動化（Selenium）
> Python Selenium 4 と HCaptchaClassification を使い、ブラウザ上で hCaptcha の 3×3 グリッド画像チャレンジを自動で突破する方法を解説します。チェックボックスのクリック、問題文と 9 枚の画像の取得、認識 API の呼び出し、クリック、送信まで、完全なサンプルコード付きです。
Source: https://docs.yescaptcha.com/ja/guides/hcaptcha-click-selenium/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/guides/hcaptcha-click-selenium/
このチュートリアルでは、Selenium 4 で hCaptcha のデモページを開き、実際のブラウザ上で 3×3 グリッドの画像チャレンジを突破します。問題文と 9 枚の画像を取得して [hCaptcha 画像認識](https://docs.yescaptcha.com/ja/tasks/hcaptcha-classification.md)（`HCaptchaClassification`）に渡し、どれが対象かを判定させたうえで、該当するタイルをクリックします。
hCaptcha には「指定位置をクリック」「ドラッグ」といった出題形式もあります。これらはタイルではなく座標を返します。処理方法は [hCaptcha 画像認識](https://docs.yescaptcha.com/ja/tasks/hcaptcha-classification.md) を参照してください。コードを書きたくない場合は [ブラウザ拡張機能](https://docs.yescaptcha.com/ja/extension.md) を使えば、これらの出題形式にもすべて対応できます。
## 準備
```bash
pip install requests selenium
export YESCAPTCHA_CLIENT_KEY=你的clientKey
```
## 手順
1. **チェックボックスをクリックする。** チェックボックスは、URL に `frame=checkbox` を含む hCaptcha の iframe 内にあります。その iframe に切り替えて `#checkbox` をクリックします。
2. **チャレンジの iframe に切り替える。** 問題は、URL に `frame=challenge` を含む iframe 内にあります。
3. **問題文を読み取る。** `.prompt-text` のテキストが問題文です。そのままAPIに渡してください（hCaptcha の表示言語は英語または簡体字中国語に切り替えることを推奨します）。問題文の横に例示画像がある場合は、その画像も `anchors` に含めます。
4. **画像を取得する。** 各タイルの `.task-image .image` の背景画像が 1 枚の画像です。順番にダウンロードして Base64 に変換し、`queries` のリストを作成します。
5. **認識する。** タイプ `HCaptchaClassification` で `createTask` を呼び出します。返される `objects` は各タイルと 1 対 1 に対応しており、`true` のものが対象です。
6. **クリックして送信する。** 対象のタイルをクリックし、送信ボタンを押します。続けて複数ラウンド出題されることがあるため、その場合は手順 3〜6 を繰り返します。
7. **完了。** 通過すると、ページの `h-captcha-response` フィールドに token が入ります。フォームと一緒に送信してください。
## 完全なコード
hcaptcha_click_selenium.py
```python
"""Click through an hCaptcha 3x3 image challenge with Selenium 4 and HCaptchaClassification.
Flow: open the page -> click the checkbox -> read the question and the 9 images ->
ask YesCaptcha which images match -> click them -> submit. Repeat while new rounds appear.
Run: pip install requests selenium
export YESCAPTCHA_CLIENT_KEY=your_client_key
python hcaptcha_click_selenium.py
Each recognized round is charged (see the price list; rounds with no target found are free).
hCaptcha changes its page structure often; adjust the selectors below if a step stops working.
Click and drag questions return coordinates instead; see the HCaptchaClassification page.
"""
import base64
import os
import re
import time
import requests
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.wait import WebDriverWait
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
PAGE_URL = "https://accounts.hcaptcha.com/demo"
def classify(question, images_b64):
task = {"type": "HCaptchaClassification", "question": question, "queries": images_b64}
data = requests.post(
"https://api.yescaptcha.com/createTask",
json={"clientKey": CLIENT_KEY, "task": task},
timeout=60,
).json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data["solution"] # synchronous
def background_image_b64(element):
"""The tiles are s with a CSS background image; download it and Base64-encode it."""
style = element.get_attribute("style") or ""
match = re.search(r'url\("?(.*?)"?\)', style)
if not match:
return None
return base64.b64encode(requests.get(match.group(1), timeout=30).content).decode()
driver = webdriver.Chrome()
wait = WebDriverWait(driver, 15)
try:
driver.get(PAGE_URL)
# 1. Click the checkbox (inside the first hCaptcha iframe)
wait.until(EC.frame_to_be_available_and_switch_to_it(
(By.CSS_SELECTOR, 'iframe[src*="hcaptcha"][src*="frame=checkbox"]')))
wait.until(EC.element_to_be_clickable((By.ID, "checkbox"))).click()
driver.switch_to.default_content()
# 2. Solve rounds in the challenge iframe
wait.until(EC.frame_to_be_available_and_switch_to_it(
(By.CSS_SELECTOR, 'iframe[src*="hcaptcha"][src*="frame=challenge"]')))
for _ in range(5):
question = wait.until(EC.presence_of_element_located((By.CSS_SELECTOR, ".prompt-text"))).text.strip()
tiles = driver.find_elements(By.CSS_SELECTOR, ".task-image")
images = [background_image_b64(t.find_element(By.CSS_SELECTOR, ".image")) for t in tiles]
if not tiles or None in images:
print("not a 3x3 image challenge; see the docs for click/drag questions")
break
solution = classify(question, images)
for tile, hit in zip(tiles, solution.get("objects", [])):
if hit:
tile.click()
time.sleep(0.3)
driver.find_element(By.CSS_SELECTOR, ".button-submit").click()
time.sleep(3)
if not driver.find_elements(By.CSS_SELECTOR, ".task-image"):
break
driver.switch_to.default_content()
token = driver.find_element(By.NAME, "h-captcha-response").get_attribute("value")
print("token received" if token else "not passed")
finally:
driver.quit()
```
## 注意事項
- hCaptcha のページ構造は頻繁に変わります。コード内のセレクターが機能しなくなった場合は、実際のページに合わせて調整してください。
- 認識を行ったラウンドごとに課金されます。対象が見つからなかったラウンドは課金されません。クリック後に検証に失敗した場合は、1 時間以内に [報告](https://docs.yescaptcha.com/ja/api/report.md) すると、報告による返金を申請できます。
- 新しい問題で `ERROR_UNKNOWN_QUESTION` が返された場合は、ページを更新して別の問題に切り替えるか、サポートにお問い合わせください。
---
# サンプルコードと SDK
> YesCaptcha の実行可能なサンプルコード（Python、Node.js、curl、C#、易語言）と、ユーザー提供の非公式 SDK（Python、Node.js、Go）。
Source: https://docs.yescaptcha.com/ja/samples/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/samples/
ここにあるサンプルは、そのまま実行できる完全なファイルです。環境変数 `YESCAPTCHA_CLIENT_KEY` から clientKey を読み込みます。各タスクタイプのページにも、そのタイプ向けに生成した curl、Python、Node.js のサンプルがあります。
[Python](https://docs.yescaptcha.com/ja/samples/python.md)残高の確認、最初のリクエスト、再利用できるクライアント、同時実行の制御、Selenium
[Node.js](https://docs.yescaptcha.com/ja/samples/nodejs.md)Node.js 18+、外部ライブラリ不要
[C#](https://docs.yescaptcha.com/ja/samples/csharp.md).NET 6+
[易語言](https://docs.yescaptcha.com/ja/samples/easy-language.md)ユーザー提供のクリック操作シミュレーションのサンプル
コマンドラインだけでテストする場合の curl の例は、[クイックスタート](https://docs.yescaptcha.com/ja/getting-started/quickstart.md) と [getBalance](https://docs.yescaptcha.com/ja/api/get-balance.md) を参照してください。
## コミュニティ SDK
以下の SDK はユーザーが提供したもので、**非公式**です。コードのレビューは行っていません。ご利用の前にご自身で評価してください。問題がある場合は作者にお問い合わせください。
| 言語 | プロジェクト |
| --- | --- |
| Python | [github.com/yescaptcha/yescaptcha-python](https://github.com/yescaptcha/yescaptcha-python) |
| Node.js | [github.com/ScoLib/yescaptcha](https://github.com/ScoLib/yescaptcha) |
| Go | [github.com/FreedWu/yescaptcha](https://github.com/FreedWu/yescaptcha) |
| Go | [github.com/deanxv/yescaptcha-go](https://github.com/deanxv/yescaptcha-go) |
どの SDK を使う場合でも、接続先が `api.yescaptcha.com` または `cn.yescaptcha.com` であること、およびタスクタイプ名が本サイトと一致していることを確認してください。
---
# Python
> YesCaptcha の Python サンプル。残高の確認、画像キャプチャの認識、再利用できるクライアントクラス（タスク作成、5 秒ごとのポーリング）、asyncio による同時実行数の制御、requests と Selenium による reCAPTCHA の送信。
Source: https://docs.yescaptcha.com/ja/samples/python/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/samples/python/
動作環境：Python 3.8 以上、`pip install requests`。実行前に環境変数を設定します。
```bash
export YESCAPTCHA_CLIENT_KEY=你的clientKey
```
## 残高を確認する
課金されません。`clientKey` が正しいかどうかの確認に使えます。
get_balance.py
```python
"""Check the balance. getBalance is free and is a quick way to verify your clientKey."""
import os
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
r = requests.post(
"https://api.yescaptcha.com/getBalance",
json={"clientKey": CLIENT_KEY},
timeout=30,
)
data = r.json()
if data.get("errorId"):
# e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
print("error:", data.get("errorCode"), data.get("errorDescription"))
else:
print("balance (points):", data["balance"])
```
## 画像キャプチャを認識する
同期タイプ `ImageToTextTaskOcrBase` は、1 回のリクエストで結果を取得できます。サンプル画像：[captcha.jpg](https://docs.yescaptcha.com/samples/captcha.jpg)。
quickstart.py
```python
"""First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase
(synchronous, 2 points per image).
Usage:
export YESCAPTCHA_CLIENT_KEY=your_client_key
python quickstart.py captcha.png
"""
import base64
import os
import sys
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
image_path = sys.argv[1] if len(sys.argv) > 1 else "captcha.png"
with open(image_path, "rb") as f:
body = base64.b64encode(f.read()).decode() # no "data:" prefix
r = requests.post(
"https://api.yescaptcha.com/createTask",
json={
"clientKey": CLIENT_KEY,
"task": {"type": "ImageToTextTaskOcrBase", "body": body},
},
timeout=30,
)
data = r.json()
if data.get("errorId"):
raise SystemExit(f"{data.get('errorCode')}: {data.get('errorDescription')}")
print("text:", data["solution"]["text"])
```
## 再利用できるクライアント
次のファイルをプロジェクトにコピーしてください。同期・非同期どちらのタイプにも使えます。
yescaptcha.py
```python
"""A small client you can copy into your project: create tasks, poll results, check the balance.
from yescaptcha import YesCaptcha
client = YesCaptcha(os.environ["YESCAPTCHA_CLIENT_KEY"])
solution = client.solve({
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})
print(solution["gRecaptchaResponse"])
"""
import os
import time
import requests
class YesCaptchaError(Exception):
def __init__(self, code, description):
super().__init__(f"{code}: {description}")
self.code = code
self.description = description
class YesCaptcha:
def __init__(self, client_key, endpoint="https://api.yescaptcha.com", poll_interval=5, timeout=180):
self.client_key = client_key
self.endpoint = endpoint.rstrip("/")
self.poll_interval = poll_interval # 5 s: polling the same taskId more often only returns "processing"
self.timeout = timeout
self.session = requests.Session()
def call(self, method, payload=None):
body = {"clientKey": self.client_key, **(payload or {})}
data = self.session.post(f"{self.endpoint}/{method}", json=body, timeout=30).json()
if data.get("errorId"):
raise YesCaptchaError(data.get("errorCode"), data.get("errorDescription"))
return data
def balance(self):
return self.call("getBalance")["balance"]
def solve(self, task):
created = self.call("createTask", {"task": task})
if created.get("status") == "ready": # synchronous types return the solution directly
return created["solution"]
task_id = created["taskId"]
deadline = time.time() + self.timeout
while time.time() < deadline:
time.sleep(self.poll_interval)
result = self.call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]
raise TimeoutError(f"task {task_id} not ready after {self.timeout}s")
if __name__ == "__main__":
client = YesCaptcha(os.environ["YESCAPTCHA_CLIENT_KEY"])
print("balance:", client.balance())
```
```python
from yescaptcha import YesCaptcha
client = YesCaptcha(os.environ["YESCAPTCHA_CLIENT_KEY"])
solution = client.solve({
"type": "HCaptchaTaskProxyless",
"websiteURL": "https://accounts.hcaptcha.com/demo",
"websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
})
print(solution["gRecaptchaResponse"])
```
エラー時は `YesCaptchaError` が送出されます。`e.code` がエラーコードです。意味は [エラーコード](https://docs.yescaptcha.com/ja/api/errors.md) を参照してください。
## 同時実行数を制御する
タスクをまとめて送るときは、同時に処理中となるリクエスト数を制限し、`ERROR_THREADS_MAXIMUM` を受け取ったら少し待ってから再試行します（`pip install aiohttp` が必要）。詳しくは [同時実行数の上限と自動一時停止](https://docs.yescaptcha.com/ja/api/rate-limits.md) を参照してください。
concurrency.py
```python
"""Limit concurrency: keep the number of requests waiting for a result below your limit, and back off
on ERROR_THREADS_MAXIMUM (rejected requests are not charged). Requires: pip install aiohttp"""
import asyncio
import os
import aiohttp
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
LIMIT = 15 # below your concurrency limit
sem = asyncio.Semaphore(LIMIT)
async def solve(session, task):
async with sem: # at most LIMIT requests in progress at a time
result = {}
for attempt in range(5):
async with session.post(
"https://api.yescaptcha.com/createTask",
json={"clientKey": CLIENT_KEY, "task": task},
) as resp:
result = await resp.json()
if result.get("errorCode") != "ERROR_THREADS_MAXIMUM":
return result
await asyncio.sleep(1 + attempt) # over the limit: wait and retry
return result
async def main(tasks):
async with aiohttp.ClientSession() as session:
return await asyncio.gather(*(solve(session, t) for t in tasks))
if __name__ == "__main__":
print(asyncio.run(main([])))
```
## reCAPTCHA の token を送信する
- requests で直接送信する：[token で reCAPTCHA を完了する](https://docs.yescaptcha.com/ja/guides/submit-recaptcha-token.md) を参照
- Selenium でブラウザに入力する：[token で reCAPTCHA を完了する](https://docs.yescaptcha.com/ja/guides/submit-recaptcha-token.md) を参照
- Selenium で画像問題のクリックを再現する：[reCAPTCHA v2 画像認識によるクリックの再現](https://docs.yescaptcha.com/ja/guides/recaptcha-click-selenium.md)、[hCaptcha 画像認識によるクリックの再現](https://docs.yescaptcha.com/ja/guides/hcaptcha-click-selenium.md) を参照
---
# Node.js
> YesCaptcha の Node.js サンプル(Node.js 18 以上、組み込みの fetch を使用、外部ライブラリ不要)。残高の確認、画像キャプチャの認識、再利用できるクライアントクラス(タスクの作成、5 秒ごとのポーリング)。
Source: https://docs.yescaptcha.com/ja/samples/nodejs/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/samples/nodejs/
実行環境は Node.js 18 以上(組み込みの `fetch` を使用)です。サンプルは ES module(`.mjs`)で、外部ライブラリのインストールは不要です。実行前に環境変数を設定してください。
```bash
export YESCAPTCHA_CLIENT_KEY=你的clientKey
```
## 残高を確認する
ポイントは消費しません。clientKey が正しいかどうかの確認に使います。
get-balance.mjs
```js
// Check the balance. getBalance is free and is a quick way to verify your clientKey. Node.js 18+
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;
const res = await fetch('https://api.yescaptcha.com/getBalance', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY }),
});
const data = await res.json();
if (data.errorId) {
// e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
console.log('error:', data.errorCode, data.errorDescription);
} else {
console.log('balance (points):', data.balance);
}
```
## 画像キャプチャを1枚認識する
同期タイプ `ImageToTextTaskOcrBase` で、1 回のリクエストで結果を取得します。サンプル画像: [captcha.jpg](https://docs.yescaptcha.com/samples/captcha.jpg)。`node quickstart.mjs captcha.jpg` で実行します。
quickstart.mjs
```js
// First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase (synchronous, 2 points per image).
// Usage: YESCAPTCHA_CLIENT_KEY=your_client_key node quickstart.mjs captcha.png
import { readFileSync } from 'node:fs';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;
const body = readFileSync(process.argv[2] ?? 'captcha.png').toString('base64'); // no "data:" prefix
const res = await fetch('https://api.yescaptcha.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY, task: { type: 'ImageToTextTaskOcrBase', body } }),
});
const data = await res.json();
if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
console.log('text:', data.solution.text);
```
## 再利用できるクライアント
yescaptcha.mjs
```js
// A small client you can copy into your project: create tasks, poll results, check the balance. Node.js 18+
//
// import { YesCaptcha } from './yescaptcha.mjs';
// const client = new YesCaptcha(process.env.YESCAPTCHA_CLIENT_KEY);
// const solution = await client.solve({ type: 'NoCaptchaTaskProxyless', websiteURL: '...', websiteKey: '...' });
export class YesCaptchaError extends Error {
constructor(code, description) {
super(`${code}: ${description}`);
this.code = code;
}
}
export class YesCaptcha {
constructor(clientKey, { endpoint = 'https://api.yescaptcha.com', pollInterval = 5000, timeout = 180000 } = {}) {
this.clientKey = clientKey;
this.endpoint = endpoint.replace(/\/$/, '');
this.pollInterval = pollInterval; // 5 s: polling the same taskId more often only returns "processing"
this.timeout = timeout;
}
async call(method, payload = {}) {
const res = await fetch(`${this.endpoint}/${method}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: this.clientKey, ...payload }),
});
const data = await res.json();
if (data.errorId) throw new YesCaptchaError(data.errorCode, data.errorDescription);
return data;
}
async balance() {
return (await this.call('getBalance')).balance;
}
async solve(task) {
const created = await this.call('createTask', { task });
if (created.status === 'ready') return created.solution; // synchronous types return the solution directly
const deadline = Date.now() + this.timeout;
while (Date.now() < deadline) {
await new Promise((r) => setTimeout(r, this.pollInterval));
const result = await this.call('getTaskResult', { taskId: created.taskId });
if (result.status === 'ready') return result.solution;
}
throw new Error(`task ${created.taskId} not ready after ${this.timeout} ms`);
}
}
if (import.meta.url === `file://${process.argv[1]}`) {
const client = new YesCaptcha(process.env.YESCAPTCHA_CLIENT_KEY);
console.log('balance:', await client.balance());
}
```
```js
import { YesCaptcha } from './yescaptcha.mjs';
const client = new YesCaptcha(process.env.YESCAPTCHA_CLIENT_KEY);
const solution = await client.solve({
type: 'TurnstileTaskProxyless',
websiteURL: 'https://example.com/login',
websiteKey: '0x4AAAAAAA_SITE_KEY',
});
console.log(solution.token);
```
エラー時は `YesCaptchaError` がスローされます。`err.code` がエラーコードで、意味は[エラーコード](https://docs.yescaptcha.com/ja/api/errors.md)を参照してください。
---
# C#
> YesCaptcha の C# サンプル（.NET 6+、HttpClient + System.Text.Json）：残高を照会し、reCAPTCHA v2 タスクを作成して 5 秒ごとに結果をポーリングします。
Source: https://docs.yescaptcha.com/ja/samples/csharp/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/samples/csharp/
動作環境：.NET 6 以上。標準ライブラリ（`HttpClient`、`System.Text.Json`）のみを使用します。
```bash
dotnet new console -o YesCaptchaDemo
cd YesCaptchaDemo
# 下のコードで Program.cs を置き換える
export YESCAPTCHA_CLIENT_KEY=你的clientKey
dotnet run
```
Program.cs
```csharp
// YesCaptcha C# sample (.NET 6+): check the balance, then solve a reCAPTCHA v2.
// Run: dotnet new console -o YesCaptchaDemo, replace Program.cs with this file, set YESCAPTCHA_CLIENT_KEY, then dotnet run
using System;
using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json;
using System.Text.Json.Nodes;
using System.Threading.Tasks;
class Program
{
const string Api = "https://api.yescaptcha.com";
static readonly HttpClient Http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
static readonly string ClientKey = Environment.GetEnvironmentVariable("YESCAPTCHA_CLIENT_KEY") ?? "";
static async Task Call(string method, JsonObject payload)
{
payload["clientKey"] = ClientKey;
var res = await Http.PostAsJsonAsync($"{Api}/{method}", payload);
var data = JsonNode.Parse(await res.Content.ReadAsStringAsync())!;
if ((int?)data["errorId"] != 0)
throw new Exception($"{data["errorCode"]}: {data["errorDescription"]}");
return data;
}
static async Task Solve(JsonObject task)
{
var created = await Call("createTask", new JsonObject { ["task"] = task });
if ((string?)created["status"] == "ready") return created["solution"]!; // synchronous types
var taskId = (string)created["taskId"]!;
for (var i = 0; i < 36; i++) // poll every 5 seconds, for up to about 3 minutes
{
await Task.Delay(5000);
var result = await Call("getTaskResult", new JsonObject { ["taskId"] = taskId });
if ((string?)result["status"] == "ready") return result["solution"]!;
}
throw new TimeoutException(taskId);
}
static async Task Main()
{
var balance = await Call("getBalance", new JsonObject());
Console.WriteLine($"balance (points): {balance["balance"]}");
var solution = await Solve(new JsonObject
{
["type"] = "NoCaptchaTaskProxyless",
["websiteURL"] = "https://www.google.com/recaptcha/api2/demo",
["websiteKey"] = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
Console.WriteLine(solution["gRecaptchaResponse"]);
}
}
```
他のタスクタイプに切り替えるときは、`Solve` に渡すタスクオブジェクトだけを変更します。フィールドは各 [タスクタイプ](https://docs.yescaptcha.com/ja/tasks.md) のページを参照してください。同期タイプ（画像認識、`ImageToTextTaskOcrBase`）は `createTask` の中で直接結果を返します。`Solve` はこのケースにも対応済みです。
---
# 易語言（Easy Language）
> ユーザー提供の YesCaptcha 易語言サンプル。reCAPTCHA・hCaptcha のクリック操作、FunCaptcha の画像認識、reCAPTCHA token の送信。ダウンロードと API 呼び出しのポイント。
Source: https://docs.yescaptcha.com/ja/samples/easy-language/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/samples/easy-language/
易語言（Easy Language）は、中国で広く使われている中国語のプログラミング言語です。このサンプルはユーザーから提供されたもので、参考用です。1 行ずつの審査は行っていません。サンプルには次の内容が含まれます。
- reCAPTCHA、hCaptcha のクリック操作（ブラウザを起動した後、自動で認識してクリック）
- FunCaptcha の画像認識
- reCAPTCHA token の送信
> **ダウンロード:** サンプルパッケージ（最大で約 87 MB、ブラウザを含む）は、新しいダウンロード先に移行中です。それまでは [サポートへお問い合わせ](https://docs.yescaptcha.com/ja/help/contact.md) のうえ、入手してください。
## 易語言から API を呼び出すポイント
サンプルパッケージがなくても、易語言のウェブアクセス命令（POST）で API を呼び出せます。
1. URL は `https://api.yescaptcha.com/createTask`、メソッドは `POST`、ヘッダーに `Content-Type: application/json` を追加します。
2. 送信する内容は JSON テキストです。例: `{"clientKey":"あなたのclientKey","task":{"type":"ImageToTextTaskOcrBase","body":"画像のBase64"}}`
3. 返された JSON の `errorId` が 0 なら成功です。非同期タイプでは `taskId` を取得し、5 秒ごとに `https://api.yescaptcha.com/getTaskResult` へ `{"clientKey":"…","taskId":"…"}` を送信して、`status` が `ready` になるまでポーリングします。
4. 画像の Base64 には `data:image/...;base64,` のプレフィックスを付けず、改行も含めないでください。
リクエストとレスポンスの形式は [リクエストとレスポンス](https://docs.yescaptcha.com/ja/api/overview.md) を参照してください。
## サンプルが動かない場合
- ブラウザを作成できないと表示される: パッケージに同梱のブラウザを使う、競合の可能性がある他のブラウザをアンインストールする、またはプログラムとしてコンパイルしてから実行してください。
- エラーコードが返る: [エラーコード](https://docs.yescaptcha.com/ja/api/errors.md) と照らし合わせて、パラメーターを確認してください。
---
# 複数の clientKey：上限、IP 許可リスト、有効期限
> 1 つの YesCaptcha アカウントで最大 20 個の clientKey を使え、すべて同じアカウント残高から課金されます。各 clientKey に、利用上限（毎日・毎週・毎月、または一括の合計。北京時間でリセット）、IP 許可リスト、有効期限を個別に設定でき、数秒で反映されます。
Source: https://docs.yescaptcha.com/ja/account/client-keys/ · Last verified: 2026-10-29
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/account/client-keys/
1 つの YesCaptcha アカウントには、最大 20 個の `clientKey`（元からある 1 つを含む）を持てます。[yescaptcha.com](https://yescaptcha.com/security) ダッシュボードの「キーとセキュリティ」ページで管理します。どの `clientKey` でもタスクの作成と残高の確認ができ、課金されるのはすべて同じアカウント残高です。それぞれに利用上限、IP 許可リスト、有効期限を個別に設定でき、数秒で反映されます。
次のような場合に便利です。テスト環境と本番環境、プロジェクトごとにキーを分ける。下流の顧客やパートナーにキーを渡し、それぞれに上限を設ける。ある `clientKey` が漏えいしても、そのキーだけを削除すれば、ほかのプログラムには影響しません。
## メイン Key とサブ Key
| | メイン Key | サブ Key |
| --- | --- | --- |
| 内容 | 元からある `clientKey`。アカウントに 1 つ | メイン Key とは別に作成したキー。最大 19 個 |
| 上限、IP 許可リスト、有効期限 | 設定できる | 設定できる |
| リセット | できる：古いキーはすぐ無効になり、残高は新しいキーに移る | できない。削除して作り直す |
| 削除 | できない | できる：数秒で無効になり、元に戻せない |
- 形式はどれも同じです。先頭 40 文字がシークレットで、その後ろにユーザー ID が続きます。
- メイン Key をリセットしても、サブ Key には影響しません。
- タスクの作成や残高の確認にどの `clientKey` を使っても、API とレスポンスは同じです。違いは、上限・許可リスト・有効期限のチェックが加わる点だけです。
## clientKey を作成する
1. [yescaptcha.com](https://yescaptcha.com/) にログインし、「キーとセキュリティ」ページ（[yescaptcha.com/security](https://yescaptcha.com/security)）を開きます。
2. 「すべての Key」で「サブ Key を作成」をクリックします。名前（最大 40 文字）、上限、IP 許可リスト、有効期限はいずれも省略でき、後から変更もできます。
3. 案内に従って、もう一度本人確認を行います。作成・変更・削除のいずれにも本人確認が必要です。
4. 作成後、完全な `clientKey` をコピーしてプログラムに設定します。後から、一覧の目のアイコンをクリックして再表示することもできます。
> **ノート:** 作成・変更・削除は数秒で反映されます。作成直後に呼び出すと `ERROR_KEY_DOES_NOT_EXIST` が返ることがあります。数秒待ってからもう一度試してください。また、削除したり設定を厳しくしたりした直後の数秒間は、すでに送信中のリクエストが以前の設定のまま処理されることがあります。
## 利用上限
上限は、1 つの `clientKey` が 1 つの期間内に使えるポイントの最大値です（1,000 ポイント = ¥1）。1 から 10,000,000,000 ポイントまで設定できます。期間は 4 種類で、北京時間（UTC+8）でリセットされます。
| 期間 | リセットのタイミング |
| --- | --- |
| 毎日 | 毎日 0 時 |
| 毎週 | 毎週月曜 0 時 |
| 毎月 | 毎月 1 日 0 時 |
| 一括の合計 | リセットされません。使い切ると、この `clientKey` ではタスクを作成できなくなります。引き続き使うには上限を引き上げてください |
- 実際に課金されたポイントで計算します。認識の失敗やタイムアウトで返金されたポイントは、上限にも戻ります。
- 今の期間の残り上限がタスクの課金額に足りない場合、`createTask` は [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED) を返します。課金されず、[自動一時停止](https://docs.yescaptcha.com/ja/api/rate-limits.md)にもカウントされません。
- ダッシュボードの一覧で、各 `clientKey` が今の期間にどれだけ使ったか、次にいつリセットされるかを確認できます。
- 上限は独立した残高ではありません。すべての `clientKey` が同じアカウント残高から課金され、アカウント残高が足りないときは通常どおり `ERROR_ZERO_BALANCE` が返ります。
上限を設定した `clientKey` で [`getBalance`](https://docs.yescaptcha.com/ja/api/get-balance.md) を呼ぶと、`balance` にはアカウント残高と今の期間の残り上限のうち小さいほうが入り、さらに `keyQuotaRemaining`（残りの上限、ポイント）が加わります。上限を設定していない `clientKey` にはこのフィールドは付かず、レスポンスは従来と同じです。
```json
{
"errorId": 0,
"balance": 20000,
"softBalance": 0,
"inviteBalance": 0,
"inviteBy": 0,
"keyQuotaRemaining": 20000
}
```
## IP 許可リスト
IP 許可リストを設定した `clientKey` は、リストにある IP から送信されたリクエストだけが使えます。空欄にすると制限しません。
- 登録するのは **YesCaptcha の API を呼び出すマシンのパブリック IP**（送信元 IP）です。タスクのパラメータにあるプロキシではありません。複数のマシンから呼び出す場合は、すべてのパブリック IP を追加してください。
- 1 行に 1 つ、IPv4 または IPv6 アドレス、もしくは CIDR 範囲を書きます。最大 50 件です。アドレス 1 つだけの場合は、その IP のみを許可します。
- 範囲はネットワークアドレスで書きます。`203.0.113.0/24` は使えますが、`203.0.113.5/24` は使えません（ホスト部が 0 ではないため）。
```text
203.0.113.10
198.51.100.0/24
2001:db8::/32
```
- リクエストの IP がリストにない場合、`createTask` と `getBalance` は [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) を返します。課金されず、自動一時停止にもカウントされません。
- 送信元 IP が変わる環境（家庭用ブロードバンド、クラウド関数、ローテーションする送信元など）では設定しないか、範囲全体を許可してください。
## 有効期限
- どの `clientKey`（メイン Key を含む）にも有効期限を設定できます。10 年以内の日時を指定します。その後はいつでも変更したり、削除したりできます。
- 期限が切れると、そのキーでの `createTask` と `getBalance` は [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_KEY_EXPIRED) を返し、課金されません。すでに作成済みのタスクは、これまでどおり `getTaskResult` で結果を取得できます。
- 長期間使われていない `clientKey` には、アカウントの安全を守るため、システムが有効期限を設定し、期限の前にメールでお知らせします。この有効期限は変更できません。メイン Key を再生成する（残高は自動的に新しいキーに移ります）か、新しい `clientKey` を作成して、プログラムを更新してください。
## 残高、同時実行数の上限、自動一時停止
- **残高**：すべての `clientKey` が同じアカウント残高から課金されます。チャージ、VIP のチャージボーナス、紹介報酬、開発者収益分配はすべてアカウント単位で、どの `clientKey` を使うかは関係ありません。
- **同時実行数の上限**：アカウント単位で計算され、すべての `clientKey` が同じ上限を共有します。詳しくは [同時実行数の上限と自動一時停止](https://docs.yescaptcha.com/ja/api/rate-limits.md) を参照してください。
- **自動一時停止**：`clientKey` ごとに計算されます。ある `clientKey` がエラーの多さで一時停止されても、ほかのキーには影響しません。
## 関連するエラーコード
| エラーコード | 返されるタイミング |
| --- | --- |
| [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED) | 今の期間の残り上限がこのタスクの課金額に足りない（`createTask`） |
| [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) | リクエストの IP がこの `clientKey` の IP 許可リストにない（`createTask`、`getBalance`） |
| [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/ja/api/errors.md#ERROR_KEY_EXPIRED) | `clientKey` の有効期限が切れている（`createTask`、`getBalance`） |
この 3 つはいずれも課金されません。対処方法は [エラーコード](https://docs.yescaptcha.com/ja/api/errors.md) を参照してください。
---
# チャージと VIP
> YesCaptcha のチャージ方法（WeChat Pay、Alipay、PayPal、暗号資産）。1,000 ポイント = ¥1。累計チャージ額に応じて VIP 1 から VIP 10 まで自動でアップグレードされ、以降のチャージにはボーナスポイントが付与されます。
Source: https://docs.yescaptcha.com/ja/account/recharge/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/account/recharge/
[yescaptcha.com](https://yescaptcha.com/) のダッシュボードにあるチャージページ（[yescaptcha.com/payment.html](https://yescaptcha.com/payment.html)）からチャージします。1,000 ポイント = ¥1 で、反映後すぐに使えます。累計チャージ額が一定額に達すると自動的に VIP にアップグレードされ、以降のチャージでは VIP レベルに応じた割合のチャージボーナスが追加で付与されます。
## チャージ方法
| 方法 | 説明 |
| --- | --- |
| WeChat Pay | QR コードで支払い |
| Alipay | QR コードまたはリダイレクトで支払い |
| PayPal | 中国国外のユーザー向け |
| 暗号資産 | Cryptomus 経由。BTC、ETH、USDT などに対応 |
| 銀行振込 | サポートに連絡してください。経理の確認後、手動で加算します |
チャージ履歴はチャージページで確認できます。チャージで問題が発生した場合は、注文情報を添えて[サポートに連絡](https://docs.yescaptcha.com/ja/help/contact.md)してください。
## VIP レベル
累計チャージ額が下表のしきい値に達すると、対応するレベルに自動でアップグレードされます。アップグレード後は、以降のチャージのたびにボーナス率に応じたポイントが追加で付与されます。
| レベル | 累計チャージ額 | チャージごとのボーナス |
| --- | --- | --- |
| VIP 1 | 10 元 | 2% |
| VIP 2 | 100 元 | 5% |
| VIP 3 | 500 元 | 8% |
| VIP 4 | 1,000 元 | 10% |
| VIP 5 | 2,000 元 | 15% |
| VIP 6 | 3,000 元 | 20% |
| VIP 7 | 6,000 元 | 25% |
| VIP 8 | 12,000 元 | 30% |
| VIP 9 | 24,000 元 | 35% |
| VIP 10 | 48,000 元 | 40% |
- **累計で計算**：何回に分けてチャージしても、累計額がしきい値に達した時点でアップグレードされます。
- **チャージ後の累計額で判定**：たとえば初回に 1000 元をチャージして累計額が VIP 4 のしきい値に達した場合、そのチャージには VIP 4 のボーナス率が適用されます。
- 友人の招待リンクから登録すると、一定の VIP レベルがすぐに付与されます。詳しくは[紹介報酬](https://docs.yescaptcha.com/ja/account/referral.md)を参照してください。
- 現在のレベルとボーナス率は、ダッシュボードのチャージページで確認できます。
---
# 紹介プログラム
> YesCaptcha の紹介プログラム。紹介したユーザーは登録時に VIP を獲得し（あなたのレベル−1、VIP 1〜VIP 6）、あなたは相手の利用金額の 20% を受け取れます（開発者収益分配も適用される場合は各 10%）。報酬は残高に振り替えるか、100 元から ダッシュボードで出金を申請できます。
Source: https://docs.yescaptcha.com/ja/account/referral/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/account/referral/
友人を YesCaptcha に紹介すると、友人は登録と同時に VIP レベルを獲得し、あなたは友人の利用金額の 20% を報酬として受け取れます。報酬はアカウントの残高に振り替えられるほか、100 元に達するとダッシュボードから出金を申請できます。
## 紹介の方法
[yescaptcha.com](https://yescaptcha.com/) のダッシュボードにログインすると、紹介プログラムのパネルで、紹介リンク、紹介した人数、累計の報酬を確認できます。紹介リンクを友人に送り、友人がそのリンクから登録すれば完了です。
## ルール
1. **友人の VIP**：友人は登録後すぐに VIP レベルを獲得します。レベルはあなたのレベル−1で、最低 VIP 1、最高 VIP 6 です。たとえばあなたが VIP 6 なら、友人は登録後に VIP 5 になります。各レベルのチャージボーナス率は [チャージと VIP](https://docs.yescaptcha.com/ja/account/recharge.md) を参照してください。
2. **あなたの報酬**：友人が利用するたび（認識による課金）、利用金額の **20%** を受け取れます。
3. **開発者収益分配と併用される場合**：友人のタスクに開発者の ID も付いているとき（[開発者収益分配](https://docs.yescaptcha.com/ja/account/developer.md) を参照）、紹介者と開発者は**それぞれ 10%** を受け取ります。
4. 友人が認識ミスを報告して報告による返金を受けたタスクについては、対応する報酬が差し引かれます。
5. 報酬の残高は [getBalance](https://docs.yescaptcha.com/ja/api/get-balance.md) の `inviteBalance` で確認できます（単位：元）。
## 報酬の使い方
- **残高に振り替える**：ダッシュボードで報酬をアカウントの残高に振り替えます。1 元 = 1000 ポイントで認識に利用できます。
- **出金**：報酬が **100 元**に達したら、ダッシュボードで出金を申請します。審査後に振り込まれます。
- 出金による収入の所得税は、ご自身で申告してください。
## 記事で紹介する
フォーラム、ブログ、SNS などで、YesCaptcha に関する紹介記事、チュートリアル、活用事例、拡張機能やコードライブラリを公開した場合は、リンクをサポートにお送りください。内容を審査のうえ、品質に応じてポイントまたは VIP レベルを付与することがあります。
報酬ルールを変更する場合は、このページと [サービス更新履歴](https://docs.yescaptcha.com/ja/changelog.md) でお知らせします。
---
# 開発者収益分配
> YesCaptcha の開発者収益分配：開発したソフトウェアやプラグインがユーザーに代わって送信するリクエストに softID を含めると、ユーザーの利用金額の 20% を受け取れます（紹介者もいる場合は 10% ずつ）。ダッシュボードで残高に振り替えるか、100 元から出金を申請できます。
Source: https://docs.yescaptcha.com/ja/account/developer/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/account/developer/
開発したソフトウェア、スクリプト、拡張機能で YesCaptcha を利用している場合、他のユーザー向けに送信するリクエストに開発者 ID（`softID`）を含めると、そのユーザーの利用金額に応じた収益分配を受け取れます。ユーザーは自分の `clientKey` で自分のポイントを使うため、分配によってユーザーの負担が増えることはありません。
## 導入方法
1. 自分の `clientKey` で [getSoftID](https://docs.yescaptcha.com/ja/api/get-soft-id.md) を呼び出し、開発者 ID を取得します。
```json
{
"errorId": 0,
"softID": 3,
"balance": 0.004
}
```
2. ソフトウェアが送信するすべての `createTask` リクエストに、トップレベルのフィールド `softID` を追加します（`clientKey`、`task` と同じ階層。大文字・小文字に注意）。
```json
{
"clientKey": "THE_USERS_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
},
"softID": 3
}
```
`clientKey` は利用者本人のキーです。
## 分配ルール
- `softID` を含むタスクは、ユーザーの実際の利用金額の **20%** が開発者収益分配として計上されます。
- そのユーザーが他の人に紹介されて登録した場合（[紹介報酬](https://docs.yescaptcha.com/ja/account/referral.md)を参照）、開発者と紹介者が**それぞれ 10%** を受け取ります。
- 分配の対象は課金が成立したタスクのみです。失敗やタイムアウトで返金されたタスクは対象外です。ユーザーが認識ミスを報告して報告による返金を受けたタスクについては、対応する分配額が差し引かれます。
- 分配の残高は、[getSoftID](https://docs.yescaptcha.com/ja/api/get-soft-id.md) の `balance` または [getBalance](https://docs.yescaptcha.com/ja/api/get-balance.md) の `softBalance` で確認できます。単位は元です。
## 分配の受け取り方
- **残高への振り替え**：ダッシュボードで分配額をアカウントの残高に振り替えられます。1 元 = 1000 ポイントでキャプチャの認識に使えます。
- **出金**：分配額が **100 元**に達したら、ダッシュボードから出金を申請します。審査後に振り込まれます。
- 出金による収入の所得税は、ご自身で申告してください。
---
# よくある質問
> YesCaptcha のよくある質問。認識に失敗した場合の課金、token の有効期間、通過率、人手か機械か、アカウント停止の可能性、1 つの clientKey の複数環境での利用、エンドポイントの選び方、拡張機能と API の違い。
Source: https://docs.yescaptcha.com/ja/help/faq/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/help/faq/
## YesCaptcha で認識に失敗した場合、課金されますか？
されません。認識失敗（`ERROR_CAPTCHA_UNSOLVABLE`）とタイムアウト（`ERROR_TASK_TIMEOUT`）のタスクは自動で返金され、パラメータエラーなどエラーコードを返したリクエストは課金されません。token を取得できても対象サイトに受け付けられなかった場合は、サイト側の判定結果を把握できないため、成功として課金されます。画像認識タイプで誤ったクリック位置が返った場合は、報告すると報告による返金を申請できます。詳しくは [課金と返金](https://docs.yescaptcha.com/ja/getting-started/billing.md) をご覧ください。
## 1 回の認識にいくらかかりますか？
タスクタイプごとに固定のポイントが課金されます。1 円 = 1000 ポイントで、タイプによって価格は異なります。全価格は [タスクタイプと価格](https://docs.yescaptcha.com/ja/tasks.md) に掲載しています。機械可読版は [/data/task-types.json](https://docs.yescaptcha.com/data/task-types.json) です。
## token の有効期間はどれくらいですか？
reCAPTCHA、hCaptcha、Turnstile の token はいずれも 1 回限り使用できます。reCAPTCHA の token は約 120 秒間有効です。取得後 60 秒以内の送信をおすすめします。有効期間はキャプチャの提供元が決めています。
## 取得した token が通らないことがあるのはなぜですか？
token が通るかどうかは対象サイトが判定します。サイトはスコア、IP、ブラウザ環境などを組み合わせて判断し、基準はいつでも変更される可能性があるため、通過率はサイトによって異なります。同じキャプチャ向けの別のタスクタイプで比較する、プロキシ持ち込み型のタイプを使って送信時にも同じプロキシを経由する、あるいは画像認識を使ってブラウザ上で実際にクリックする、といった方法を試してください。
## 認識にどれくらい時間がかかりますか？
非同期タスクは通常、数秒から数十秒、最長で約 110 秒（一部のタイプは 180〜220 秒）です。タイムアウトすると自動で返金されます。画像認識と画像の英数字認識は同期型で、1 回のリクエストで結果が返ります。
## 人手による認識ですか、機械による認識ですか？
機械による認識で、機械学習モデルを使用しています。
## YesCaptcha を使うとアカウントが停止されることはありますか？
当社が返すのは認識結果のみで、対象サイト上のあなたのアカウントには一切触れません。対象サイトがどのように判定し、アカウントを停止するかどうかはサイト側が決めますので、対象サイトのルールを守ってください。YesCaptcha は合法的な用途に限り、違法な用途での利用は禁止されています。
## 1 つの clientKey を複数のプログラムやブラウザで同時に使えますか？
使えます。同一アカウントのリクエストは [同時実行数の上限](https://docs.yescaptcha.com/ja/api/rate-limits.md) を合算して計算され、残高も共有されます。
## グローバルエンドポイントと中国エンドポイントのどちらを使えばよいですか？
サーバーが中国本土にある場合は `cn.yescaptcha.com`、それ以外の地域では `api.yescaptcha.com` を使用してください。タスクを作成したエンドポイントで結果を取得します。[接続先](https://docs.yescaptcha.com/ja/getting-started/endpoints.md) をご覧ください。
## ブラウザ拡張機能と API の違いは何ですか？
拡張機能も同じ API を呼び出して認識を行います。無料でインストールでき、利用した API 分のポイントが課金されます。コードを書かずにブラウザ上で使いたい場合に向いています。API はプログラムで大量に処理する場合に向いています。[ブラウザ拡張機能](https://docs.yescaptcha.com/ja/extension.md) をご覧ください。
## ERROR\_IP\_BLOCKED\_5MIN が返って一時停止されたのはなぜですか？
同じ clientKey で 1 分間にエラーとなるリクエストが多く発生したため、数分間自動一時停止されました。期間が過ぎると自動で復旧します。レスポンスの `blockReason` は一時停止の原因となったエラーコードですので、それに従ってプログラムを修正してください。[同時実行数の上限と自動一時停止](https://docs.yescaptcha.com/ja/api/rate-limits.md) をご覧ください。
## 対応しているサイトは？
キャプチャの種類ごとに認識を提供しており、特定のサイトを対象にしたものではありません。通過できるかどうかは対象サイトの設定次第ですので、まず少量でテストすることをおすすめします。一部のサイトが未対応の場合は `ERROR_DOMAIN_NOT_ALLOWED` が返ります。
---
# 接続とネットワークの問題
> YesCaptcha API に接続できないときの対処法。Failed to establish a new connection、DNS 解決の失敗、プロキシソフトの干渉、SSL 証明書エラー（Certificate has expired、SSLEOFError）の切り分け手順。
Source: https://docs.yescaptcha.com/ja/help/troubleshooting/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/help/troubleshooting/
API 呼び出しで接続エラー（例: `Failed to establish a new connection`、`getaddrinfo failed`、タイムアウト、SSL エラー）が出る場合、多くは手元のネットワーク、DNS、プロキシソフトが原因です。以下の順に確認してください。
## 1\. 別のエンドポイントを試す
YesCaptcha にはエンドポイントが 2 つあります。`https://api.yescaptcha.com`（グローバル）と `https://cn.yescaptcha.com`（中国）です。中国本土のサーバーでは中国エンドポイントを、それ以外の地域ではグローバルエンドポイントを使います。エンドポイントを切り替えたら、結果の取得にも同じエンドポイントを使ってください。
```bash
curl -s https://api.yescaptcha.com/getBalance -H 'Content-Type: application/json' -d '{"clientKey": "YOUR_CLIENT_KEY"}'
curl -s https://cn.yescaptcha.com/getBalance -H 'Content-Type: application/json' -d '{"clientKey": "YOUR_CLIENT_KEY"}'
```
どちらか一方でも JSON が返れば、ネットワーク自体は正常です。もう一方のエンドポイントへの経路に問題があります。
## 2\. プロキシソフトを確認する
YesCaptcha への接続にプロキシは不要です。プロキシや VPN ソフトを起動している場合は次のようにします。
- いったんオフにして再試行する。
- オフにできない場合は、グローバルモードではなくルールベース（PAC モード）の振り分けにするか、`api.yescaptcha.com` と `cn.yescaptcha.com` を直接接続のリストに追加する。
- プロキシ使用中の Python で `SSLEOFError(8, 'EOF occurred in violation of protocol')` が出る場合も、たいていはプロキシが原因です。プロキシをオフにするか、この 2 つのドメインを直接接続にしてください。
## 3\. ネットワークと DNS を確認する
```bash
ping api.yescaptcha.com
```
- ホストが見つからないと表示される場合: DNS 解決に失敗しています。DNS キャッシュをフラッシュする（Windows: `ipconfig /flushdns`、macOS: `sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder`）か、パブリック DNS（例: `223.5.5.5`、`119.29.29.29`、`8.8.8.8`）に変更して再試行してください。
- ping は通らないがアドレスは解決できる場合: ネットワークが ICMP を遮断している可能性があります。API に接続できないという意味ではないので、手順 1 の curl の結果で判断してください。
## 4\. SSL 証明書エラー
- `Certificate has expired` や `certificate verify failed` が出る場合: まず**システム時刻**が正しいか確認します。次に、OS、Python の `certifi`、Postman などのツールを最新版に更新し、最新のルート証明書を使えるようにしてください。
- 常に `https://` を使ってください。証明書エラーを回避するために `http://` に切り替えたり、証明書の検証を無効にしたりしないでください。
## 5\. それでも解決しない場合
[サポートに問い合わせ](https://docs.yescaptcha.com/ja/help/contact.md)てください。次の情報を添えてください: エラーメッセージの全文、使用しているエンドポイント、サーバーの所在地域、手順 1 の curl の出力。
---
# お問い合わせ
> YesCaptcha サポートへの連絡方法：WeChat、QQ、WhatsApp、LINE、Telegram @yescaptcha_official、メール yescaptcha@gmail.com。対応時間は UTC+8 9:00–21:00。
Source: https://docs.yescaptcha.com/ja/help/contact/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/help/contact/
YesCaptcha サポートの対応時間は **UTC+8（北京時間）9:00–21:00** です。返信が遅い場合はメッセージを残してください。できるだけ早く対応します。
- メール：[yescaptcha@gmail.com](mailto:yescaptcha@gmail.com)
- Telegram：[@yescaptcha\_official](https://t.me/yescaptcha_official)
QR コードを読み取って追加してください：
**WeChat**WeChat で QR コードを読み取って友だち追加すると、ユーザーグループにご招待できます
**QQ**QQ で QR コードを読み取って友だち追加
**WhatsApp**WhatsApp のカメラで QR コードを読み取って追加
**LINE**LINE の「友だち追加」から QR コードを読み取り
**[Telegram](https://t.me/yescaptcha_official)**@yescaptcha\_official
お問い合わせの際は、次の情報を添えてください：
- アカウントのメールアドレスまたはユーザー ID（`clientKey` は**送らないでください**）
- 関連する `taskId`、エラーコード、発生時刻
- 使用したタスクタイプと、利用したエンドポイント（`api.yescaptcha.com` または `cn.yescaptcha.com`）
多くの疑問は [よくある質問](https://docs.yescaptcha.com/ja/help/faq.md)、[エラーコード](https://docs.yescaptcha.com/ja/api/errors.md)、[接続とネットワークの問題](https://docs.yescaptcha.com/ja/help/troubleshooting.md) で解決できます。
---
# サービス更新履歴
> YesCaptcha のユーザーに影響する変更を日付順に記録します。新規公開・終了したタスクタイプ、課金と報告による返金のルール、同時実行数の上限、ドキュメントの移行など。2026-10 から記録しています。
Source: https://docs.yescaptcha.com/ja/changelog/ · Last verified: 2026-10-19
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/changelog/
ここでは、ユーザーに影響する変更を日付順に記録します。タスクタイプの公開と終了、課金ルール、レート制限のルールなどです。新しいものが上にあります。
## 2026-10-19
- **Cloudflare チャレンジページの「非推奨」表示を解除**: `CloudFlareTaskS2` と `CloudFlareTaskS3` のサービスを再構築しました。1 タスクあたり通常 6〜35 秒です。2 つのタイプはパラメータ、返却結果、効果が同じで、価格も変わりません（25 ポイント、20 ポイント）。プロキシは `http://`（アカウント・パスワード付き可）と、アカウント・パスワードなしの `socks5://` のみ対応します。`https://` プロキシ、ローカルアドレス、内部ネットワークのアドレスはタスク作成時に拒否されます（課金されません）。`userAgent` は Linux デスクトップ版 Chrome のものだけが使われるため、以降のリクエストには結果に含まれる `user_agent` を使ってください。`requiredCookies` を指定した場合は、すべて取得できて初めて成功になります。詳しくは [Cloudflare チャレンジページ](https://docs.yescaptcha.com/ja/tasks/cloudflare-challenge.md) を参照してください。
## 2026-10-16
- **FunCaptcha の token 型タスクは当面非推奨**: コストが高く、安定した方法がないためです。`FunCaptchaTask` は 1 タスクあたり 30 ポイントに変更しました（従来は 15 ポイント）。`FunCaptchaTaskProxyless` は引き続き認識に成功せず、失敗したタスクは自動的に返金されます。FunCaptcha を通過する必要がある場合は、[FunCaptcha 画像認識](https://docs.yescaptcha.com/ja/tasks/funcaptcha-classification.md) またはブラウザ拡張機能の利用をおすすめします。
## 2026-10-15
- **ドキュメントの移行**: ドキュメントを Confluence から本サイト（docs.yescaptcha.com）に移しました。中国語と英語で提供し、内容は中国語が優先されます。AI やプログラムから読み取りやすいよう、[llms.txt](https://docs.yescaptcha.com/llms.txt)、[OpenAPI](https://docs.yescaptcha.com/openapi.json)、各ページの Markdown 版を提供しています。
- **報告による返金を約 24 時間後の精算に変更**: 画像認識タイプで認識ミスを報告しても、即時には返金されず、約 24 時間後にまとめて精算されます。失敗率が同時期より明らかに高い場合は、同時期の失敗率に基づいて返金します。詳しくは [課金と返金](https://docs.yescaptcha.com/ja/getting-started/billing.md) を参照してください。
- **同時実行数の上限**: アカウントごと、タスクタイプごとに処理中のタスク数の集計を開始しました。上限を超えると `ERROR_THREADS_MAXIMUM` が返され、課金されず、自動一時停止の対象にも含まれません。各タイプの上限が決まり次第、[同時実行数の上限と自動一時停止](https://docs.yescaptcha.com/ja/api/rate-limits.md) で公開します。
- **公開するタスクタイプを追加**: `HCaptchaTask`、`NoCaptchaTask`、`TurnstileTask`、`RecaptchaV2EnterpriseTask`（自前のプロキシを使用）と、`FunCaptchaTaskProxylessM1`、`FunCaptchaTask`、`HCaptchaTaskProxylessM1` をドキュメントに追加しました。
- **FunCaptcha の token 型タスク**: `FunCaptchaTaskProxylessM1` と `FunCaptchaTask` は利用できます。`FunCaptchaTaskProxyless` の経路は 2026-09-10 頃から認識に成功しておらず、失敗したタスクは自動的に返金されます。
- **終了**: reCAPTCHA K1 カスタムフィンガープリントシリーズ、`FunCaptchaTaskS1`、`CloudFlareTaskS1`、`TurnstileTaskS2`、`TurnstileTaskProxylessS2`、`bCaptcha2Classification`、`GeneralClassification` のサービスを停止しました。
## 2026-10-15 より前
- **専用サーバー**のセルフサービスレンタルは終了しました。