Skip to content
capzy
Login

Coordinate Click CAPTCHA

Map an instruction to click points in the image. Capture the image and its click instruction together. Returned points refer to the original image geometry and must stay in their returned order.

Get the integration code
POST /createTask · example
{
  "clientKey": "capzy_YOUR_API_KEY",
  "task": {
    "type": "CoordinatesTask",
    "body": "/9j/4AAQSkZJRgABAQ...",
    "comment": "click all traffic lights"
  }
}

Illustrative values. Replace the inputs with values from your current integration.

Base64 image + click instructionDirect task integrationx / y coordinate pairs

Keep the original image dimensions.

Capture the image and its click instruction together. Returned points refer to the original image geometry and must stay in their returned order.

Your API key authenticates Capzy.
Provider keys, challenge IDs, images, and session values belong inside task.

Send the exact question with the original bytes.

  1. Save the current image response and copy the displayed click instruction exactly into comment.
  2. Base64-encode the original file into body. Keep its width and height for result interpretation.
  3. Retain the current challenge identifier/session; do not use the points on a refreshed image.
Input collection example - replace illustrative values
import base64
from pathlib import Path

def image_bytes(filename):
    return base64.b64encode(Path(filename).read_bytes()).decode("ascii")

task_inputs = {
    "body": image_bytes("challenge.png"),
    "comment": "YOUR_EXACT_CLICK_INSTRUCTION"
}

comment is required. It tells the solver which objects to select and whether order matters.

How Coordinate Click CAPTCHA works

A generic task for captchas that require clicking at specific points on an image. Send the image and a text description of what to click, and our AI returns the (x,y) coordinates. Useful for custom captchas ('click all fire hydrants'), Chinese character selection, and icon matching puzzles.

Capzy's proprietary classifier returns the (x, y) coordinates that match your prompt. Useful for accessibility tooling and authorized image-analysis workflows.

  • Capzy proprietary object detection + classification
  • Works with any text prompt
  • Returns multiple coordinates
  • < 3 second solve time

Know what goes in.

Choose a field to see its purpose, where to get it, and its place in the request. Optional values omitted from the example can be added when your flow uses them.

The request below follows your selected task configuration.

Request authentication

Required task inputs

body

stringRequired

Base64-encoded image

Where it comes from

Save the original CAPTCHA image bytes from the current challenge and base64-encode them. Send the encoded bytes, not a local path.

Open the input guide
Example value/9j/4AAQSkZJRgABAQ...
POST /createTask · selected configuration
{
  "clientKey": "capzy_YOUR_API_KEY",
  "task": {
    "type": "CoordinatesTask",
    "body": "/9j/4AAQSkZJRgABAQ...",
    "comment": "click all traffic lights"
  }
}

The selected field is highlighted when present. Preserve the declared value type and current challenge context.

Make your first request.

Create the task, keep its taskId, and poll until status is ready. Then read the selected variant's solution.

More examples
  1. Create the task

    Send clientKey and the selected task to /createTask from your server. Keep the returned taskId.

  2. Wait for the solution

    Send that same key and ID to /getTaskResult. While processing, wait two seconds before checking again. Stop on Ready or an error.

  3. Apply the result

    Apply solution.coordinates to the same challenge in the returned order. Scale to the displayed image when clicking, or use the verification endpoint's expected original-image coordinates.

CoordinatesTask · Price unavailable / 1,000
solve_coordinates.py
import json, os, time
import requests

API = "https://api.capzy.ai"
KEY = os.environ["CAPZY_API_KEY"]
task = json.loads("{\"type\":\"CoordinatesTask\",\"body\":\"/9j/4AAQSkZJRgABAQ...\",\"comment\":\"click all traffic lights\"}")

def call(path, payload):
    response = requests.post(f"{API}/{path}", json={"clientKey": KEY, **payload}, timeout=30)
    response.raise_for_status()
    data = response.json()
    if data.get("errorId", 0) or data.get("status") == "failed":
        raise RuntimeError(data.get("errorDescription") or data.get("errorCode") or "Task failed")
    return data

created = call("createTask", {"task": task})
for attempt in range(60):
    result = call("getTaskResult", {"taskId": created["taskId"]})
    if result.get("status") == "ready":
        solution = result["solution"]
        print(solution)
        break
    time.sleep(2)
else:
    raise TimeoutError("Task is still processing; keep the taskId to check it later.")

Before runningReplace all illustrative inputs with your captured values. Set CAPZY_API_KEY in your environment. Install requests with pip install requests.

Polling and failuresThe example checks HTTP/API failures, uses 30-second request timeouts, and stops after 60 result checks. Retain taskId if your task is still processing.

Understand what comes back.

Follow this task from creation to completion. Response fields and usage follow your selected request variant.

x / y coordinate pairs

Apply solution.coordinates to the same challenge in the returned order. Scale to the displayed image when clicking, or use the verification endpoint's expected original-image coordinates.

array
Array of {x, y} objects — the click points
POST /getTaskResult · example response
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "coordinates": [
      {
        "x": 142,
        "y": 87
      },
      {
        "x": 234,
        "y": 191
      },
      {
        "x": 318,
        "y": 102
      }
    ]
  }
}

Illustrative values. Additional metadata may be returned; only Ready contains a completed solution.

Use the result

Apply solution.coordinates to the same challenge in the returned order. Scale to the displayed image when clicking, or use the verification endpoint's expected original-image coordinates.

Execution context result is the parsed Ready response from the polling example. session, when referenced, is your existing requests.Session (or browser-compatible session) with the original cookie jar, headers, and solving proxy configured in session.proxies for both http and https. Keep this client for the complete flow. task is the task object you submitted. For Shape, action_body is the original protected request body as bytes or a string, with its original Content-Type in session.headers. Install curl_cffi when the fragment imports it; match the target's required browser/TLS identity.

Use the result · Python

# Step 3: Coordinates — click each (x,y) point in your browser session
for pt in result["solution"]["coordinates"]:
    # e.g. Selenium: ActionChains(driver).move_by_offset(pt["x"], pt["y"]).click().perform()
    print(pt["x"], pt["y"])

When something doesn't work.

Check your captured values, the selected variant, and the response before starting another task.

How accurate is it?

Very accurate for common objects (vehicles, signs, animals). For unusual prompts, accuracy depends on how well our classifier can match the description to image regions.

Connect Coordinate Click CAPTCHA to your workflow.

Get your Capzy API key and use this guide's integration.

Get an API key Full API documentation
UnavailablePer 1,000 solves
UnavailableAverage solve time

CoordinatesTask · Live configuration
Current stats are unavailable. Check the solver catalog.