PRODUCT TEST WORKSPACE

reCAPTCHA Enterprise

Captcha verification product

RECAPTCHA_ENTERPRISE

01 / CREATE

创建任务

编辑器默认填入必填字段及一组条件字段。可选字段在下方文档列出,也可一键填入。

02 / REQUEST

请求预览

POST /api/validator/create.cgi
{
  "productCode" : "RECAPTCHA_ENTERPRISE",
  "adapter" : {
    "websiteURL" : "https://example.com/register",
    "websiteKey" : "YOUR_WEBSITEKEY"
  }
}

03 / RESULT

响应示例

EXAMPLE
Task ID —
{
  "code" : 0,
  "msg" : "操作成功",
  "data" : {
    "taskId" : "11111111-1111-4111-8111-111111111111",
    "productCode" : "RECAPTCHA_ENTERPRISE",
    "state" : "SUCCEEDED",
    "solution" : {
      "gRecaptchaResponse" : "EXAMPLE_GRECAPTCHARESPONSE",
      "token" : "EXAMPLE_TOKEN"
    }
  }
}

响应仅为示例,不是真实任务结果。提交前请替换请求中的所有示例值。

状态为 SUCCEEDED 后读取 data.solution。答案字段因产品而异,其他状态可能返回空对象。

04 / API REFERENCE

reCAPTCHA Enterprise · API

创建和查询任务时,将 API Key 统一放在 HTTP apiKey 请求头中;JSON 请求体只包含业务参数。

Content-Type: application/json
apiKey: YOUR_API_KEY

请求示例

POST /api/validator/create.cgi · JSONC
{
  "productCode": "RECAPTCHA_ENTERPRISE", // 产品编码,必须与 adapter 参数匹配。
  "adapter": { // 产品专属参数对象。
    "websiteURL": "https://example.com/register", // 从实际目标页面、控件配置或接入协议读取,确认具体产品与版本;不能替换为占位值或其他网站的 key。
    "websiteKey": "YOUR_WEBSITEKEY", // 从实际目标页面、控件配置或接入协议读取,确认具体产品与版本;不能替换为占位值或其他网站的 key。
    "pageAction": "YOUR_PAGEACTION", // 取自目标 execute 配置的实际 v3 动作。v2 为历史兼容保留此字段,但它不能替代 data-s 或 enterprisePayload.s,也不能用于选择产品版本。
    "apiDomain": "YOUR_APIDOMAIN", // 从实际目标页面、控件配置或接入协议读取,确认具体产品与版本;不能替换为占位值或其他网站的 key。
    "isEnterprise": false, // RECAPTCHA_V3_ENTERPRISE 上游标记始终为 true,旧请求传 false 也不会降级;RECAPTCHA_V3 保持原有选填标记行为。Enterprise 控件应选明确的 v2 Enterprise 产品,此标记不能补足会话参数。
    "minScore": 0.3, // 根据实际题目及产品字段含义设置。这些是识别选项,不能随意猜测来修复失败请求。
    "userAgent": "YOUR_BROWSER_USER_AGENT", // 读取取得当前挑战时实际使用的 User-Agent;产品要求一致时保持不变。
    "appId": "YOUR_APPID", // 从实际目标页面、控件配置或接入协议读取,确认具体产品与版本;不能替换为占位值或其他网站的 key。
    "isInvisible": false, // 从实际目标页面、控件配置或接入协议读取,确认具体产品与版本;不能替换为占位值或其他网站的 key。
    "cookies": "challenge_cookie=CURRENT_VALUE", // v2/v2 Enterprise 可选的当前挑战 Cookie 请求头字符串,格式为 key=value; key2=value2,取自对应目标上下文;不需要时省略。v3 不公开此字段。
    "proxyType": "http", // v2/v2 Enterprise 可选代理协议:http、socks4 或 socks5。提供任一代理字段时,proxyType、proxyAddress、proxyPort 必须齐全;全部省略保留无代理模式。当前 v3 没有已确认的代理任务。
    "proxyAddress": "YOUR_PROXY_HOST", // 可达的代理主机名或 IP,不含协议、端口及认证信息。目标要求 IP 绑定时,识别端与目标浏览器必须使用相同的实际出口;仅给浏览器设置代理并不足够。
    "proxyPort": 8080, // 代理 TCP 端口,1 至 65535 的整数;仅在提供代理参数时必填。
    "proxyLogin": "YOUR_PROXYLOGIN", // 调用方已配置代理的可选认证用户名,不要编造凭据。
    "proxyPassword": "YOUR_PROXYPASSWORD", // 同一个已配置代理的可选认证密码。
    "enterprisePayload": { // 当前 grecaptcha.enterprise.render 配置的可选附加 JSON 对象,存在 s 字符串时一并携带,保持与挑战匹配。Enterprise v2 不使用 recaptchaDataSValue;此字段不是已确认的 v3 参数。
      "s": "CURRENT_ENTERPRISE_S_VALUE"
    }
  }
}

请求头: apiKey: YOUR_API_KEY

注释用于说明字段,复制后得到不含注释的标准 JSON。

响应示例

POST /api/validator/query.cgi · JSONC
{
  "code": 0, // 业务返回码,0 表示成功,其他值表示错误。
  "msg": "操作成功", // 结果说明,成功时可能为空。
  "data": { // 响应数据,接口报错时可能为 null。
    "taskId": "11111111-1111-4111-8111-111111111111", // 创建任务返回的任务 ID。
    "productCode": "RECAPTCHA_ENTERPRISE", // 产品编码,必须与 adapter 参数匹配。
    "state": "SUCCEEDED", // 任务状态:CREATED、SUBMITTING、PROCESSING、SUCCEEDED、FAILED、EXPIRED。
    "solution": { // SUCCEEDED 时的产品答案;处理中或失败时为空对象。
      "gRecaptchaResponse": "EXAMPLE_GRECAPTCHARESPONSE", // 提交到目标网站的验证令牌。
      "token": "EXAMPLE_TOKEN" // 提交到目标网站的验证令牌。
    }
  }
}

创建任务返回任务 ID 和初始状态。下方为查询接口的完成结果,也可通过 WebSocket 接收答案。

请求参数说明

字段类型必填说明
productCodestring是产品编码,必须与 adapter 参数匹配。
adapterobject是产品专属参数对象。
adapter.websiteURLstring是从实际目标页面、控件配置或接入协议读取,确认具体产品与版本;不能替换为占位值或其他网站的 key。
adapter.websiteKeystring是从实际目标页面、控件配置或接入协议读取,确认具体产品与版本;不能替换为占位值或其他网站的 key。
adapter.pageActionstring否取自目标 execute 配置的实际 v3 动作。v2 为历史兼容保留此字段,但它不能替代 data-s 或 enterprisePayload.s,也不能用于选择产品版本。
adapter.apiDomainstring否从实际目标页面、控件配置或接入协议读取,确认具体产品与版本;不能替换为占位值或其他网站的 key。
adapter.isEnterpriseboolean否RECAPTCHA_V3_ENTERPRISE 上游标记始终为 true,旧请求传 false 也不会降级;RECAPTCHA_V3 保持原有选填标记行为。Enterprise 控件应选明确的 v2 Enterprise 产品,此标记不能补足会话参数。
adapter.minScorenumber否根据实际题目及产品字段含义设置。这些是识别选项,不能随意猜测来修复失败请求。
adapter.userAgentstring否读取取得当前挑战时实际使用的 User-Agent;产品要求一致时保持不变。
adapter.appIdstring否从实际目标页面、控件配置或接入协议读取,确认具体产品与版本;不能替换为占位值或其他网站的 key。
adapter.isInvisibleboolean否从实际目标页面、控件配置或接入协议读取,确认具体产品与版本;不能替换为占位值或其他网站的 key。
adapter.cookiesstring否v2/v2 Enterprise 可选的当前挑战 Cookie 请求头字符串,格式为 key=value; key2=value2,取自对应目标上下文;不需要时省略。v3 不公开此字段。
adapter.proxyTypestring否v2/v2 Enterprise 可选代理协议:http、socks4 或 socks5。提供任一代理字段时,proxyType、proxyAddress、proxyPort 必须齐全;全部省略保留无代理模式。当前 v3 没有已确认的代理任务。
adapter.proxyAddressstring否可达的代理主机名或 IP,不含协议、端口及认证信息。目标要求 IP 绑定时,识别端与目标浏览器必须使用相同的实际出口;仅给浏览器设置代理并不足够。
adapter.proxyPortinteger否代理 TCP 端口,1 至 65535 的整数;仅在提供代理参数时必填。
adapter.proxyLoginstring否调用方已配置代理的可选认证用户名,不要编造凭据。
adapter.proxyPasswordstring否同一个已配置代理的可选认证密码。
adapter.enterprisePayloadobject否当前 grecaptcha.enterprise.render 配置的可选附加 JSON 对象,存在 s 字符串时一并携带,保持与挑战匹配。Enterprise v2 不使用 recaptchaDataSValue;此字段不是已确认的 v3 参数。

响应参数说明

字段类型说明
codeinteger业务返回码,0 表示成功,其他值表示错误。
msgstring结果说明,成功时可能为空。
dataobject | null响应数据,接口报错时可能为 null。
data.taskIdstring创建任务返回的任务 ID。
data.productCodestring产品编码,必须与 adapter 参数匹配。
data.statestring任务状态:CREATED、SUBMITTING、PROCESSING、SUCCEEDED、FAILED、EXPIRED。
data.solutionobjectSUCCEEDED 时的产品答案;处理中或失败时为空对象。
data.failureobject | omitted仅 FAILED 或 EXPIRED 返回的公开诊断,不含上游原始消息;按失败处理指引操作。
data.failure.codestring失败编码
data.failure.nextActionstring下一步
data.solution.gRecaptchaResponsestring提交到目标网站的验证令牌。
data.solution.tokenstring提交到目标网站的验证令牌。

响应

HTTP 业务响应包含 code、msg 和 data;code 为 0 表示成功。WebSocket 使用独立的消息结构。

-1317
API Key 无效。
-1100 / -1101
请求参数错误或缺失。
-1401
余额不足,请充值后再创建任务
-1400 / -1001
系统或创建任务错误。
API文档