Image Grid

Image Grid tasks identify and select the correct cells in a grid-based image challenge. This is the type of challenge commonly seen in reCAPTCHA v2 image selection, where a large image is divided into a grid and you must select all squares matching a prompt (e.g., “Select all squares with crosswalks”).

Task Type

Type	Description
`ImageGridTask`	Select correct cells from a grid image

Parameters

Parameter	Type	Required	Description
`type`	string	Yes	`ImageGridTask`
`body`	string	Yes	Base64-encoded grid image
`rows`	integer	No	Number of grid rows (default: 3)
`columns`	integer	No	Number of grid columns (default: 3)
`comment`	string	No	Instructions (e.g., “Select all squares with crosswalks”)

Create Task

Request

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "ImageGridTask",
    "body": "iVBORw0KGgoAAAANSUhEUg...",
    "rows": 3,
    "columns": 3,
    "comment": "Select all squares with crosswalks"
  }
}

Response

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "cells": [1, 3, 5, 7]
  }
}

Solution Object

{
  "cells": [1, 3, 5, 7]
}

Field	Type	Description
`cells`	array	Array of selected cell indices (1-based, left-to-right, top-to-bottom)

Cell numbering follows a left-to-right, top-to-bottom order starting at 1. For a 3x3 grid:

| 1 | 2 | 3 |
| 4 | 5 | 6 |
| 7 | 8 | 9 |

Code Examples

Python

import requests
import base64

API_KEY = "YOUR_API_KEY"

with open("grid_captcha.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode()

response = requests.post("https://api.ucaptcha.net/createTask", json={
    "clientKey": API_KEY,
    "task": {
        "type": "ImageGridTask",
        "body": image_data,
        "rows": 3,
        "columns": 3,
        "comment": "Select all squares with crosswalks"
    }
}).json()

if response.get("status") == "ready":
    cells = response["solution"]["cells"]
    print("Selected cells:", cells)
else:
    import time
    task_id = response["taskId"]
    while True:
        result = requests.post("https://api.ucaptcha.net/getTaskResult", json={
            "clientKey": API_KEY,
            "taskId": task_id
        }).json()

        if result["status"] == "ready":
            cells = result["solution"]["cells"]
            print("Selected cells:", cells)
            break
        elif result["status"] == "failed":
            print("Error:", result.get("errorDescription"))
            break

        time.sleep(5)

JavaScript

import { readFileSync } from "fs";

const API_KEY = "YOUR_API_KEY";

const imageData = readFileSync("grid_captcha.png").toString("base64");

const response = await fetch("https://api.ucaptcha.net/createTask", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientKey: API_KEY,
    task: {
      type: "ImageGridTask",
      body: imageData,
      rows: 3,
      columns: 3,
      comment: "Select all squares with crosswalks"
    }
  })
}).then(r => r.json());

if (response.status === "ready") {
  console.log("Selected cells:", response.solution.cells);
} else {
  const taskId = response.taskId;
  while (true) {
    const result = await fetch("https://api.ucaptcha.net/getTaskResult", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ clientKey: API_KEY, taskId })
    }).then(r => r.json());

    if (result.status === "ready") {
      console.log("Selected cells:", result.solution.cells);
      break;
    } else if (result.status === "failed") {
      console.error("Error:", result.errorDescription);
      break;
    }

    await new Promise(r => setTimeout(r, 5000));
  }
}

cURL

IMAGE_BASE64=$(base64 -w 0 grid_captcha.png)

curl -X POST https://api.ucaptcha.net/createTask \
  -H "Content-Type: application/json" \
  -d "{
    \"clientKey\": \"YOUR_API_KEY\",
    \"task\": {
      \"type\": \"ImageGridTask\",
      \"body\": \"$IMAGE_BASE64\",
      \"rows\": 3,
      \"columns\": 3,
      \"comment\": \"Select all squares with crosswalks\"
    }
  }"

# Poll for result if not immediately ready (replace TASK_ID)
curl -X POST https://api.ucaptcha.net/getTaskResult \
  -H "Content-Type: application/json" \
  -d '{
    "clientKey": "YOUR_API_KEY",
    "taskId": "TASK_ID"
  }'

Provider Coverage

2Captcha
Anti-Captcha

Aliases

The following legacy type name is also accepted for backward compatibility:

GridTask