hCaptcha

hCaptcha 작업은 토큰(gRecaptchaResponse)을 반환해요. 이 토큰을 반환된 userAgent(경우에 따라 respKey도 함께)와 같이 대상 웹사이트에 제출하면 검증을 통과할 수 있어요. HCaptchaTaskProxyless는 작업당 30 포인트 (≈ $4.50 / 1k), 자체 프록시를 쓰는 HCaptchaTask는 작업당 15 포인트 (≈ $2.25 / 1k)이고, 둘 다 비동기예요. 먼저 createTask를 호출한 뒤 5초마다 getTaskResult를 호출하세요. 인식에 실패하거나 시간이 초과되면 포인트가 자동으로 환불돼요.

POSThttps://api.yescaptcha.com/createTask글로벌 엔드포인트복사

POSThttps://cn.yescaptcha.com/createTask중국 엔드포인트복사

요청 본문은 JSON이고, clientKey로 인증해요. 작업을 만든 엔드포인트와 같은 엔드포인트에서 결과를 조회하세요.

사용 상황

웹페이지에 hCaptcha의 “사람입니다” 체크박스가 있거나 hCaptcha 이미지 문제가 나타나는 경우예요. 토큰을 받아 바로 제출하려면 이 페이지의 작업 유형을 사용하세요. 브라우저에서 직접 이미지를 클릭하려면 hCaptcha 이미지 인식을 사용하세요.

참고

hCaptcha 통과율은 웹사이트마다 크게 달라요. 먼저 소량으로 테스트하는 것을 권장해요.

작업 유형과 가격

작업 유형	가격	반환 방식	설명
HCaptchaTaskProxyless	$4.50 / 1k; 30 포인트/작업 · ¥30 / 1k	비동기
HCaptchaTaskProxylessM1	$4.50 / 1k; 30 포인트/작업 · ¥30 / 1k	비동기	HCaptchaTaskProxyless와 파라미터는 같고 경로만 달라요. 서로 대체용으로 사용할 수 있어요
HCaptchaTask	$2.25 / 1k; 15 포인트/작업 · ¥15 / 1k	비동기	자체 프록시

미국 달러 가격은 US$1 ≈ ¥6.67 기준의 추정치이며, 작업은 포인트로 차감돼요.

• HCaptchaTaskProxyless와 HCaptchaTaskProxylessM1은 파라미터가 같고 경로만 달라요. 서로 대체용으로 쓸 수 있어요.
• HCaptchaTask는 직접 준비한 프록시로 캡차를 불러와요. 프록시 필드를 전달해야 하며, 대상 웹사이트가 접속 IP를 검사할 때 사용하세요.

요청 파라미터

필드	유형	필수	설명
type	string	예	작업 유형이에요. 이 페이지의 "작업 유형 및 가격"을 참고하세요
websiteURL	string	예	캡차가 표시되는 페이지의 전체 URL이에요. 캡차 제공업체의 도메인이 아니라 캡차가 보이는 사이트를 입력하세요
websiteKey	string	예	hCaptcha 사이트 키(sitekey)예요. 보통 UUID 형식이에요
userAgent	string	아니요	브라우저 User-Agent예요. 입력하는 것을 권장하지만 GET https://api.yescaptcha.com/useragent가 반환한 값만 사용할 수 있어요. 토큰을 제출할 때는 결과의 userAgent를 사용하세요
isInvisible	boolean	아니요	보이지 않는(invisible) 버전이면 true로 설정하세요. 그렇지 않으면 생략하세요
rqdata	string	아니요	Enterprise hCaptcha의 rqdata예요. 일부 사이트에서 필요하고, 보통 캡차를 불러오는 요청에서 찾을 수 있어요
proxyType	string	일부 유형	프록시 프로토콜이에요: http, https, socks4, socks5 (HCaptchaTask에서 필수)
proxyAddress	string	일부 유형	프록시 IP 주소 또는 호스트 이름이에요. 127.0.0.1이나 192.168.x.x 같은 로컬 또는 사설 주소는 저희 서버가 접근할 수 없어서 사용할 수 없어요 (HCaptchaTask에서 필수)
proxyPort	integer	일부 유형	프록시 포트 (HCaptchaTask에서 필수)
proxyLogin	string	아니요	프록시 사용자 이름(프록시에 인증이 필요한 경우) (HCaptchaTask 전용)
proxyPassword	string	아니요	프록시 비밀번호(프록시에 인증이 필요한 경우) (HCaptchaTask 전용)

• websiteURL에는 캡차가 나타나는 웹페이지를 입력하세요. hcaptcha.com이 아니에요.
• userAgent는 입력하는 것을 권장해요. /useragent가 반환한 값만 사용할 수 있어요.
• rqdata: 엔터프라이즈 버전 hCaptcha(예: 일부 소셜, 채팅 웹사이트)에서 요구해요. 보통 캡차를 불러오는 요청에서 찾을 수 있어요. 일반 웹사이트에서는 전달하지 않아요.

파라미터를 찾는 방법은 hCaptcha 파라미터 찾기를 참고하세요.

요청 예시

POST https://api.yescaptcha.com/createTask

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
  }
}

curl

curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
  }
}'

# Returns {"errorId":0,"taskId":"..."}; then poll every 5 seconds:
curl -s https://api.yescaptcha.com/getTaskResult \
  -H 'Content-Type: application/json' \
  -d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'

Python

solve.py

import os
import time

import requests

API = "https://api.yescaptcha.com"
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]  # Read the clientKey from an environment variable


def call(method, payload):
    r = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30)
    data = r.json()
    if data.get("errorId"):
        raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
    return data


def solve(task):
    task_id = call("createTask", {"task": task})["taskId"]
    for _ in range(36):  # Poll every 5 seconds, for up to about 3 minutes
        time.sleep(5)
        result = call("getTaskResult", {"taskId": task_id})
        if result.get("status") == "ready":
            return result["solution"]
    raise TimeoutError(task_id)


solution = solve({
    "type": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
})
print(solution["gRecaptchaResponse"])

Node.js

solve.mjs

const API = 'https://api.yescaptcha.com';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY; // Read the clientKey from an environment variable

async function call(method, payload) {
  const res = await fetch(`${API}/${method}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ clientKey: CLIENT_KEY, ...payload }),
  });
  const data = await res.json();
  if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
  return data;
}

async function solve(task) {
  const { taskId } = await call('createTask', { task });
  for (let i = 0; i < 36; i++) { // Poll every 5 seconds, for up to about 3 minutes
    await new Promise((r) => setTimeout(r, 5000));
    const result = await call('getTaskResult', { taskId });
    if (result.status === 'ready') return result.solution;
  }
  throw new Error(`timeout: ${taskId}`);
}

const solution = await solve({
  type: "HCaptchaTaskProxyless",
  websiteURL: "https://accounts.hcaptcha.com/demo",
  websiteKey: "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
});
console.log(solution.gRecaptchaResponse);

자체 프록시를 사용하는 경우:

POST https://api.yescaptcha.com/createTask

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaTask",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
    "proxyType": "http",
    "proxyAddress": "proxy.example.com",
    "proxyPort": 8080,
    "proxyLogin": "user",
    "proxyPassword": "pass"
  }
}

반환 결과

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36",
    "respKey": "E0_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
  }
}

필드	유형	설명
gRecaptchaResponse	string	대상 웹사이트에 제출할 토큰이에요. 1회만 사용할 수 있고 약 120초 동안 유효하며, 60초 안에 사용하는 것을 권장해요
userAgent	string	토큰을 발급받을 때 사용한 User-Agent예요. 토큰을 제출할 때 이 값을 사용하세요. 보낸 값과 다르면 이 값이 우선해요
respKey	string	일부 웹사이트에서 토큰과 함께 제출해야 하는 값이에요. 값이 있으면 함께 제출하세요

제출할 때는 다음 순서로 진행하세요.

1. 토큰을 웹페이지의 h-captcha-response 필드(g-recaptcha-response 필드가 있으면 거기에도)에 넣거나, 대상 웹사이트 API가 요구하는 필드에 넣으세요.
2. 제출 요청을 보낼 때 User-Agent는 반환된 userAgent를 사용하세요.
3. respKey가 반환되었다면 웹사이트의 요구에 따라 함께 제출하세요.

처리 중이면 {"errorId": 0, "status": "processing"}가 반환돼요. 5초 후에 다시 조회하세요. 오류가 발생하면 errorCode에 따라 처리하세요. 오류 코드를 참고하세요.

자주 묻는 질문

통과율이 왜 일정하지 않나요?

hCaptcha는 웹사이트 설정, 접속 IP, 브라우저 환경을 바탕으로 판단하기 때문에 통과율이 웹사이트마다 달라요. 반환된 userAgent를 사용했는지 확인하세요. IP에 민감한 웹사이트에는 자체 프록시를 쓰는 HCaptchaTask를 사용하고, 제출할 때도 같은 프록시를 거치세요. HCaptchaTaskProxylessM1으로 바꿔서 비교해 볼 수도 있어요.

토큰은 얼마 동안 유효한가요?

한 번만 사용할 수 있고, 약 120초 동안 유효해요. 받은 뒤 가능한 한 빨리 제출하세요.

관련 튜토리얼

• hCaptcha 파라미터 찾기
• hCaptcha 이미지 인식으로 클릭 시뮬레이션(Selenium)