跳到主要内容

API 文档

三个端点,六种语言的完整代码示例。借助 Capzy 高性能求解器集群,60 秒内即可完成集成。

快速开始

第 1 步
POST /createTask

提交验证码类型和网站参数,立即获得 taskId。

第 2 步
POST /getTaskResult

每隔约 1 秒轮询,直到状态变为 ready。token 位于 solution 对象中。

第 3 步
POST /getBalance

查看剩余额度。失败的求解会自动退款到这里。

基础 URLhttps://api.capzy.ai通过请求体中的 clientKey 进行鉴权

端点

POST/createTask创建新的验证码求解任务
请求
{
  "clientKey": "capzy_...",
  "task": {
    "type": "AntiTurnstileTaskProxyLess",
    "websiteURL": "https://example.com",
    "websiteKey": "0x4AAA..."
  }
}
响应
{
  "errorId": 0,
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "status": "processing"
}
POST/getTaskResult轮询任务结果
请求
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
响应
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "0.eyJhbGci..."
  }
}
POST/getBalance查询账户余额
请求
{ "clientKey": "capzy_..." }
响应
{ "errorId": 0, "balance": 9.50 }
POST/reportScore可选:为 V3 任务回报 Google 验证后的分数,用于控制台的 V3 质量视图。每个任务只能报告一次;报告必须在求解完成后 24 小时内提交。
请求
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "score": 0.9,
  "action": "login",
  "hostname": "example.com"
}
响应
{ "errorId": 0 }
POST/reportCorrectCaptcha可选:告诉我们该求解已被目标网站接受。对于返回坐标的类型(例如 Shopee 滑块)尤其有用,这类类型由我们返回位置,由你自己的浏览器执行拖动。此报告是我们唯一的真实准确率信号。每个任务只能报告一次,须在 24 小时内提交;绝不影响价格。
请求
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
响应
{ "errorId": 0 }
POST/reportIncorrectCaptcha可选:告诉我们该求解被目标网站拒绝。与 /reportCorrectCaptcha 一起用于真实准确率追踪。每个任务只能报告一次,须在 24 小时内提交;绝不影响价格。
请求
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
响应
{ "errorId": 0 }

支持的任务类型

加载中…

当前已启用任务类型的实时列表,按验证码服务商分组。价格和平均求解耗时根据集群遥测数据自动更新。

正在加载任务类型…

速率限制

限制按账户执行,汇总你名下所有 API 密钥。超出限制会返回错误码,且不消耗额度。

默认
30 并发 · 每秒 30 次请求

所有新账户的初始等级

更高并发
300+ 并发 · 每秒 100+ 次请求

提交支持工单并说明你的预期用量(无单独价格等级,每次求解单价不变)

并发任务

你在求解队列中可同时拥有的任务数。任务从 createTask 开始计入上限,直到完成(成功、失败或超时)。

速率限制

你每秒可调用 createTask 的次数。滑动窗口,按账户执行。超出速率会返回 ERROR_RATE_LIMITED,且不扣除额度。

错误码

/createTask / /getTaskResult 返回的所有错误及修复方法。失败的求解会自动退款:额度立即返还到你的余额。

身份验证

与你的 API 密钥或 IP 相关的问题。
  • ERROR_KEY_DOES_NOT_EXIST

    无法识别你的 API 密钥。

    修复请在“控制台 → API 密钥”中仔细核对该值。密钥以 `capzy_` 开头。轮换后的旧密钥会立即失效。

    #
  • ERROR_IP_NOT_ALLOWED

    你的请求 IP 不在该 API 密钥的白名单中。

    修复在“控制台 → API 密钥”中将你的 IP 添加到该密钥的白名单,如果不需要 IP 绑定,也可以完全移除白名单。

    #
  • ERROR_IP_BLOCKED

    你的 IP 因发送过多无效请求而被暂时封禁。

    修复10 分钟内发送 100 次以上无效请求的 IP 会被封禁(逐级加重)。请修复导致无效请求的问题,然后等待。封禁会根据等级在 1 分钟到 24 小时后自动解除。

    #

参数校验

任务参数错误,或与 sitekey 的类型不符。
  • ERROR_INVALID_PARAMS

    请求体格式错误或缺少必填字段。

    修复检查 `clientKey` 是否位于顶层,且 `task` 包含 `type` 以及所需的标识符(websiteURL/websiteKey/captchaId 等)。各类型的必填参数请参见“任务类型”部分。

    #
  • ERROR_BAD_SITEKEY

    该 `websiteKey` 未在我们能识别的任何验证码服务商处注册。

    修复请确保从目标页面复制了完整的 sitekey(查找 `data-sitekey`、`sitekey:`,或 `grecaptcha.render` / `hcaptcha.render` 中的参数)。

    #
  • ERROR_TASK_NOT_SUPPORTED

    你提交的任务 `type` 不是 Capzy 当前支持的验证码类型。

    修复完整的已启用列表请参见下方的“任务类型”部分。如果你需要的验证码不在列表中,请提交工单,我们会优先处理。

    #
  • ERROR_WRONG_TASK_TYPE

    任务类型与该 sitekey 的实际服务商不匹配。

    修复我们会根据真实服务商预检 sitekey。错误响应中包含 `recommended` 字段:请切换到该任务类型。(不扣除额度。)

    #
  • ERROR_PROXY_REQUIRED

    此验证码与 IP 绑定:其 token 与求解时使用的 IP 相关联。

    修复切换到 `*Task` 版本(而非 `*TaskProxyLess`),并传入与你提交 token 时所用 IP 一致的 `proxyAddress`。适用于:Cloudflare Challenge、CaptchaFox、AWS WAF、DataDome、PerimeterX、Kasada、Akamai、Imperva。

    #
  • ERROR_NO_PROXY

    此任务类型需要代理字段,但请求中缺失。

    修复在任务体中包含 `proxyType`、`proxyAddress`、`proxyPort`(以及可选的 `proxyLogin`/`proxyPassword`/`userAgent`)。

    #
  • ERROR_PROXY_CONNECT_REFUSED

    你提供的代理拒绝了连接。

    修复检查代理凭据、主机是否可达,以及该 IP 是否在线。可先在你自己的机器上测试同一代理,以排查服务商问题。

    #

速率限制

并发 / 每秒 / 退款比例上限。
  • ERROR_MAX_TASKS_REACHED

    你已达到账户等级的并发任务上限。

    修复请等待进行中的任务完成后再提交更多任务。默认 Regular 等级为 30 个并发;如需升级请联系客服。

    #
  • ERROR_RATE_LIMITED

    你提交 /createTask 的速度超过了速率限制。

    修复请放慢速度后重试。默认 Regular 等级为每秒 30 次请求(滑动窗口)。超出速率不会消耗额度。

    #
  • ERROR_NO_SLOT_AVAILABLE

    集群容量暂时饱和。

    修复请几秒后重试(这是暂时性的)。如果持续数分钟,请查看 status.capzy.ai。

    #
  • ERROR_SYSTEM_MAINTENANCE

    Capzy 正在进行计划内维护。

    修复请在维护窗口结束后重试。我们会提前在状态页发布通知。

    #

求解结果

求解器返回的结果。失败的求解会自动退款。
  • ERROR_TIMEOUT

    任务未在该类型的超时上限内完成。

    修复已自动退款,不收费。大多数超时是暂时性的。如果某个验证码持续超时,请提交工单并附上任务 UUID。

    #
  • ERROR_CAPTCHA_UNSOLVABLE

    求解器在此挑战上已用尽重试次数。

    修复已自动退款,不收费。常见原因:sitekey 已过期、websiteURL 与嵌入域名不匹配、目标网站已停用该验证码。

    #
  • ERROR_NULL_RESULT

    求解器已完成,但未返回 token。

    修复已自动退款。通常表示目标网站在求解过程中移除了验证码。请重试;如果问题持续,请提交工单。

    #
  • ERROR_INTERNAL

    求解流程内部发生意外错误。

    修复已自动退款。请重试(这类错误很少见)。如果你频繁连续遇到,请提交工单并附上任务 UUID。

    #
  • ERROR_ZERO_BALANCE

    账户余额不足以支付任务费用。

    修复在“控制台 → 账单”中充值。失败的求解会自动退款,你只需为成功的 token 付费。

    #

分数报告

/reportScore 特有的错误(V3 质量反馈)。
  • ERROR_TASK_NOT_FOUND

    /reportScore:该 taskId 不属于你的账户,或已被清除。

    修复分数报告必须引用你拥有的任务,并且必须在求解完成后 24 小时内提交。

    #
  • ERROR_TASK_NOT_READY

    /reportScore:该任务仍在处理中或已失败。

    修复只有 `ready` 状态的任务才能报告分数。请等待 /getTaskResult 返回 ready 后再报告。

    #
  • ERROR_REPORT_TOO_LATE

    /reportScore:距求解完成已超过 24 小时。

    修复请在调用 siteverify 后的几分钟内报告分数。此时的数据对我们的 V3 质量看板最有价值。

    #
06

代码演练场

主流语言的完整可运行示例。复制代码,粘贴你的 API 密钥,运行即可。

solve.py
import requests, time

API = "https://api.capzy.ai"
KEY = "capzy_your_key_here"

# Create task
task = requests.post(f"{API}/createTask", json={
    "clientKey": KEY,
    "task": {
        "type": "AntiTurnstileTaskProxyLess",
        "websiteURL": "https://example.com",
        "websiteKey": "0x4AAA..."
    }
}).json()

task_id = task["taskId"]

# Poll for result
while True:
    result = requests.post(f"{API}/getTaskResult", json={
        "clientKey": KEY,
        "taskId": task_id
    }).json()

    if result["status"] == "ready":
        token = result["solution"]["token"]
        print(f"Solved: {token[:50]}...")
        break
    elif result["status"] == "failed":
        print(f"Failed: {result.get('errorDescription')}")
        break

    time.sleep(1)
输出预览成功(200 OK)
{ "errorId": 0, "status": "ready", "solution": { "token": "0.eyJhbGci..." } }

60 秒内完成集成。

注册即送 $0.10 免费额度。无需信用卡。

获取免费 API 密钥 →