Skip to content
easycaptcha.to

Developer workflows

Integrating reCAPTCHA recognition into a Python workflow

Integrating reCAPTCHA recognition into a Python workflow. Follow practical setup steps and checks for your easycaptcha reCAPTCHA workflow.

By the easycaptcha team · Published

Reading map for Integrating reCAPTCHA recognition into a Python workflow: Separate waiting from image application; Keep dynamic state between calls; Prepare a request from a local image.
An illustrated reading map of the considerations discussed below.View full-size illustration

The Python SDK exposes create_job and get_job for reCAPTCHA recognition. Submit a request with type recaptcha_recognition, the English task instruction, grid, and image_data. Keep the paid customer key in protected configuration.

Separate waiting from image application

Create once, retain task_id, and poll queued or running tasks. On completed, read the boolean result; on failed, handle the embedded error. Keep the code that maps selections to your images separate from the code that waits for a task.

Keep dynamic state between calls

For replacement rounds, retain the instruction and ordered cell map between requests. Submit the new tile data as dynamic and pair its result with that map. A Python list index alone is not a persistent browser cell identity.

Prepare a request from a local image

Install easycaptcha-sdk and keep the paid account key in EASYCAPTCHA_API_KEY. The following example uses the standard-library HTTP backend and a full 3×3 JPEG fixture. It prepares the native request shape; replace the filename and instruction with inputs from your controlled workflow.

import base64
import os
from pathlib import Path
from easycaptcha.backends.urllib import UrllibClient

encoded = base64.b64encode(Path("challenge.jpg").read_bytes()).decode("ascii")
request = {
    "type": "recaptcha_recognition",
    "task": "Select all images with buses",
    "grid": "imageselect",
    "image_data": [f"data:image/jpeg;base64,{encoded}"],
    "hold": 30,
}

Encoding the file contents matters. Encoding the filename or a remote URL string produces text bytes rather than the image the recognizer needs. Also check the final serialized request size, since the 4 MiB limit includes base64 and JSON overhead.

Create once, then retrieve the same task

Continue the example with a bounded polling loop. The local deadline below limits observation time; it does not cancel the remote task. Save the identifier in durable application state if another process may need to resume the lookup.

import time

with UrllibClient(os.environ["EASYCAPTCHA_API_KEY"]) as client:
    job = client.create_job(request)
    task_id = job["task_id"]
    deadline = time.monotonic() + 180
    while job["status"] in ("queued", "running"):
        if time.monotonic() >= deadline:
            raise TimeoutError(f"Retrieve {task_id} again later")
        time.sleep(1)
        job = client.get_job(task_id)
    if job["status"] == "failed":
        raise RuntimeError(job["error"]["detail"])
    selections = job["result"]

The hold value can let creation return a completed snapshot, but the same code must handle queued and running responses. An HTTP exception during creation is a separate path from an embedded failed status. Do not put the entire create operation inside an unconditional retry loop.

Validate and map before handing results to the browser

For this full-grid request, require nine boolean values before mapping positions. Use sixteen for tileselect. For dynamic requests, the expected count is the number of replacement images submitted, and each result must be paired with its stored cell record. Keep false entries until mapping is complete.

The Python process receiving the result may finish after the browser resets the challenge. Carry a local round identifier through your application and verify it before applying selections. If the input snapshot is stale, record that outcome and obtain current images instead of applying a valid result to unrelated cells.

Adapt waiting behavior to the application

A synchronous worker can use the standard-library backend and time.sleep as shown. An asynchronous application should use the documented async client methods and nonblocking waiting rather than blocking its event loop. The task contract and status checks remain the same even when the HTTP backend changes.

Keep image preparation, remote task observation, and browser application as separate responsibilities. That makes it possible to reproduce mapping defects with local arrays and investigate API errors using task IDs. The recognition documentation supplies the complete fields; this example deliberately leaves application-specific capture and browser interaction to your own workflow.

Make request preparation and recovery observable

Before creating the task, validate the instruction byte length, image count, and serialized payload size. Store a compact local record containing grid mode, round identity, and expected result length. These values explain the request contract without writing base64 data or the account key into logs. Use the record to validate the completed answer before passing it to browser code.

A production worker should also preserve task identity across the boundary where it can restart or lose its HTTP connection. If creation returned an ID, later recovery should retrieve that work rather than rerun the creation block. If the initial response was lost before an ID was known, record the submission as uncertain and follow an explicit application policy instead of hiding it in a broad retry decorator.

Keep the local mapping function testable with lists of booleans and stored cell positions. Python truth-value coercion should not substitute for checking that external entries are actual booleans: the string "false" is truthy. Validate the response shape first, map second, and observe the application outcome after selections are applied. Each step then has a clear diagnostic boundary.

Frequently asked questions

Which Python SDK methods handle reCAPTCHA recognition?

Use create_job and get_job with the documented reCAPTCHA request fields.

Which Python backend is used in the example?

The example uses UrllibClient from easycaptcha.backends.urllib with the standard-library HTTP backend.

Should an async application use time.sleep while polling?

No. Use the documented async client methods and nonblocking waiting so the event loop can continue serving other work.

Try easycaptcha

Build with the easycaptcha API

Use easycaptcha for reCAPTCHA image recognition with the documented grid formats and task lifecycle.

Submit hCaptcha recognition or token jobs, retrieve results, and send feedback through one API. Typed Python and JavaScript SDKs help you get started.