API 문서
엔드포인트 3개, 6개 언어의 전체 코드 예제. Capzy의 고성능 솔버 클러스터와 60초 안에 연동하세요.
빠른 시작
POST /createTask캡차 유형과 사이트 매개변수를 제출하면 즉시 taskId를 받습니다.
POST /getTaskResult상태가 ready가 될 때까지 약 1초 간격으로 폴링하세요. 토큰은 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선택 사항: 대상 사이트에서 해결이 승인(ACCEPTED)되었음을 알려 주세요. 위치를 반환하고 사용자의 브라우저가 드래그를 수행하는 좌표 반환 유형(예: Shopee 슬라이더)에 특히 유용합니다. 이 보고는 실제 정확도를 알 수 있는 유일한 신호입니다. 작업당 한 번, 24시간 이내이며 요금에는 영향을 주지 않습니다.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "errorId": 0 }/reportIncorrectCaptcha선택 사항: 대상 사이트에서 해결이 거부(REJECTED)되었음을 알려 주세요. /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_EXISTAPI 키를 인식할 수 없습니다.
해결 방법대시보드 → API 키에서 값을 다시 확인하세요. 키는 `capzy_`로 시작합니다. 교체된 키는 즉시 무효화됩니다.
- #
ERROR_IP_NOT_ALLOWED요청 IP가 API 키의 허용 목록에 없습니다.
해결 방법대시보드 → API 키에서 키의 허용 목록에 IP를 추가하거나, IP 고정이 필요 없다면 허용 목록을 완전히 제거하세요.
- #
ERROR_IP_BLOCKED잘못된 요청을 너무 많이 보내 IP가 일시적으로 차단되었습니다.
해결 방법10분 동안 잘못된 요청을 100건 이상 보내는 IP는 차단됩니다(단계적으로 강화). 잘못된 요청을 일으키는 버그를 수정한 후 기다리세요. 차단은 등급에 따라 1분에서 최대 24시간 후 자동으로 해제됩니다.
유효성 검사
잘못된 작업 매개변수 또는 사이트키에 맞지 않는 유형.- #
ERROR_INVALID_PARAMS요청 본문의 형식이 잘못되었거나 필수 필드가 누락되었습니다.
해결 방법`clientKey`가 최상위에 있고 `task`에 `type`과 필수 식별자(websiteURL/websiteKey/captchaId 등)가 포함되어 있는지 확인하세요. 유형별 필수 매개변수는 작업 유형 섹션을 참고하세요.
- #
ERROR_BAD_SITEKEY`websiteKey`가 식별 가능한 어떤 캡차 제공업체에도 등록되어 있지 않습니다.
해결 방법대상 페이지에서 전체 사이트키를 복사했는지 확인하세요(`data-sitekey`, `sitekey:` 또는 `grecaptcha.render` / `hcaptcha.render`의 매개변수를 찾으세요).
- #
ERROR_TASK_NOT_SUPPORTED제출한 작업 `type`은 Capzy가 현재 지원하는 캡차 유형이 아닙니다.
해결 방법활성화된 전체 목록은 아래 작업 유형 섹션을 참고하세요. 목록에 없는 캡차가 필요하면 티켓을 열어 주세요. 우선적으로 검토합니다.
- #
ERROR_WRONG_TASK_TYPE작업 유형이 사이트키의 실제 제공업체와 일치하지 않습니다.
해결 방법사이트키는 실제 제공업체를 기준으로 사전 확인됩니다. 오류 응답에 `recommended` 필드가 포함되어 있으니 해당 작업 유형으로 전환하세요. (크레딧은 차감되지 않습니다.)
- #
ERROR_PROXY_REQUIRED이 캡차는 IP에 바인딩됩니다. 토큰이 해결한 IP에 묶입니다.
해결 방법`*TaskProxyLess` 대신 `*Task` 변형으로 전환하고, 토큰을 제출할 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솔버가 이 챌린지에 대한 재시도 횟수를 모두 소진했습니다.
해결 방법자동 환불되며 요금이 없습니다. 일반적인 원인: 오래된 사이트키, websiteURL이 삽입 도메인과 일치하지 않음, 대상 사이트에서 캡차를 비활성화함.
- #
ERROR_NULL_RESULT솔버가 완료되었지만 토큰을 반환하지 않았습니다.
해결 방법자동 환불됩니다. 보통 해결 도중 대상 사이트가 캡차를 제거했음을 의미합니다. 다시 시도하고, 계속되면 티켓을 열어 주세요.
- #
ERROR_INTERNAL해결 파이프라인 내부에서 예기치 않은 오류가 발생했습니다.
해결 방법자동 환불됩니다. 다시 시도하세요(드물게 발생합니다). 반복적으로 발생하면 작업 UUID와 함께 티켓을 열어 주세요.
- #
ERROR_ZERO_BALANCE계정 잔액이 작업 비용을 충당하기에 부족합니다.
해결 방법대시보드 → 결제에서 크레딧을 충전하세요. 실패한 해결은 자동 환불되므로 성공한 토큰에 대해서만 지불합니다.
점수 보고
/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 키 받기 →