hCaptcha 이미지 인식

HCaptchaClassification은 hCaptcha가 띄우는 이미지 문제를 인식해요. 문제와 이미지를 보내면 어떤 이미지를 선택해야 하는지, 어느 위치를 클릭해야 하는지, 어디에서 어디로 드래그해야 하는지를 반환하고, 브라우저에서의 실제 동작은 직접 작성한 프로그램이 처리해요. 토큰은 반환하지 않아요. 동기로 결과를 반환하며, 요청당 8 포인트 (≈ $1.20 / 1k)가 차감돼요. 대상을 찾지 못해 결과가 비어 있으면 포인트가 차감되지 않아요.

팁

클릭 로직을 직접 작성하고 싶지 않다면 브라우저 확장 프로그램을 사용하세요. 이 문제 유형을 모두 지원해요. 클릭 위치 대신 토큰이 필요하다면 hCaptcha를 사용하세요.

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

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

작업 유형과 가격

작업 유형	가격	반환 방식	설명
HCaptchaClassification	$1.20 / 1k; 8 포인트/작업 · ¥8 / 1k	동기	대상을 찾지 못하면 포인트가 차감되지 않아요

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

요청 파라미터

필드	유형	필수	설명
type	string	예	작업 유형이에요. 이 페이지의 "작업 유형 및 가격"을 참고하세요
queries	array	예	질문 이미지의 Base64 인코딩 목록이에요. 웹페이지에 표시된 순서대로 보내세요(3×3 그리드는 작은 이미지 9장)
question	string	아니요	웹페이지에 표시된 질문 전체 문장이에요(간체 중국어 또는 영어 권장). 예: Please click each image containing a bicycle. question과 anchors 중 하나 이상을 보내야 하며, 둘 다 보내는 것을 권장해요
anchors	array	아니요	질문 옆에 표시되는 예시 이미지의 Base64 인코딩 목록이에요. 예시 이미지가 있는 질문에는 반드시 보내야 해요

• question에는 웹페이지에 표시된 문제 문장을 그대로 넣으세요. 번역할 필요는 없지만 hCaptcha 언어를 중국어 간체나 영어로 바꾸는 것을 권장해요. 새로운 문제 문구는 보통 빠르게 지원하고, 완전히 새로운 카테고리는 영업일 기준 3일 이내에 지원해요.

주의

문제 오른쪽 위에 예시 이미지가 있다면 그 이미지를 anchors에 넣으세요. 예시 이미지를 봐야만 풀 수 있는 문제는 anchors를 보내지 않으면 인식할 수 없어요.

3×3 그리드 선택

문제가 “… 이(가) 포함된 이미지를 모두 클릭하세요”이고 아래에 이미지 9장이 있는 유형이에요. queries에 9장의 이미지를 순서대로 Base64로 넣으세요:

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

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaClassification",
    "question": "Please click each image containing a bicycle",
    "queries": ["BASE64_IMAGE_1", "BASE64_IMAGE_2"]
  }
}

반환 결과:

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "objects": [true, false, false, true, true, false, true, true, false],
    "top_k": [0, 3, 4, 6, 7],
    "confidences": [1.0, 0.0, 0.0, 1.0, 1.0, 0.0, 1.0, 1.0, 0.0]
  }
}

objects와 top_k는 같은 정보를 담고 있어요. objects는 각 이미지가 대상인지 여부이고, top_k는 대상 이미지의 번호(0부터 시작)예요. 해당 이미지를 클릭하면 돼요.

지정 위치 클릭

문제가 “… 을(를) 클릭하세요”이고 아래에 큰 이미지가 하나 있어, 이미지 위의 한 곳 또는 여러 곳을 클릭하는 유형이에요.

1. question에는 웹페이지의 문제를 넣고, 예시 이미지가 있으면 anchors에 넣으세요.
2. queries에는 이미지 한 장을 넣어요. canvas에서 바로 내보낸 원본 이미지가 가장 좋아요(JPG로 변환하는 것을 권장해요). 스크린샷만 가능하다면 아래 빨간 박스 안의 큰 이미지 영역만 정확히 캡처하세요. 더 넓거나 좁으면 안 돼요.
3. 반환된 box는 클릭할 좌표이며 x1, y1, x2, y2 … 순서로 들어 있고, 업로드한 이미지의 왼쪽 위를 원점으로 해요.
4. 업로드한 이미지 크기가 웹페이지에 표시된 크기와 다르면 변환해야 해요. 웹페이지의 x = 반환된 x × 표시 너비 ÷ 업로드 이미지 너비예요(y도 같아요). 예를 들어 반환된 x = 769이고 canvas 표시 너비가 350, 업로드 이미지 너비가 1000이면 웹페이지에서는 769 × 350 ÷ 1000 ≈ 269 위치를 클릭해야 해요.

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

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaClassification",
    "question": "Please click on the entity present in the sample image.",
    "anchors": ["BASE64_ANCHOR_1", "BASE64_ANCHOR_2", "BASE64_ANCHOR_3"],
    "queries": ["BASE64_OF_THE_BIG_IMAGE"]
  }
}

반환 결과:

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "box": ["221", "213"]
  }
}

대상을 여러 개 클릭해야 하면 box에 여러 좌표 쌍이 순서대로 들어 있어요: ["221", "213", "340", "118", ...].

지정 위치로 드래그

문제가 “… 을(를) … 로 드래그하세요”이고, 오른쪽의 조각을 이미지의 해당 위치로 드래그하는 유형이에요.

1. question에는 웹페이지의 문제를 넣으세요.
2. 스크린샷 한 장을 queries에 넣으세요. 이미지에 드래그할 조각과 목표 위치가 모두 보여야 하고, 이미지의 어느 변도 260픽셀 이상이어야 해요.
3. 반환된 box의 각 항목은 한 번의 드래그예요. start는 조각의 위치이고 end는 놓을 위치예요. 조각이 여러 개면 하나씩 드래그하세요.

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "type": "drag",
    "box": [
      {
        "start": [644, 218],
        "end": [239, 315]
      }
    ]
  }
}

스크린샷이 아니라 프로토콜 데이터(조각 이미지, 조각 좌표, 배경 큰 이미지)를 가지고 있다면, 먼저 좌표에 맞게 조각을 큰 이미지 위에 합성해서 웹페이지 스크린샷과 같은 모양으로 만든 뒤 전송하세요.

애니메이션 문제

문제 이미지가 애니메이션이면 애니메이션(GIF 등 형식)을 Base64로 인코딩해서 queries에 넣으세요. 애니메이션 길이는 최소 3초, 가능하면 5~6초, 프레임 레이트는 약 12 FPS를 권장해요.

신고와 포인트 환불

클릭 후 검증에 실패했다면 1시간 이내에 report로 신고할 수 있어요. 약 24시간 후 포인트 환불이 정산돼요. 규칙은 과금 및 포인트 환불을 참고하세요.

관련 튜토리얼

• hCaptcha 이미지 인식 클릭 시뮬레이션(Selenium)