验证码识别 API 参考

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

字段：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。