Submit binary hCaptcha image-recognition jobs

Preserve image task keys and question data when submitting a binary challenge, then read keyed answers rather than assuming a positional token result.

Keep the original task keys

A binary recognition challenge asks whether each image matches a question. The easycaptcha request carries the original structured challenge in task, with request_type: "image_label_binary". Each image has a task_key and a datapoint_uri containing base64-encoded image or video bytes in a data URI. Remote image URLs are not accepted.

Preserving keys is essential when results return out of a program’s assumed order or when the source challenge uses identifiers that do not match array indexes. Keep your key-to-image mapping alongside the job ID.

Construct the recognition request

{
  "type": "hcaptcha_recognition",
  "sitekey": "YOUR_SITEKEY",
  "task": {
    "request_type": "image_label_binary",
    "requester_question": {
      "en": "Select the images containing a circle"
    },
    "tasklist": [
      {
        "task_key": "tile-1",
        "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII="
      },
      {
        "task_key": "tile-2",
        "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII="
      },
      {
        "task_key": "tile-3",
        "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII="
      },
      {
        "task_key": "tile-4",
        "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII="
      },
      {
        "task_key": "tile-5",
        "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII="
      },
      {
        "task_key": "tile-6",
        "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII="
      },
      {
        "task_key": "tile-7",
        "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII="
      },
      {
        "task_key": "tile-8",
        "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII="
      },
      {
        "task_key": "tile-9",
        "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII="
      }
    ]
  }
}

The nine entries above use the same tiny PNG fixture to demonstrate the payload format; they are not a real challenge. Replace each data URI with the corresponding original tile bytes and preserve the actual question and task keys. Binary challenges require exactly 9, 18, or 27 tiles.

If the source challenge supplies HTTPS image URLs, fetch the media in your integration first, base64-encode the bytes, and build a data:<media-type>;base64,<encoded-bytes> URI. Do not send the remote URL as datapoint_uri. Use the response media type, such as image/png or video/webm, for the data URI header.

Interpret the result by challenge family

A completed binary recognition result maps task keys to boolean answers or nullable entries. It is not a result.token object. Handle an absent or null answer explicitly instead of treating it as a confident match or substituting an array position.

Check the job status before reading the result. Failed snapshots have an embedded problem, and pending work needs another lookup for the same ID. Your application is responsible for applying recognition results to its own workflow.

Keep billing and feedback honest

Nine binary tiles form a recognition group for billing. A larger challenge can use more than one group. The optional sitekey attributes challenge statistics; it does not change the task into token solving.

Report feedback after observing whether the applied answers were accepted. Separate recognition completion from the final action’s success. The API reference defines wire shapes, and recognition versus token solving explains which operation an integration should choose.