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 秒后放弃未完成的任务且不收费。

reCAPTCHA v2 识别 API：住宅代理获取 g-recaptcha-response

请求字段

创建请求示例

cURL 调用

创建响应与查询

结果字段

失败与排查

相关文档