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

# Cloudflare Turnstile プロトコル認識 API 接続説明

> Cloudflare Turnstile Captcha Service API guide - Ace Data Cloud

この記事では、Cloudflare Turnstile プロトコル認識 API 接続説明を紹介します。これにより、ユーザーは Turnstile CAPTCHA を認識してクリックすることなく、Website Key を提出するだけでバックエンドで自動的にデコードし、検証を完了できます。

## 申請プロセス

Cloudflare Turnstile プロトコル認識 API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) にアクセスして、API Token を取得し、保管してください。

![](https://cdn.acedata.cloud/dvc3cg.jpg)

まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。

**1つの API Token でプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。** 初回申請時には無料のクレジットが付与され、無料で体験できます。クレジットが不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin) で一般残高をチャージできます。

> 📘 完全なドキュメント：[Cloudflare Turnstile プロトコル認識 API →](https://platform.acedata.cloud/documents/captcha-token-turnstile)

## 基本使用

まず、基本的な使用方法を理解します。これは、処理する必要のある Turnstile CAPTCHA のウェブサイト URL を入力することで、処理された結果を得ることができます。最初に `website_url` フィールドを簡単に渡す必要があります。私たちのサンプルサイトは `https://react-turnstile.vercel.app` です。`website_url` ページで `website_key` を取得する必要があります。まず、このウェブページを開き、F12 を押してコンソールに入り、Element ページで `cf-turnstile` を全体検索すると、Turnstile を含むコンテナ要素が見つかります。その中の `data-sitekey` に対応する文字列が `website_key` の値です。

設定するリクエストヘッダーには以下が含まれます：

* `accept`：受け取りたいレスポンス結果の形式。ここでは `application/json`、つまり JSON 形式を記入します。
* `authorization`：API を呼び出すためのキー。申請後、直接ドロップダウンから選択できます。

さらに、リクエストボディを設定します。これには以下が含まれます：

* `website_url`：処理する CAPTCHA のウェブサイト URL。
* `website_key`：Cloudflare Turnstile におけるウェブサイトのキー識別子（sitekey）。
* `action`：オプションのパラメータ。ターゲットウェブサイトが Turnstile コンポーネントにカスタム `action` を設定している場合のみ渡す必要があります。
* `cdata`：オプションのパラメータ。ターゲットウェブサイトが Turnstile コンポーネントにカスタム `cData` を設定している場合のみ渡す必要があります。

「Try」ボタンをクリックするとテストが行われ、以下の結果が得られます：

```json theme={null}
{
  "token": "0.mNQ2f9uP6mQ0y3H5Q8bqO7iM......",
  "started_at": 1784885653.0,
  "finished_at": 1784885665.4,
  "elapsed": 12.4
}
```

返された結果には複数のフィールドがあり、以下のように説明されます：

* `token`：今回の Cloudflare Turnstile CAPTCHA タスク処理後の検証結果。
* `started_at`、`finished_at`：今回のリクエストが処理を開始し、結果を出力した時間、Unix タイムスタンプ（秒、浮動小数点）。
* `elapsed`：今回の処理にかかった総時間（秒）。

Turnstile CAPTCHA の検証結果を得たことがわかります。これを POST またはターゲットウェブサイトにシミュレートして提出することができ、一度限りの使用で有効期限は 120 秒、60 秒以内の使用を推奨します。提出時には通常、このトークンを `cf-turnstile-response` パラメータとしてターゲットウェブサイトに送信します。トークン検証に対応する Python コードは以下の通りです：

```python theme={null}
import requests

token = '{token}'

data = {
    'cf-turnstile-response': token
}

response = requests.post('https://react-turnstile.vercel.app', data=data)

if response.status_code == 200:
    print(response.text)
```

また、対応する接続コードを生成したい場合は、生成されたものを直接コピーできます。例えば、CURL のコードは以下の通りです：

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/token/turnstile' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_key": "0x4AAAAAAADnPIDROrmt1Wwj",
  "website_url": "https://react-turnstile.vercel.app"
}'
```

Python の接続コードは以下の通りです：

```python theme={null}
import requests

url = "https://api.acedata.cloud/captcha/token/turnstile"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "website_key": "0x4AAAAAAADnPIDROrmt1Wwj",
    "website_url": "https://react-turnstile.vercel.app"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

## 非同期モード（async）

デフォルトでは、API は同期ブロッキングです：1回のリクエストはトークン処理が完了するまで待機します。マルチソルバーのローテーションを行っている場合（multi-solver rotation）、タスクを提出した後にすぐに task\_id を取得し、他のソルバーを調整し、後で結果を読み取ることを希望する場合は、リクエストボディに `async: true` を渡すことができます。

`async: true` を渡すと、インターフェースはすぐに `task_id` を返し、待機することはありません：

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

進捗を確認するには、この `task_id` を使用して `POST /captcha/tasks` をクエリできます（3〜5秒ごとを推奨）。このインターフェースはタスク処理をトリガーしたり進めたりしません。クエリしなくても、ネットワークが切断されても、クライアントを終了しても、サーバーは処理を続けます：

```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` が返され、処理が完了すると `status: ready` とトークンが返されます：

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

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

> 注意：Cloudflare Turnstile は現在、持ち込みプロキシ（Bring Your Own Proxy）をサポートしていないため、このインターフェースは `proxy` パラメータを受け付けません；渡すと `400 invalid_proxy` が返されます。

## エラーハンドリング

API を呼び出す際にエラーが発生した場合、API は対応するエラーコードと情報を返します。例えば：

* `400 token_mismatched`：不正なリクエスト、パラメータが不足しているか無効である可能性があります。
* `400 invalid_proxy`：不正なリクエスト、このキャプチャタイプではプロキシがサポートされていません。
* `401 invalid_token`：未承認、無効または不足している認証トークン。
* `429 too_many_requests`：リクエストが多すぎます、レート制限を超えました。
* `500 api_error`：内部サーバーエラー、サーバーで何かがうまくいきませんでした。

### エラー応答の例

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## 結論

この文書を通じて、Cloudflare Turnstile プロトコルを使用して API を利用し、ユーザーが Turnstile CAPTCHA を認識したりクリックしたりすることなく、Website Key を提出するだけでバックエンドで自動的にデコードし、検証を完了できる方法を理解しました。この文書が、API の接続と使用をより良くする手助けとなることを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。


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