> ## 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.