> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

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

> hCaptcha verification code recognition service 集成指南 - Ace Data Cloud

本文介绍验证码异步任务查询接口 `POST /captcha/tasks`。当你在调用任意验证码接口（token 系列或 recognition 系列）时传入 `async: true`，接口会立即返回一个 `task_id`，服务器会立即接管并持续处理；你可以用该 `task_id` 查询最终结果，但查询不是任务继续执行的前提。适用于多打码器轮换（multi-solver rotation）等场景：提交任务后立即拿到 `task_id`，先去调度其他打码器，稍后再回来读取结果。

> 📘 完整交互式文档（含在线调试）：[验证码任务查询 API →](https://platform.acedata.cloud/documents/captcha-tasks)

## 申请流程

要使用本接口，先到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 获取您的 API Token，留作备用。**一个 API Token 即可调用平台所有服务，无需为每个服务单独申请。**

## 基本使用

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

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

```shell theme={null}
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
}'
```

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

### 第二步（可选）：用 task\_id 查询结果

如需主动查看进度，可使用上一步返回的 `task_id` 查询 `POST /captcha/tasks`（建议每 3\~5 秒一次）。本接口不会触发或推进任务处理；读取 ready 结果时沿用现有的一次性结算行为：

```shell theme={null}
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`：

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

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

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

```json theme={null}
{
  "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 分类**（recognition/recaptcha2、recognition/hcaptcha）返回 `solution`；**recognition/image2text** 返回 `text`。

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

服务器从创建时开始持续处理，最长 120 秒。如果到 deadline 的最后一次查询仍未得到结果，会持久化 HTTP 504。该状态是终态，客户端应停止轮询；重复查询同一个 `task_id` 会稳定返回相同的失败结果：

```json theme={null}
{
  "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
}
```

`status: ready` 和 HTTP 504 的终态响应都会带上计时字段。

* `started_at`，任务开始处理时间，Unix 时间戳（秒，浮点）。
* `finished_at`，任务产出结果时间，Unix 时间戳（秒，浮点）。仍在处理中时不返回该字段。
* `elapsed`，任务处理耗时，单位为秒（浮点，保留 3 位小数）。仍在处理中时不返回该字段。

## 计费说明

异步模式下，创建任务和读取「处理中」状态都不计费；**客户端首次读取成功结果时计费一次**（与现有行为及同步模式价格一致）。服务器会自主推进任务，但不会因为后台先完成就提前扣费。120 秒 deadline 内未成功的任务以 HTTP 504 终止且不计费。

## 错误处理

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

* `400 invalid_request`：请求缺少 `task_id` 参数。
* `401 invalid_token`：未授权，授权 Token 无效或缺失。
* `404 not_found`：`task_id` 不存在，或不属于当前账号。
* `504 timeout`：任务已终止且未产生结果；请停止轮询该 `task_id`。该失败不会扣费。

### 错误响应示例

```json theme={null}
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "task not found"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.