# hCaptcha image recognition

> Recognize hCaptcha image challenges with YesCaptcha (HCaptchaClassification). Grid selection, click-a-position, drag-to-position and animated questions; synchronous, and free when no target is found.

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

`HCaptchaClassification` recognizes hCaptcha image challenges: send the question and images, and get back which images to select, which position to click, or where to drag from and to; your code performs the action in the browser. It **does not return a token**. It is synchronous, costs 8 points (¥0.008) per request, and is free when no target is found (empty result).

> **Tip:** If you’d rather not write clicking code, the [browser extension](https://docs.yescaptcha.com/en/extension/) handles all of these question styles. For a token instead of click positions, use [hCaptcha](https://docs.yescaptcha.com/en/tasks/hcaptcha/).

- POST `https://api.yescaptcha.com/createTask` (Global endpoint)
- POST `https://cn.yescaptcha.com/createTask` (China endpoint)

## Task types and pricing

| Task type | Price | Mode | Notes |
| --- | --- | --- | --- |
| `HCaptchaClassification` | 8 points (¥0.008) | Synchronous | Not charged when no target is found |

## Request parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | Yes | Task type; see "Task types and pricing" on this page |
| `queries` | array | Yes | List of Base64-encoded challenge images in page order (9 tiles for a 3×3 grid) |
| `question` | string | No | The full question as shown on the page (Simplified Chinese or English recommended), e.g. `Please click each image containing a bicycle`. Send at least one of `question` and `anchors`; sending both is recommended |
| `anchors` | array | No | Base64-encoded example images shown next to the question; required for questions that have them |

-   Send `question` exactly as shown on the page; there is no need to translate it, but switching hCaptcha to English or Simplified Chinese is recommended. New wordings are supported quickly; brand-new categories within 3 business days.
-   If the question shows example images next to it, send them in `anchors`. Questions that can only be answered from the example images fail without `anchors`.

## Grid selection

The question reads “Please click each image containing …” above 9 images. Put the 9 images in `queries`, in page order:

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

Result:

```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` and `top_k` carry the same information: the first says for each image whether it is a target, the second lists the target indexes (from 0). Click those images.

## Click a position

The question reads “Please click on …” above one large image, and you click one or more positions on it.

1.  Take `question` from the page; put any example images in `anchors`.
2.  Put one image in `queries`: ideally the original exported from the canvas (JPG recommended). If you can only screenshot, capture exactly the large image area, no more and no less.
3.  `box` in the result lists the coordinates to click as x1, y1, x2, y2, …, from the top-left of the uploaded image.
4.  If the uploaded image’s size differs from its size on the page, scale: page x = returned x × displayed width ÷ uploaded width (same for y). For example, x = 769 on a 1000-px-wide upload shown 350 px wide is 769 × 350 ÷ 1000 ≈ 269 on the page.

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

Result:

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

When several targets need clicking, `box` holds several coordinate pairs: `["221", "213", "340", "118", ...]`.

## Drag to a position

The question reads “Drag … to …”, and you drag pieces on the right to their place in the picture.

1.  Take `question` from the page.
2.  Put one screenshot in `queries` that shows **both** the pieces and their destinations, with each side at least 260 px.
3.  Each item of `box` in the result is one drag: `start` is where the piece is, `end` is where to drop it. With several pieces, drag them one by one.

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

![A drag result: Start marks the pieces, End marks their destinations](https://docs.yescaptcha.com/_astro/hcaptcha-drag-result.vEj4iyUz_1Ou9zz.webp)

If you have protocol data (piece images, piece coordinates and the background) instead of a screenshot, paste the pieces onto the background at their coordinates to make an image that looks like the screenshot, then send it.

## Animated questions

For animated challenge images, send the animation (GIF or similar) Base64-encoded in `queries`. An animation of at least 3 seconds, ideally 5 to 6, at about 12 FPS works best.

## Reports and refunds

If the site rejects your clicks, report the tasks with [`report`](https://docs.yescaptcha.com/en/api/report/) within 1 hour; refunds are settled after about 24 hours. Rules: [Billing and refunds](https://docs.yescaptcha.com/en/getting-started/billing/).

## Related guides

-   [hCaptcha image clicking with Selenium](https://docs.yescaptcha.com/en/guides/hcaptcha-click-selenium/)