reCAPTCHA v3 解決 API：action ごとのトークンとスコア

SolveHub API で reCAPTCHA v3 のトークンと 0.0–1.0 のスコアを action 指定で取得。スコアはプロキシの評判に依存し、minScore の保証はありません。

許可された QA 自動化とブラウザー連携向けです。テスト権限のあるサイトと業務フローでのみ使用してください。

reCAPTCHA v3 向けで、g-recaptcha-response トークンと 0.0–1.0 のスコアを返します。スコアは IP とブラウザー環境から Google が評価するため、minScore 以上の保証はありません。クリーンな住宅用プロキシを使用してください。

リクエストフィールド

外側の type と task は必須です。以下の task.* パスは task オブジェクト内にあります。フィールド名は大文字小文字を区別します。長さ制限は UTF-8 バイトです。

フィールド	型	必須	制限	説明
`type`	文字列	はい	`recaptcha_v3` 固定	プラットフォームのタスク種別。
`task`	JSON オブジェクト	はい	≤ 7 MiB	この種別のタスクパラメーター。
`task.type`	文字列	いいえ	指定時は `recaptcha_v3` 固定	旧リクエスト形式との互換用。新規は省略可。
`task.websiteURL`	HTTP(S) URL	はい	≤ 2048 バイト	reCAPTCHA v3 が動作するページの完全な URL。
`task.websiteKey`	非空文字列	はい	≤ 256 バイト	reCAPTCHA v3 の site key。
`task.action`	非空文字列	いいえ	≤ 256 バイト	サイトが期待する action（例 `login`）。既定は `verify`。
`task.minScore`	数値	いいえ	0.0–1.0	希望する最低スコア。ヒントのみです。
`task.proxyType`	文字列	はい	`http` / `https` / `socks5`	プロキシプロトコル。住宅用プロキシが必須です。
`task.proxyAddress`	非空文字列	はい	≤ 256 バイト	プロキシアドレス。
`task.proxyPort`	文字列	はい	1–5 バイト、値 1–65535	プロキシポート。引用符付きの数字文字列。
`task.proxyLogin`	非空文字列	いいえ	≤ 256 バイト	プロキシユーザー名。
`task.proxyPassword`	非空文字列	いいえ	≤ 256 バイト	プロキシパスワード。

作成リクエストの例

{
  "type": "recaptcha_v3",
  "task": {
    "websiteURL": "https://example.com/",
    "websiteKey": "6Lc_aCMTAAAAA_EXAMPLE",
    "action": "verify",
    "minScore": 0.7,
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080"
  }
}

cURL での呼び出し

例の中の Key、サイト情報、プロキシを実際の値に置き換えてください。同じ業務リクエストを再試行するときは Idempotency-Key を変えないでください。

curl -sS -X POST 'https://www.tiam.codes/v1/tasks' \
  -H 'Authorization: Bearer sh_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-recaptcha-v3-0001' \
  --data-binary @- <<'JSON'
{
  "type": "recaptcha_v3",
  "task": {
    "websiteURL": "https://example.com/",
    "websiteKey": "6Lc_aCMTAAAAA_EXAMPLE",
    "action": "verify",
    "minScore": 0.7,
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080"
  }
}
JSON

作成レスポンスと照会

作成に成功すると HTTP 202 を返し、status は通常 queued です。taskId を保存し、約 2–3 秒ごとに GET /v1/tasks/{taskId} で照会してください。この種別の処理ソフト期限は 120 秒です。超えると uncertain になる場合がありますが、受理済みタスクの結果は引き続き確認できます。新しい冪等キーで代替タスクを作らないでください。

結果フィールド

status=completed のときだけ solution を読んでください。表はよく使うフィールドで、実際のレスポンスが正となります。

フィールド	型	読み取り方
`solution.token`	文字列	`g-recaptcha-response` トークン。
`solution.solution`	文字列	`solution.token` と同じトークン。トークン結果の汎用フィールド。
`solution.score`	数値、任意	Google が返した 0.0–1.0 のスコア。
`solution.userAgent`	文字列	トークン送信時は同じ User-Agent を使用。

トークンを g-recaptcha-response として同じプロキシ出口と同じ userAgent で送信してください。スコアが低い場合はよりクリーンなプロキシに変えるか minScore を下げて再試行してください。

失敗とトラブルシューティング

minScore はヒントのみで、結果スコアを保証しません。ページの action がサイトの実際の呼び出しと一致しないとリスクチェックで拒否されます。

作成時のよくあるエラーは 400 INVALID_TASK、402 INSUFFICIENT_BALANCE、429 TASK_LIMIT_EXCEEDED、503 TYPE_UNAVAILABLE です。作成済みタスクの失敗時は TASK_FAILED または TASK_TIMEOUT、uncertain は TASK_UNCERTAIN に対応します。詳細はプラットフォーム API リファレンスを参照してください。

処理ウィンドウはタスク作成時から起算します。プラットフォームは約 90 秒後に未完了のタスクを放棄し、課金しません。