reCAPTCHA recognition
Solve reCAPTCHA image grids and replacement tiles through the recognition API or Chromium extension. Submit images and receive ordered boolean selections.
Choose your integration
The browser extension selects images and handles replacement tiles for you. Choose Free plan, or connect a paid API key, and enable Global and reCAPTCHA in the popup. The free plan provides 25 recognitions shared across hCaptcha and reCAPTCHA. Each replacement round uses one recognition.
For an application, submit recaptcha_recognition to POST /v1/task with your paid API key. The API returns image selections; your application applies them to the challenge. reCAPTCHA token submission is not supported.
The JavaScript/TypeScript, Python, and Go SDKs use their existing task methods:
createJob / getJob, create_job / get_job, and CreateJob / GetJob.
Pass the reCAPTCHA request fields below and read the completed boolean array.
Go accepts the instruction in JobRequest.Task as a JSON-encoded string and
provides RecaptchaImageSelect, RecaptchaTileSelect, and RecaptchaDynamic
grid constants. SDK extension configuration also accepts the independent
hcaptcha_enabled and recaptcha_enabled switches.
Request and result formats
grid |
image_data |
Completed result |
|---|---|---|
imageselect |
One full 3×3 challenge image | Nine booleans |
tileselect |
One full 4×4 challenge image | Sixteen booleans |
dynamic |
One to nine separate replacement tiles | One boolean per submitted tile |
Provide a nonempty English instruction in task, up to 254 bytes. Each image_data entry must be a base64 image data URI. HTTP image URLs are not supported. The request body limit is 4 MiB, including base64 data.
The public grid names are imageselect, tileselect, and dynamic. The native API does not accept the old values 3x3, 4x4, and 1x1; the NopeCHA compatibility adapter accepts them as aliases.
Results are flat boolean arrays. true means select the image; false means leave it unselected. Full-grid results run left to right, top to bottom. Replacement results follow the order of image_data, so keep the original cell positions in your application.
Submit a full grid
Replace the image placeholder with the base64 contents of the full challenge image:
curl https://api.easycaptcha.to/v1/task \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-binary '{
"type": "recaptcha_recognition",
"task": "Select all images with buses",
"grid": "imageselect",
"image_data": ["data:image/jpeg;base64,BASE64_CHALLENGE"],
"hold": 0
}'
The response contains a task_id, a status, and the task lifecycle fields. Save the full returned task ID and poll it:
curl 'https://api.easycaptcha.to/v1/task/TASK_ID' \
-H 'Authorization: Bearer YOUR_API_KEY'
Keep polling while status is queued or running. When status is completed, read result:
[true, false, false, true, false, false, false, true, false]
This is the result field of the completed snapshot. A failed task has an embedded error instead. See the API reference for the complete snapshot and problems for error handling. A transport failure during creation has an unknown submission outcome; do not resubmit automatically.
Handle replacement tiles
A repeating challenge starts with a full image: use imageselect for that first round. After applying positive selections, wait for the provider to finish replacing the selected tiles. Submit those replacement images as a new dynamic request with the same instruction. Map each returned boolean back to its original cell.
Repeat until no replacement image matches. Click Verify only then. Do not reuse a result after the challenge instruction or images change. A tileselect request uses the full 4×4 image and produces sixteen selections.
Pricing and limits
reCAPTCHA has one recognition rate for all three grid modes, billed once per request. A dynamic request with nine images costs the same as one with a single image. Each replacement round is a new request and is billed separately.
The default is $0.10 per 1,000 requests. reCAPTCHA and hCaptcha have independent rates; check your effective rate in the dashboard. Burst and fast multipliers apply when selected. Each request uses one shared concurrency unit.
Optional common fields include hold (0–30 seconds), burst, fast, developer_tag, sitekey, and url. Download the OpenAPI schema to generate request types. The existing create/get task lifecycle applies to both providers.
Vendor compatibility
The compatibility APIs support NopeCHA recognition, 2Captcha GridTask through JSON and legacy endpoints, and CapSolver ReCaptchaV2Classification. Use a paid API key on the corresponding compatibility hostname. The adapters translate image inputs and selection results into each vendor’s format. CapSolver classification returns its solution directly from /createTask.
For NopeCHA, POST the fields above to https://api-nopecha.easycaptcha.to/v1/recognition/recaptcha, using key for your paid API key. That alias infers the provider. At /, specify type: "recaptcha". Raw base64 images and legacy numeric grid names are also accepted on this adapter. Submission returns { "data": "TASK_ID" }; retrieval at the same route with id and key returns the boolean array in data.
More reCAPTCHA guides
- Grid types and result ordering: understand full grids and replacement images.
- Browser assistance: configure the extension and choose a plan.
- Extension vs recognition API: choose where selection handling belongs.
- Measuring recognition success: distinguish returned results from completed workflows.