CAPTCHA Task Query API (Server-side Asynchronous Task) Integration Instructions

This document introduces the CAPTCHA asynchronous task query interface POST /captcha/tasks. When you call any CAPTCHA interface (token series or recognition series) and pass async: true, the interface will immediately return a task_id, and the server will take over and continue processing; you can use this task_id to query the final result, but querying is not a prerequisite for the task to continue executing. This is suitable for scenarios like multi-solver rotation: after submitting the task, you immediately get the task_id, schedule other solvers, and come back later to read the results.

📘 Complete interactive documentation (including online debugging): CAPTCHA Task Query API →

Application Process

To use this interface, first go to the 辰汐ai Console to obtain your API Token for backup. One API Token can call all services on the platform, no need to apply separately for each service.

Basic Usage

Step 1: Create a Task Asynchronously

In the request body of any CAPTCHA interface, pass async: true, and the interface will immediately return a task_id (HTTP 201) without blocking:

curl -X POST 'https://api.acedata.cloud/captcha/token/recaptcha2' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_key": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
  "website_url": "https://www.google.com/recaptcha/api2/demo",
  "async": true
}'

{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}

Step 2 (Optional): Query Results with task_id

If you need to actively check the progress, you can use the task_id returned from the previous step to query POST /captcha/tasks (recommended every 3-5 seconds). This interface will not trigger or advance task processing; reading ready results follows the existing one-time settlement behavior:

curl -X POST 'https://api.acedata.cloud/captcha/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002"
}'

During processing, it will return status: processing:

{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "processing"
}

When processing is complete, it will return status: ready and the corresponding result fields—the field structure is completely consistent with synchronous mode:

  • Token Series (hcaptcha, recaptcha2, recaptcha3) returns token:
{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "started_at": 1784885653.0,
  "finished_at": 1784885665.4,
  "elapsed": 12.4,
  "token": "03AFcWeA5kjJyDQ9S1a9UYimR6nuxnpEnAs5x2Pixao0dXZhMB......"
}
  • Recognition Classification (recognition/recaptcha2, recognition/hcaptcha) returns solution; recognition/image2text returns text.

/captcha/tasks is universal for all CAPTCHA interfaces (token and recognition series), and you can poll with the same task_id.

The server continues processing from the time of creation, for a maximum of 120 seconds. If the last query before the deadline still does not yield a result, it will persist an HTTP 504. This status is a terminal state, and the client should stop polling; repeated queries for the same task_id will consistently return the same failure result:

{
  "detail": "The captcha task timed out.",
  "code": "timeout",
  "success": false,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "failed",
  "started_at": 1784885653.0,
  "finished_at": 1784885765.4,
  "elapsed": 112.4
}

Both status: ready and the HTTP 504 terminal response will include timing fields.

  • started_at, the time the task started processing, Unix timestamp (seconds, float).
  • finished_at, the time the task produced results, Unix timestamp (seconds, float). This field will not be returned while still processing.
  • elapsed, the time taken for task processing, in seconds (float, rounded to 3 decimal places). This field will not be returned while still processing.

Billing Instructions

In asynchronous mode, creating tasks and reading "processing" status are not charged; the client is charged once when reading the successful result for the first time (consistent with existing behavior and synchronous mode pricing). The server will autonomously advance the task but will not charge in advance just because the background completes first. Tasks that do not succeed within the 120-second deadline will terminate with HTTP 504 and will not incur charges.

Error Handling

When calling this interface, if an error occurs, it will return the corresponding error code and message. For example:

  • 400 invalid_request: The request is missing the task_id parameter.
  • 401 invalid_token: Unauthorized, the authorization token is invalid or missing.
  • 404 not_found: The task_id does not exist or does not belong to the current account.
  • 504 timeout: The task has been terminated and did not produce results; please stop polling this task_id. This failure will not incur charges.

Error Response Example

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "task not found"
  }
}