API リファレンス

同時実行数の上限と自動一時停止

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

すべてのユーザーの認識速度を保つため、YesCaptcha には 3 つの保護ルールがあります。アカウントごとに同時に処理中のタスク数を制限します（同時実行数の上限）。同じ clientKey が短時間にエラーを出しすぎると数分間一時停止されます（自動一時停止）。無効と判定済みのパラメータは、一定時間そのまま元のエラーを返します（無効パラメータのキャッシュ）。この 3 つのいずれも課金されません。

同時実行数の上限

アカウントごと、タスクタイプごとに、同時に処理中のタスク数を制限します。制限するのは同時実行数であり、1 分あたりのリクエスト数ではありません。

createTask を呼び出してから、その呼び出しが返るまでの間、タスクは「処理中」として数えられます。画像認識タイプは createTask の中で直接結果を返すため、同時実行数 ≈ 1 秒あたりに送信するタスク数 × 1 タスクあたりの所要時間になります。例えば、1 タスク 0.5 秒で毎秒 40 個送信すると、同時実行数は約 20 です。
同じアカウントのリクエストは合算して数えます。タスクタイプごとに別々に数えます。
上限を超えたリクエストはすぐに ERROR_THREADS_MAXIMUM を返します。レスポンスの limit が現在の上限です。課金されず、自動一時停止の対象にもなりません。
認識サーバーの処理が追いつかないときは、認識時間を最も多く使っているアカウントの、そのタスクタイプの上限が一時的に半分になり、10 分後に自動で元に戻ります。速度が制限されるだけで、アカウントが停止されることはありません。
より高い上限が必要な場合は、サポートまでお問い合わせください。各タイプの既定の上限が決まり次第、このページとサービス更新履歴で公開します。

{
  "errorId": 1,
  "errorCode": "ERROR_THREADS_MAXIMUM",
  "errorDescription": "这个账号这种任务同时处理中的请求已达上限 30。请降低并发、等已发出的请求返回后再发；超额的请求不扣点，也不会导致封禁。",
  "limit": 30
}

（例の数値はあくまでイメージです。）

推奨される対処

毎秒の送信数だけを制御するのではなく、「結果待ちのリクエスト数」をプログラム側で制限します。例えばセマフォ（Semaphore）や固定サイズのスレッドプールを使います。
ERROR_THREADS_MAXIMUM を受け取ったら、送信済みのリクエストが返るのを待ってから新しいリクエストを送るか、1〜2 秒待って再試行します。すぐにループで再試行しないでください。
大量のタスクは均等に送信し、数千、数万のタスクを一度に同時送信しないでください。

Python（asyncio）の例：

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_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 のダッシュボードで、直近 24 時間の一時停止の記録を確認できます。

{
  "errorId": 1,
  "errorCode": "ERROR_IP_BLOCKED_5MIN",
  "errorDescription": "这个 clientKey 短时间内产生了 100 次 ERROR_TASK_NOT_SUPPORTED 错误，为保护服务已暂停创建任务，182 秒后自动恢复。",
  "retryAfter": 182,
  "blockReason": "ERROR_TASK_NOT_SUPPORTED"
}

無効パラメータのキャッシュ

エラーの中にはリクエストのパラメータで決まるものがあり、同じパラメータで再送しても結果は変わりません。

これらのエラーは自動一時停止の対象にはならず、代わりにサイト全体でキャッシュされます。最初に判定されてから 2 分間キャッシュされ、1 時間以内に再度確認された場合は 10 分間キャッシュされます。キャッシュ期間中は、同じリクエスト（同じタスクタイプと websiteKey、または同じサイトのドメイン）に対して元のエラーをそのまま返し、課金されません。レスポンスには "cached": true、retryAfter（キャッシュの残り秒数）、badRequest（ヒットしたパラメータ）が含まれます。websiteKey を修正するかタスクタイプを変更すると、すぐに反映されます。

同時実行数の上限と自動一時停止の違い

	同時実行数の上限	自動一時停止
原因	同時に処理中のタスクが多すぎる	短時間にエラーリクエストが多すぎる
動作	超過した分のリクエストのみ拒否し、`ERROR_THREADS_MAXIMUM` を返す	その `clientKey` のタスク作成を一時停止し、`ERROR_IP_BLOCKED_5MIN` を返す
復旧	リクエストの処理が完了すれば新しく送信できる。一時的に半減した上限は 10 分後に復旧	時間が経過すると自動で再開
課金	されない	されない