캡차 풀이 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과 오류 이름으로 답해요.

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. 답: 미국 달러 잔액.

{"clientKey":"YOUR_API_KEY"}

{"errorId":0,"balance":42.5}

틀린 답 신고

reportIncorrectRecaptcha와 reportIncorrectImageCaptcha는 clientKey와 taskId를 받아 success로 답해요. 기존 라이브러리와 맞추려고 받아 두는 호출이고, 비용은 바뀌지 않아요.

작업 보내기: in.php

항목: key, method, 그리고 캡차 종류별 항목. 답: OK|번호, json=1이면 {"status":1,"request":"번호"}. 오류는 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=번호는 풀리면 OK|답, 푸는 중이면 CAPCHA_NOT_READY. action=get2는 비용도 함께 줘요. ids=번호1,번호2로 한 번에 100개까지 확인해요. action=getbalance는 잔액, 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와 같은 JSON에 taskId가 붙고, 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는 지금 대기 중·푸는 중인 작업 수와 최근 1시간 평균 풀이 시간을 줘요. getSpendingStats는 UTC 하루(date는 유닉스 시간) 동안 시간별 작업 수와 금액을 줘요. 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를 받아요.