reCAPTCHA v2 解決 API：住宅プロキシで g-recaptcha-response を取得

SolveHub reCAPTCHA v2 API で g-recaptcha-response を取得：websiteURL、websiteKey、住宅プロキシを送信し、返却された User-Agent と同じ出口でトークンを送信します。

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

チェックボックスまたは不可視 reCAPTCHA v2 向けで、g-recaptcha-response（約 2 分間有効）を返します。トークンは websiteURL のドメインに束縛されるため、住宅用プロキシを使い、返却された userAgent と同じ出口からトークンを送信してください。ページに data-s がある場合は recaptchaDataSValue をそのまま渡してください。そうでないとトークンは拒否されます。

リクエストフィールド

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

フィールド	型	必須	制限	説明
`type`	文字列	はい	`recaptcha_v2` 固定	プラットフォームのタスク種別。
`task`	JSON オブジェクト	はい	≤ 7 MiB	この種別のタスクパラメーター。
`task.type`	文字列	いいえ	指定時は `recaptcha_v2` 固定	旧リクエスト形式との互換用。新規は省略可。
`task.websiteURL`	HTTP(S) URL	はい	≤ 2048 バイト	reCAPTCHA が表示されるページの完全な URL。
`task.websiteKey`	非空文字列	はい	≤ 256 バイト	ページの `data-sitekey`（anchor の `k`）。
`task.isInvisible`	ブール値	いいえ	`true` / `false`	不可視 reCAPTCHA では `true`。
`task.pageAction`	非空文字列	いいえ	≤ 512 バイト	anchor の `sa` の値（存在する場合）。
`task.recaptchaDataSValue`	非空文字列	いいえ	≤ 512 バイト	anchor の `s` の値。`data-s` があるページでは必須。
`task.apiDomain`	文字列	いいえ	`www.google.com` / `www.recaptcha.net`	reCAPTCHA へのリクエスト先ドメイン。既定は `www.google.com`。
`task.proxyType`	文字列	はい	`http` / `https` / `socks5`	プロキシプロトコル。住宅用プロキシが必須です。
`task.proxyAddress`	非空文字列	はい	≤ 256 バイト	プロキシアドレス。
`task.proxyPort`	文字列	はい	1–5 バイト、値 1–65535	プロキシポート。引用符付きの数字文字列。
`task.proxyLogin`	非空文字列	いいえ	≤ 256 バイト	プロキシユーザー名。
`task.proxyPassword`	非空文字列	いいえ	≤ 256 バイト	プロキシパスワード。

作成リクエストの例

{
  "type": "recaptcha_v2",
  "task": {
    "websiteURL": "https://example.com/login",
    "websiteKey": "6Lc_aCMTAAAAA_EXAMPLE",
    "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-v2-0001' \
  --data-binary @- <<'JSON'
{
  "type": "recaptcha_v2",
  "task": {
    "websiteURL": "https://example.com/login",
    "websiteKey": "6Lc_aCMTAAAAA_EXAMPLE",
    "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` トークン。約 2 分間有効。
`solution.solution`	文字列	`solution.token` と同じトークン。トークン結果の汎用フィールド。
`solution.userAgent`	文字列	トークン送信時は同じ User-Agent を使用。

トークンを g-recaptcha-response として対象フォームに送信し、同じプロキシ出口と同じ userAgent でリクエストを完了してください。

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

リスクチェックを通る住宅用プロキシを使用してください。データセンターのプロキシは低スコアまたは拒否になります。data-s のあるページで recaptchaDataSValue が欠けるとトークンは拒否されます。

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

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