API 文档
三个端点,六种语言的完整代码示例。借助 Capzy 高性能求解器集群,60 秒内即可完成集成。
快速开始
POST /createTask提交验证码类型和网站参数,立即获得 taskId。
POST /getTaskResult每隔约 1 秒轮询,直到状态变为 ready。token 位于 solution 对象中。
POST /getBalance查看剩余额度。失败的求解会自动退款到这里。
https://api.capzy.ai通过请求体中的 clientKey 进行鉴权端点
/createTask创建新的验证码求解任务{
"clientKey": "capzy_...",
"task": {
"type": "AntiTurnstileTaskProxyLess",
"websiteURL": "https://example.com",
"websiteKey": "0x4AAA..."
}
}{
"errorId": 0,
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"status": "processing"
}/getTaskResult轮询任务结果{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{
"errorId": 0,
"status": "ready",
"solution": {
"token": "0.eyJhbGci..."
}
}/getBalance查询账户余额{ "clientKey": "capzy_..." }{ "errorId": 0, "balance": 9.50 }/reportScore可选:为 V3 任务回报 Google 验证后的分数,用于控制台的 V3 质量视图。每个任务只能报告一次;报告必须在求解完成后 24 小时内提交。{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"score": 0.9,
"action": "login",
"hostname": "example.com"
}{ "errorId": 0 }/reportCorrectCaptcha可选:告诉我们该求解已被目标网站接受。对于返回坐标的类型(例如 Shopee 滑块)尤其有用,这类类型由我们返回位置,由你自己的浏览器执行拖动。此报告是我们唯一的真实准确率信号。每个任务只能报告一次,须在 24 小时内提交;绝不影响价格。{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "errorId": 0 }/reportIncorrectCaptcha可选:告诉我们该求解被目标网站拒绝。与 /reportCorrectCaptcha 一起用于真实准确率追踪。每个任务只能报告一次,须在 24 小时内提交;绝不影响价格。{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "errorId": 0 }支持的任务类型
加载中…当前已启用任务类型的实时列表,按验证码服务商分组。价格和平均求解耗时根据集群遥测数据自动更新。
速率限制
限制按账户执行,汇总你名下所有 API 密钥。超出限制会返回错误码,且不消耗额度。
所有新账户的初始等级
提交支持工单并说明你的预期用量(无单独价格等级,每次求解单价不变)
并发任务你在求解队列中可同时拥有的任务数。任务从 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_MAINTENANCECapzy 正在进行计划内维护。
修复请在维护窗口结束后重试。我们会提前在状态页发布通知。
求解结果
求解器返回的结果。失败的求解会自动退款。- #
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 质量看板最有价值。
代码演练场
主流语言的完整可运行示例。复制代码,粘贴你的 API 密钥,运行即可。
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)60 秒内完成集成。
注册即送 $0.10 免费额度。无需信用卡。
获取免费 API 密钥 →