通过 getToken 解决 reCAPTCHA：一次请求，无需轮询

简要说明

• CapSolver 的 getToken 端点可以在一次请求中返回支持的 reCAPTCHA 结果。
• 向 https://api.capsolver.com/getToken 发送 clientKey 和支持的任务对象。
• 为您的 reCAPTCHA 变体选择任务类型，并提供相应的页面、公开站点密钥和所需上下文。
• 在检查 API 结果后读取 solution.gRecaptchaResponse；成功的 HTTP 交换本身是不够的。
• 返回的令牌仍需要您拥有应用程序的正常验证。一次请求并不意味着即时完成或保证被接受。
• 下面的 cURL 请求是针对本地 HTTP 模拟器进行测试的。没有进行实时求解。

传统的 CAPTCHA 求解集成会创建一个任务，然后请求其结果。如果您正在集成支持的 reCAPTCHA 任务并希望直接响应，CapSolver 的 getToken 端点提供了另一种记录的请求模式。

实际区别在于客户端：提交任务并等待 HTTP 响应中的结果。您不需要为此流程编写 getTaskResult 轮询循环。本指南将介绍任务字段、JSON 文件和 cURL 命令、返回的令牌以及您的应用程序在接受它之前需要的检查。

什么是 getToken API？

getToken API 是其文档中列出的 reCAPTCHA 任务类型的直接结果端点。API 端点 是特定 API 操作的地址；使用正确的路径会选择此请求模式。

官方 getToken 文档 列出了支持的 reCAPTCHA v2 和 v3 任务变体，包括相应的企业版和代理选项。不要从端点的通用名称中推断出对 AWS WAF、Turnstile 或图像到文本识别的支持。

该方法改变了结果检索方式，而不是挑战参数的含义。通过直接端点发送的错误公开站点密钥或任务类型不匹配仍然错误。首先确认 CAPTCHA 家族，然后选择记录的任务变体。

一些 createTask 任务家族直接返回结果。比较并不意味着每个 createTask 调用都需要轮询。

第1步：确定 reCAPTCHA 任务和密钥

在构建请求之前，确定您拥有页面上的实际 reCAPTCHA 集成。下面的示例使用 ReCaptchaV3TaskProxyLess，因此其字段必须描述 v3 集成。

保持三个关键角色分开。CapSolver API 密钥授权求解请求。reCAPTCHA 公开站点密钥标识页面集成。站点所有者的验证密钥属于应用程序的服务器；它不是此请求中的 clientKey 或 websiteKey。

对于 v3，检查预期的操作以及公开密钥。reCAPTCHA v3 任务文档 解释了任务字段，包括 pageAction。下面的示例操作 submit 是您拥有的表单实际使用的操作的占位符。

Google 的 reCAPTCHA v3 文档 描述了基于操作的评估。不同操作的令牌不应被视为对预期表单的成功测试。保持请求的操作和后端预期的操作一致。

如果页面使用 v2 或企业版，请选择其文档中的任务类型和字段，而不是仅更改集成的标题。在没有检查其要求的情况下，避免将 v3 操作复制到其他任务中。

第2步：保存记录的 JSON 请求

将以下 JSON 保存为 request.json。其封装遵循 getToken 文档，任务字段遵循 v3 指南。这些是示例值；在进行实时检查时，请替换为您的设置。

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "ReCaptchaV3TaskProxyLess",
    "websiteURL": "https://your-owned-test.example/form",
    "websiteKey": "YOUR_PUBLIC_SITE_KEY",
    "pageAction": "submit"
  }
}

在联系实时端点之前，替换每个占位符。示例域故意标识一个拥有测试页面，并不是有效的 CAPTCHA 目标。公开密钥和操作必须来自该页面的配置集成。

JSON 文件使有效负载易于检查，而无需长命令行。一旦包含真实凭据，请限制对该文件的访问，并将其排除在源代码控制之外。在将此请求移入应用程序时，请使用适当的密钥管理方法。

无代理任务名称描述了提供商的任务变体。它并不消除对正确页面上下文的需求，也不意味着每个挑战配置使用相同的参数。使用任务文档作为字段参考。

第3步：使用 cURL 发送一次请求

从包含 request.json 的目录运行此命令。其标志和有效负载已针对本地 HTTP 模拟器进行测试，但实时端点仍需要您的求解凭据和拥有页面参数：

curl --silent --show-error --connect-timeout 10 --max-time 90 \
  --json @request.json \
  https://api.capsolver.com/getToken

该命令使用 cURL 的 JSON 请求选项将文件作为正文发送。官方 cURL JSON 文档 解释了该选项及其请求头。请使用支持 --json 的 cURL 版本。

连接和总超时值是此示例的本地选择。它们不是提供商的服务级承诺。端点可能在求解任务时保持请求，因此直接响应并不等同于即时响应。

检查 HTTP 结果和 JSON 内容。该命令显示响应正文和传输错误；它不是完整的应用程序错误处理程序。cURL 可能在返回的 JSON 描述提供者错误时完成 HTTP 交换。应用程序应根据返回的字段进行分支，而不是在终端输出中搜索类似令牌的字符串。

不要将轮询循环附加到此命令作为默认下一步。所选流程专门用于直接返回其结果。如果您的应用程序需要带有单独结果检索的任务跟踪，请从一开始就选择并实现记录的 createTask 流程。

使用您的 CapSolver 奖励代码

立即提升您的自动化预算！
在充值 CapSolver 账户时使用奖励代码 CAP26，每次充值可获得额外 5% 奖励 —— 无限制。
现在在您的 CapSolver 仪表板 中兑换

第4步：读取直接令牌响应

在确认结果报告成功和就绪后，仅读取 solution.gRecaptchaResponse。以下响应结构是示例；令牌值是占位符，不是实时求解返回的令牌。

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "ILLUSTRATIVE_TOKEN_VALUE"
  }
}

重要值是错误指示符、就绪状态和非空结果字段。不要将响应对象、任务标识符或 HTTP 成功状态与可用令牌互换。也可能出现可选字段；仅保留您的集成所需的字段。

在提供者失败时，检查 API 错误参考 中描述的错误代码和说明。保留足够的信息以区分无效参数、账户问题或传输失败，同时从常规日志中排除凭证和令牌。

直接端点简化了客户端状态机，但连接仍然是操作的一部分。如果客户端超时或丢失响应，其结果可能是不确定的。请求可能在本地错误发生前已到达提供者。除非 API 明确记录该行为，否则不要将立即的第二次提交描述为恢复第一个任务。

第5步：在您的拥有应用程序中验证令牌

返回的令牌必须通过应用程序的正常验证，操作才算成功。求解结果和应用程序接受是两个独立事件。

Google 的 服务器端验证文档 指出响应令牌在两分钟后过期，并且只能验证一次。在预期操作接近时获取令牌，并避免通过验证端点重复测试同一令牌。

对于标准验证流程，站点所有者的密钥留在后端。检查与您的集成相关的响应属性，包括预期的主机名，以及对于 v3 的操作和评分策略。企业应用程序应使用其相应的验证或评估集成，而不是假设标准示例涵盖所有变体。

考虑一个具有 submit 操作的拥有表单。一个有用的测试首先确认请求的任务描述该操作，然后将返回的令牌通过表单的正常后端路径发送，并最终断言预期的测试操作被接受。在终端中打印的令牌字符串仅证明收到了一个字符串。

关于评分解释，请参阅单独的 reCAPTCHA v3 评分指南。切换检索端点不会建立特定评分或移除后端的接受规则。

何时应使用 getToken 而不是轮询？

当任务变体受支持且客户端可以在等待结果时保持请求打开时，使用 getToken。这适用于小型直接集成，其中下一步立即使用返回的令牌。

当您的应用程序特别需要单独的任务创建和结果检索时，请使用 createTask API 及其记录的结果流程。例如，一个在步骤之间持久化任务标识符的工作者可能围绕该模式组织。

根据客户端的生命周期进行选择，而不是假设一个端点普遍更快。直接请求移除了客户端轮询代码，但仅此并不证明较低的求解延迟。后台工作者可能还需要单个同步 HTTP 调用未提供的控制。

不要仅为了适应首选端点而切换 CAPTCHA 家族。页面决定了挑战类型。如果家族未列出用于 getToken，请遵循该家族的文档 API。

示例的测试确立了什么？

cURL 命令是在仅替换端点的本地 HTTP 模拟器上执行的。该模拟器检查了 POST 路径、JSON 内容类型和精确解析的有效负载，然后返回了提供的就绪响应。这验证了基于文件的命令和直接响应处理。

没有使用实际的求解密钥、付费任务或受 reCAPTCHA 保护的表单。模拟器令牌对任何应用程序均无效。实时集成仍需要实际的站点密钥、操作、求解凭据和拥有应用程序的验证结果。

在超越单个测试之前，记录哪个任务变体和字段与拥有页面配合使用。如果测试失败，请确定失败是在任务提交、结果检索、令牌验证还是最终应用程序操作期间发生。这些区别为您提供了一个具体的起点，而无需添加不必要的轮询循环。

使用一个支持的 reCAPTCHA 任务尝试 CapSolver 完成实时验证步骤。在将经过验证的请求从 cURL 移动到您的应用程序时，保持相同的请求字段和接受检查。

常见问题

Q: getToken 是否需要 getTaskResult？

此处描述的直接流程在 getToken 响应中返回结果，因此客户端不需要轮询 getTaskResult。带有单独检索的任务跟踪属于相应的 createTask 集成。

Q: getToken 能解决任何 CAPTCHA 类型吗？

仅使用其文档中列出的任务类型。记录的 reCAPTCHA 变体不意味着支持无关家族，如 AWS WAF 或图像识别。

Q: getToken 是否比 createTask 更快？

本指南不建立延迟优势。可观察的设计差异是客户端等待直接结果而不是实现单独的检索循环。

Q: websiteKey 是私有验证密钥吗？

不是。它是页面集成的公开站点密钥。站点的验证密钥留在后端，而 clientKey 是求解服务凭据。

Q: 为什么返回的令牌可能无法通过验证？

检查过期时间、先前使用、预期页面上下文、操作和应用程序的验证响应。从求解器接收令牌并不保证应用程序会接受它。

Q: 示例令牌是否由实时求解生成？

不。显示的响应是示例，命令已通过本地 HTTP 模拟器进行检查。使用您的求解密钥和拥有应用程序完成单独的实时测试。