Scarnox · Blog

验证码求解 API：工作原理与调用方法

验证码求解 API 是一种通过 HTTP 调用的 Web 服务。你发送验证码的相关信息，包括任务类型、页面的 sitekey 和页面 URL，它会返回一个 token，目标网站接受该 token 作为挑战已通过的凭证。Scarnox 的接口就是这样工作的，而且是同步的，因此一次请求即可得到结果。

本指南涵盖请求、响应、错误格式，以及决定集成在生产环境中能否稳定运行的各种细节。如果你想先运行一个可用的脚本，请从使用 Python 求解 PopularCaptcha开始。

API 做什么，不做什么

你的代码在页面上找到验证码，读取其 sitekey，并将其发送给求解器。求解器返回一个 token。你的代码把该 token 写入网站表单所期望的字段中，然后提交表单。

求解器不会加载你的页面，不会点击任何东西，也不会替你提交表单。它只负责生成 token。记住这一边界，会让集成的其余部分更容易理解：会话、cookie 和请求时序都由你的代码负责。

目前唯一可用的任务类型是无代理的 PopularCaptcha，即 PopularCaptchaTaskProxyless。其他验证码类型已列入路线图。验证码类型详解列出了各类型的支持状态。

接口地址

向以下地址发送 POST 请求：

POST https://api.scarnox.com/api/tasks/create
Authorization: Bearer scarnox_YOURAPIKEY
Content-Type: application/json

请求体描述任务内容：

{
  "captcha_type": "PopularCaptchaTaskProxyless",
  "site_key": "10000000-ffff-ffff-ffff-000000000001",
  "site_url": "https://example.com/signup"
}

三个必填字段如下：

另外还有三个可选字段。proxy 的格式为 http://user:pass@host:port，用于代理类任务类型。rqdata 和 is_invisible 适用于特定的组件变体。完整的任务类型和字段说明见 API 参考文档。

同步意味着无需轮询

调用会阻塞，直到 token 准备好。你无需轮询，这个流程中也没有第二个“获取结果”的请求。请将 HTTP 客户端的超时时间设置为约 185 秒，以免较慢的求解被误判为网络故障。

在使用 requests 库的 Python 中，代码如下：

import requests

r = requests.post(
    "https://api.scarnox.com/api/tasks/create",
    headers={"Authorization": "Bearer scarnox_YOURAPIKEY"},
    json={
        "captcha_type": "PopularCaptchaTaskProxyless",
        "site_key": "10000000-ffff-ffff-ffff-000000000001",
        "site_url": "https://example.com/signup",
    },
    timeout=185,
)
data = r.json()

请从环境变量中读取密钥，而不是将其写入脚本。任何能读取源码的人都不应能够动用你的余额。

读取响应

求解成功时，返回的 errorId 为 0，token 位于 solution 中，并附带 cost 字段：

{"errorId": 0, "solution": {"token": "..."}, "cost": ...}

求解失败时，返回的 errorId 不为 0，并附带机器可读的 errorCode 和人类可读的 errorDescription：

{"errorId": 1, "errorCode": "...", "errorDescription": "..."}

每次调用都要检查响应体中的 errorId。不要因为 HTTP 请求已经完成，就认为你一定拿到了 token。最关键的规则是：只有在 errorId 为 0 时才会计费，失败的求解不收费。当前费率请查看定价页面。

Token 的有效期

PopularCaptcha 的 token 约在两分钟内过期。请在收到 token 后立即提交。不要缓存 token 以备后用，也不要提前求解，在表单提交之前很久就去获取。如果你的代码在获得 token 与提交表单之间还要执行多个步骤，请把求解操作推迟到最后一刻。

将 token 放入表单

大多数网站会从名为 h-captcha-response 的表单字段中读取 PopularCaptcha 的响应。许多网站也接受值相同的 g-recaptcha-response，因此同时发送两者是常见的稳妥做法：

requests.post("https://example.com/signup", data={
    "email": "you@example.com",
    "h-captcha-response": token,
    "g-recaptcha-response": token,
})

如果表单不接受 token，原因通常是 sitekey 或页面 URL 与组件实际所在的页面不匹配。在怀疑求解器之前，请先仔细核对这些值。

错误处理

生产环境中的集成需要养成以下几个习惯：

经得起生产环境考验的重试与错误处理指南对上述每一项都有更深入的讲解。

开始使用

注册账户，即可获得免费试用额度，无需信用卡。然后对你自己的测试页面运行上面的请求，并在将其接入任何重要的系统之前，确认表单能够接受该 token。

下一步