# hCaptcha 이미지 인식

> YesCaptcha로 hCaptcha 이미지 문제(HCaptchaClassification)를 인식해요. 3×3 그리드 선택, 지정 위치 클릭, 지정 위치로 드래그, 애니메이션 문제를 지원하고, 동기로 결과를 반환하며, 대상을 찾지 못하면 포인트가 차감되지 않아요.

Source: https://docs.yescaptcha.com/ko/tasks/hcaptcha-classification/ · Last verified: 2026-10-15

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/hcaptcha-classification/

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

> **팁:** 클릭 로직을 직접 작성하고 싶지 않다면 [브라우저 확장 프로그램](https://docs.yescaptcha.com/ko/extension.md)을 사용하세요. 이 문제 유형을 모두 지원해요. 클릭 위치 대신 토큰이 필요하다면 [hCaptcha](https://docs.yescaptcha.com/ko/tasks/hcaptcha.md)를 사용하세요.

- POST `https://api.yescaptcha.com/createTask` (글로벌 엔드포인트)
- POST `https://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

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

반환 결과:

```json
{
  "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 위치를 클릭해야 해요.

![클릭 문제의 캡처 범위: 문제 텍스트는 question, 예시 이미지 3장은 anchors, 아래의 큰 이미지는 queries](https://docs.yescaptcha.com/_astro/hcaptcha-click-areas.DCBFUFPf_Z123RnJ.webp)

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

```json
{
  "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"]
  }
}
```

반환 결과:

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

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

## 지정 위치로 드래그

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

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

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

![드래그 문제의 인식 결과 예시: Start는 드래그할 조각, End는 목표 위치](https://docs.yescaptcha.com/_astro/hcaptcha-drag-result.vEj4iyUz_1Ou9zz.webp)

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

## 애니메이션 문제

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

## 신고와 포인트 환불

클릭 후 검증에 실패했다면 1시간 이내에 [report](https://docs.yescaptcha.com/ko/api/report.md)로 신고할 수 있어요. 약 24시간 후 포인트 환불이 정산돼요. 규칙은 [과금 및 포인트 환불](https://docs.yescaptcha.com/ko/getting-started/billing.md)을 참고하세요.

## 관련 튜토리얼

-   [hCaptcha 이미지 인식 클릭 시뮬레이션(Selenium)](https://docs.yescaptcha.com/ko/guides/hcaptcha-click-selenium.md)