基础
- 基础 URL
https://unlock-api.com- API 密钥
- 32 个字符，在账户页面上。以 clientKey（JSON）或 key（in.php、res.php）发送。
- 格式
- JSON 方法：POST，请求体为 JSON。in.php 和 res.php：GET 或 POST 表单字段；加上 json=1 可获得 JSON 回复。
- 限制
- 每个账户每分钟 1,200 次请求，包含结果查询。创建任务后等待约 5 秒，然后每 5 秒查询一次。
- 时间限制
- 5 分钟内未完成的任务会以 ERROR_CAPTCHA_UNSOLVABLE 失败，费用退回余额。
- 计费
- 任务费用在创建任务时扣除。失败任务自动退款。
快速开始
用 JSON 方法识别一个 reCAPTCHA v2。把 YOUR_API_KEY 换成你的密钥。
import time, requests
API = "https://unlock-api.com"
KEY = "YOUR_API_KEY"
task = requests.post(f"{API}/createTask", json={
"clientKey": KEY,
"task": {
"type": "RecaptchaV2TaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "6LcR_RsTAAAAAFJR_5ZdbQd0SMxL7yIDmSXH1-lo"
}
}).json()
if task["errorId"]:
raise SystemExit(task["errorCode"])
while True:
time.sleep(5)
r = requests.post(f"{API}/getTaskResult", json={"clientKey": KEY, "taskId": task["taskId"]}).json()
if r["errorId"]:
raise SystemExit(r["errorCode"]) # failed tasks are refunded
if r["status"] == "ready":
print(r["solution"]["gRecaptchaResponse"])
breakJSON 方法
POST /createTask 创建任务
请求体：clientKey 和 task 对象。其他字段由任务类型决定，见“任务类型”。回复：errorId 0 和 taskId，或 errorId 1 和 errorCode。
POST https://unlock-api.com/createTask
{"clientKey":"YOUR_API_KEY","task":{"type":"TurnstileTaskProxyless","websiteURL":"https://example.com","websiteKey":"0x4AAAAAAAC3DHQFLr1GavRN"}}
{"errorId":0,"taskId":1001}
{"errorId":1,"errorCode":"ERROR_ZERO_BALANCE","errorDescription":"..."}POST /getTaskResult 获取结果
请求体：clientKey 和 taskId。任务运行中：status 为 processing。完成后：status 为 ready，附带 solution 和 cost。失败的任务回复 errorId 1 和对应的 errorCode。
POST https://unlock-api.com/getTaskResult
{"clientKey":"YOUR_API_KEY","taskId":1001}
{"errorId":0,"status":"processing"}
{"errorId":0,"status":"ready","solution":{"token":"0.zrSnRHO7h0..."},"cost":"0.0012","createTime":1791640000,"endTime":1791640011,"solveCount":1}POST /getBalance 查询余额
请求体：clientKey。回复：以美元计的 balance。
{"clientKey":"YOUR_API_KEY"}
{"errorId":0,"balance":42.5}报告错误答案
reportIncorrectRecaptcha 和 reportIncorrectImageCaptcha 接受 clientKey 和 taskId，并回复 success。它们是为兼容现有库而保留的；报告不会改变扣费。
表单方法（in.php、res.php）
发送任务：in.php
字段：key、method 和该验证码类型的字段。回复：OK|ID，或加上 json=1 时为 {"status":1,"request":"ID"}。错误以其名称返回，例如 ERROR_ZERO_BALANCE。
POST https://unlock-api.com/in.php
key=YOUR_API_KEY&method=hcaptcha&sitekey=SITE_KEY&pageurl=https://example.com&json=1
OK|1001
{"status":1,"request":"1001"}获取答案：res.php
action=get&id=ID 在识别完成时返回 OK|ANSWER，处理中返回 CAPCHA_NOT_READY。action=get2 会附带费用。ids=ID1,ID2 一次最多查询 100 个任务。action=getbalance 返回余额。也接受 action=reportbad 和 reportgood。
GET https://unlock-api.com/res.php?key=YOUR_API_KEY&action=get&id=1001 CAPCHA_NOT_READY OK|P1_eyJ0eXAiOiJKV1Qi... GET https://unlock-api.com/res.php?key=YOUR_API_KEY&action=getbalance 42.5
更多方法
POST /getToken 创建并等待：getToken
请求体与 createTask 相同。调用最多等待 50 秒，返回与 getTaskResult 相同的回复。如果任务仍在运行，回复为 status processing 及其 taskId；请继续轮询 getTaskResult。
POST https://unlock-api.com/getToken
{"clientKey":"YOUR_API_KEY","task":{"type":"TurnstileTaskProxyless","websiteURL":"https://example.com","websiteKey":"0x4AAAA..."}}
{"errorId":0,"taskId":1001,"status":"ready","solution":{"token":"0.zrSnRHO7h0..."},"cost":"0.000725"}结果回调
在 createTask 中加入 callbackUrl（或在 in.php 中加入 pingback），任务完成时结果会发送到该地址：一个类似 getTaskResult 并带有 taskId 的 JSON 请求体，in.php 则为表单请求体 id=…&code=…。只会调用公网地址，调用一次，超时 5 秒；结果仍可通过轮询获取。
{"clientKey":"YOUR_API_KEY","callbackUrl":"https://your.server/captcha-result","task":{...}}
POST https://your.server/captcha-result
{"errorId":0,"taskId":1001,"status":"ready","solution":{...},"cost":"0.0005"}统计
getQueueStats 返回当前等待中和识别中的任务数，以及最近一小时的平均识别时间。getSpendingStats 返回你在某个 UTC 日内每小时的任务量和金额（date 为 unix 时间）。test 会原样返回收到的请求体。
POST https://unlock-api.com/getQueueStats {"clientKey":"..."} -> {"errorId":0,"waiting":3,"solving":12,"speed":6.4,"total":15}
POST https://unlock-api.com/getSpendingStats {"clientKey":"...","date":1791590400} -> {"errorId":0,"data":[{"dateFrom":...,"volume":120,"money":0.06},...]}
POST https://unlock-api.com/test {"anything":1} -> {"errorId":0,"received":{"anything":1}}IP 白名单
如果你在账户页面设置了 IP 白名单，来自其他 IP 的请求会收到 ERROR_IP_NOT_ALLOWED。
任务类型
每种类型都有无代理名称和代理名称（去掉 Proxyless）。名称不区分大小写，也接受其他识别 API 使用的写法。代理任务还需要 proxyType（http、socks4、socks5）、proxyAddress 和 proxyPort，或一个代理字符串，例如 http://user:[email protected]:8080。此处未列出的可选字段会原样传给识别方。
reCAPTCHA v2 Enterprise
详情RecaptchaV2EnterpriseTaskProxylessRecaptchaV2EnterpriseTask
字段
websiteURL (必填)websiteKey (必填)
FunCaptcha (Arkose Labs)
详情FunCaptchaTaskProxylessFunCaptchaTask
字段
websiteURL (必填)websitePublicKey (必填)
KeyCaptcha
详情KeyCaptchaTaskProxylessKeyCaptchaTask
字段
websiteURL (必填)s_s_c_user_id (必填)s_s_c_session_id (必填)s_s_c_web_server_sign (必填)s_s_c_web_server_sign2 (必填)
Yandex SmartCaptcha
详情YandexSmartCaptchaTaskProxylessYandexSmartCaptchaTask
字段
websiteURL (必填)websiteKey (必填)
错误
两种格式使用相同的错误名称。因错误被拒绝的请求不收费。
| 错误 | 含义及处理方法 |
|---|---|
ERROR_KEY_DOES_NOT_EXIST | 密钥错误。请从账户页面重新复制。（in.php 和 res.php：ERROR_WRONG_USER_KEY） |
ERROR_ZERO_BALANCE | 余额不足以支付该任务。请充值；本次未扣费。 |
ERROR_NO_SLOT_AVAILABLE | 当前请求过多，任务未被接受。请几秒后重试；本次未扣费。 |
ERROR_TASK_NOT_SUPPORTED | 任务类型未知或已关闭。请检查类型名称。 |
ERROR_BAD_PARAMETERS | 缺少必填字段或字段格式错误。 |
ERROR_PAGEURL | 缺少 websiteURL 或 pageurl，或不是完整的 http(s) 地址。 |
ERROR_GOOGLEKEY | in.php 的 reCAPTCHA 请求缺少 googlekey。 |
ERROR_BAD_PROXY | 代理任务需要 proxyAddress 和 proxyPort。 |
ERROR_ZERO_CAPTCHA_FILESIZE | 图片缺失或太小。 |
ERROR_TOO_BIG_CAPTCHA_FILESIZE | 图片大于 100 KB。 |
ERROR_IMAGE_TYPE_NOT_SUPPORTED | 图片不是有效的 base64。 |
ERROR_WRONG_CAPTCHA_ID | 你的账户中没有该 ID 的任务。 |
CAPCHA_NOT_READY | 仅限 in.php 和 res.php：任务仍在运行。请 5 秒后再查询。 |
ERROR_CAPTCHA_UNSOLVABLE | 任务未能按时完成识别。费用已退回余额。 |
ERROR_TOO_MANY_REQUESTS | 请求过多。请把结果查询放慢到每 5 秒一次。 |
ERROR_IP_NOT_ALLOWED | 请求来自不在账户白名单中的 IP。请在账户页面添加该 IP。 |