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

# CAPTCHAタスククエリAPI（サーバーサイド非同期タスク）接続説明

> hCaptcha verification code recognition service API guide - Ace Data Cloud

この記事では、CAPTCHA非同期タスククエリインターフェース `POST /captcha/tasks` を紹介します。任意のCAPTCHAインターフェース（トークンシリーズまたは認識シリーズ）を呼び出す際に `async: true` を渡すと、インターフェースはすぐに `task_id` を返し、サーバーがすぐに処理を引き継ぎます。あなたはその `task_id` を使って最終結果をクエリできますが、クエリはタスクの継続実行の前提ではありません。これはマルチソルバー回転（multi-solver rotation）などのシナリオに適しています：タスクを提出した後、すぐに `task_id` を取得し、他のソルバーを調整し、後で結果を読み取ることができます。

> 📘 完全なインタラクティブドキュメント（オンラインデバッグを含む）：[CAPTCHAタスククエリAPI →](https://platform.acedata.cloud/documents/captcha-tasks)

## 申請プロセス

このインターフェースを使用するには、まず [Ace Data Cloudコンソール](https://platform.acedata.cloud/console/applications) にアクセスしてAPIトークンを取得し、予備として保管してください。**1つのAPIトークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。**

## 基本的な使用法

### ステップ1：非同期方式でタスクを作成

任意のCAPTCHAインターフェースのリクエストボディに `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"
}
```

### ステップ2（オプション）：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` と対応する結果フィールドが返されます——フィールド構造は同期モードと完全に一致します：

* **トークンシリーズ**（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/recaptcha2、recognition/hcaptcha）は `solution` を返します；**recognition/image2text** は `text` を返します。

`/captcha/tasks` はすべてのCAPTCHAインターフェース（トークンおよび認識シリーズ）に共通で、同じ `task_id` でポーリングできます。

サーバーは作成時から処理を継続し、最長120秒です。デッドラインの最後のクエリで結果が得られない場合、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桁の小数点以下を保持）。処理中の場合はこのフィールドは返されません。

## 課金説明

非同期モードでは、タスクの作成と「処理中」状態の読み取りは課金されません；**クライアントが初めて成功した結果を読み取るときに1回課金されます**（既存の動作および同期モードの価格と一致）。サーバーはタスクを自動的に進めますが、バックグラウンドで先に完了しても早期に課金されることはありません。120秒のデッドライン内に成功しなかったタスクはHTTP 504で終了し、課金されません。

## エラー処理

このインターフェースを呼び出す際にエラーが発生した場合、対応するエラーコードと情報が返されます。例えば：

* `400 invalid_request`：リクエストに `task_id` パラメータが欠けています。
* `401 invalid_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.