Integrate hCaptcha area-selection recognition

Submit area-selection challenges with stable image identifiers, then map returned coordinate data to the correct original image and UI scale.

Treat an image location as a coordinate problem

An area-selection challenge requires locations within an image instead of yes-or-no labels for tiles. The easycaptcha recognition request uses request_type: "image_label_area_select", retaining the question and the original image task keys.

The application must associate returned coordinates with the correct source image. A resized browser display, cropped preview, or substituted image can make otherwise meaningful coordinates land in the wrong place.

Submit the original challenge structure

{
  "type": "hcaptcha_recognition",
  "task": {
    "request_type": "image_label_area_select",
    "requester_question": { "en": "Select the center of the circle" },
    "tasklist": [
      {
        "task_key": "image-a",
        "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII="
      }
    ]
  }
}

The image above is a tiny PNG fixture showing the data URI format, not a circle-selection challenge. Replace it with the original challenge media and use its actual question. datapoint_uri accepts base64 image/video data URIs only; HTTP(S) URLs are rejected. If your source provides a remote URL, download the bytes in your integration and encode them before submission. You can add the optional sitekey on the outer request for attribution. Creation follows the same task lifecycle as other recognition types: save the ID, observe pending work, and check terminal status before interpreting the result.

Map answers without silently guessing

Area results are keyed by image task identifier and contain selection data, including entity_coords and entity_name. Use the published API schema for the exact result shape and numeric constraints. A null entry is not an instruction to click the image center.

Document how the source coordinate system maps to your rendered image. Apply scaling and offsets exactly once, and test the mapping with known fixture points near each edge. Preserve the image’s dimensions and avoid modifying it between submission and application of the answer.

Diagnose recognition and UI application separately

When an answer is rejected, examine whether the source question and image were correct, whether a complete result arrived, and whether the application used the intended coordinate transform. Repeatedly sending the same image will not fix a deterministic scaling bug.

One area-selection image is a recognition group. A multi-image challenge can therefore cost multiple groups. Record task IDs and observed outcomes for feedback, keeping private form data out of traces. The coordinate-transform article gives a debugging checklist, and binary recognition shows why result families should remain distinct.