验证码任务查询 API（异步轮询）对接说明

本文介绍验证码异步任务查询接口 POST /captcha/tasks。当你在调用任意验证码接口（token 系列或 recognition 系列）时传入 async: true，接口会立即返回一个 task_id，随后即可用该 task_id 轮询本接口获取最终结果。适用于多打码器轮换（multi-solver rotation）等场景：提交任务后立即拿到 task_id，先去调度其他打码器，稍后再回来取结果。

📘 完整交互式文档（含在线调试）：验证码任务查询 API →

¶ 申请流程

要使用本接口，先到 Ace Data Cloud 控制台获取您的 API Token，留作备用。一个 API Token 即可调用平台所有服务，无需为每个服务单独申请。

¶ 基本使用

¶ 第一步：以异步方式创建任务

在任意验证码接口的请求体中传入 async: true，接口会立即返回 task_id（HTTP 201），而不会阻塞等待：

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"
}

¶ 第二步：用 task_id 轮询结果

使用上一步返回的 task_id 轮询 POST /captcha/tasks（建议每 3~5 秒一次）：

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"
}'

处理中会返回 status: processing：

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

处理完成会返回 status: ready 及对应结果字段——字段结构与同步模式完全一致：

token 系列（hcaptcha、recaptcha2、recaptcha3）返回 token：

{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "token": "03AFcWeA5kjJyDQ9S1a9UYimR6nuxnpEnAs5x2Pixao0dXZhMB......"
}

recognition 分类（recognition/recaptcha2、recognition/hcaptcha）返回 solution；recognition/image2text 返回 text。

/captcha/tasks 对所有验证码接口（token 与 recognition 系列）通用，用同一个 task_id 轮询即可。

¶ 计费说明

异步模式下，创建任务与轮询「处理中」都不计费；仅在成功取到结果时计费一次（与同步模式的价格一致）。因此在轮换中取消尚未完成的任务不会产生费用。

¶ 错误处理

在调用本接口时，如果遇到错误，会返回相应的错误代码和信息。例如：

400 invalid_request：请求缺少 task_id 参数。
401 invalid_token：未授权，授权 Token 无效或缺失。
404 not_found：task_id 不存在，或不属于当前账号。

¶ 错误响应示例

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