将 2Captcha reCAPTCHA 集成迁移到 solvethree
这不仅仅是更改端点。将 clientKey/task 封装结构替换为使用 Bearer 密钥验证的平铺请求，在 solvethree 中配置目标站点，并提供代理。将现有 2Captcha 任务 ID 与新的 solvethree 任务分开管理。
本页内容
检查要迁移的任务
本迁移指南涵盖通过 2Captcha API v2 使用的 reCAPTCHA v3 Enterprise，不涉及旧版 in.php/res.php API。另外，2Captcha 的 API 版本并不是验证码版本：solvethree 不支持 reCAPTCHA v2。
原始请求使用 2Captcha createTask 文档所述的封装结构：凭据位于提供商特定的任务对象之外。
{
"clientKey": "TWO_CAPTCHA_API_KEY",
"task": {
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://accounts.example.com/login",
"websiteKey": "PUBLIC_SITE_KEY",
"minScore": 0.7,
"pageAction": "login",
"isEnterprise": true
}
}不要将此对象原样带入新 API。尤其是，下面的 solvethree 请求不应包含无代理任务类型和 minScore。
配置站点，然后替换请求
首先，在 solvethree 控制台中配置目标站点。工作区必须有处于启用状态的站点配置，才能为该主机名处理求解请求。发送主机名和 action 不会创建站点配置。
使用工作区 API 密钥，通过 Authorization: Bearer 向 https://api.solvethree.com 的 POST /v1/tasks 创建新任务。请将该密钥保存在服务器端。任务创建规范 使用扁平 JSON 请求体，而不是嵌套的 task 对象。
| 2Captcha API v2 输入 | solvethree 替代方式 |
|---|---|
| clientKey | 将工作区 API 密钥放在 Authorization 请求头中，而不是 JSON 请求体中。 |
| task 包装层 | 移除该层；在顶层发送任务字段。 |
| type: RecaptchaV3TaskProxyless | 省略 type。必须提供 proxy 或 proxyCandidates 中的一个，且只能提供一个。 |
| websiteURL | 使用 site，且仅填写主机名：accounts.example.com。不要发送 url。 |
| websiteKey | 在控制台中配置目标站点，而不是将此字段复制到任务中。 |
| pageAction | 使用 action，并填写目标的操作值，例如 login。 |
| isEnterprise | 省略此字段；recaptchaType 默认为 enterprise-v3。 |
| minScore | 省略此字段；不要将其复制到 solvethree 请求中。 |
{
"site": "accounts.example.com",
"action": "login",
"proxy": "http://user:[email protected]:8080",
"requestId": "example_login_001"
}将示例中的主机名、action 和代理替换为目标对应的值。在发送请求前选定 requestId，并保留它以便在超时后恢复任务；每个新的逻辑任务都应使用新值。
示例使用一个代理。也可以使用 proxyCandidates，它最多接受十二个不同的 HTTP 或 HTTPS 代理 URL，且不能包含路径、查询参数或片段。两个字段只能发送其中一个，不能同时发送。候选代理让服务能够尝试其他出口，但不保证一定有可用的代理。
替换轮询和超时处理逻辑
对于仍在处理中的 2Captcha 任务，请继续使用其 getTaskResult 流程，沿用其凭据、任务 ID 和文档规定的轮询策略。其他服务的任务 ID 不是 solvethree 任务句柄。
- 1.
处理创建响应
在读取成功响应数据前，先检查 HTTP 响应是否成功。reCAPTCHA 创建请求默认最多等待 15 秒，但可能返回尚未进入终态的任务。如果任务已经是 ready 状态，直接使用解答，无需启动轮询循环。
- 2.
仅轮询未完成的任务
使用 GET /v1/tasks/:id 获取 solvethree 任务。将原先对 processing 的检查改为检查 pending 和 solving；这两种状态都表示任务尚未完成。只有 ready 状态才包含可用的解答。
- 3.
在 URL 中设置等待时间
GET 轮询默认不等待。要使用长轮询，请在 URL 查询参数中设置 waitMs，最大为 15000，而不是将其作为 JSON 字段发送。HTTP 客户端超时时间应涵盖请求的等待时间以及网络开销。
- 4.
在 failed 状态下停止
读取 errorCode 和 error，然后停止轮询该任务。求解失败会退款。site-unreachable 等错误需要排查；不要认定所有失败都是余额问题，也不要不断重新提交未经修改的无效输入。
连接超时并不证明创建失败。如果已收到任务 ID，请获取该任务。如果没有收到，请使用相同的 requestId 重复发送相同请求，以恢复已有任务，而不是创建另一次求解。复用该 requestId 时更改任务输入会导致冲突。
在适配器中区分 HTTP 错误与任务终态失败。轮询规范和失败处理介绍了这两种处理路径；不要复用 2Captcha 的错误响应解析器。
更新令牌提取和提交逻辑
将旧适配器中的令牌查找逻辑替换为读取 ready 状态的 solvethree 任务中的 solution.token。将该令牌提交到目标预期接收 reCAPTCHA 值的位置，而不是提交任务 ID 或整个 solution 对象。
提交令牌时，使用返回的 userAgent 和 secChUa 浏览器身份信息，并使用求解成功时所用的代理。如果提供了 proxyCandidates，请使用求解成功时所用的代理，而不是另选一个候选代理进行提交。
任务处于 ready 状态表示已生成解答，并不表示网站已接受你的应用请求。如果目标拒绝请求，请先检查发出的令牌、action、目标 URL、代理和浏览器身份信息，再付费进行下一次求解。
来源与 API 参考
运行您的第一个任务。
使用 $5 工作区额度开始体验。