> ## 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 整合指南 - Ace Data Cloud

本文將介紹一種 Cloudflare Turnstile 協議識別 API 對接說明，它可讓用戶無需識別和點選 Turnstile 驗證碼，僅需通過提交 Website Key 即可實現後台自動解碼，完成驗證。

## 申請流程

要使用 Cloudflare Turnstile 協議識別 API，首先到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 獲取您的 API Token，留作備用。

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

如果你尚未登錄或註冊，會自動跳轉到登錄頁面邀請你註冊和登錄，完成後會自動返回當前頁面。

**一個 API Token 即可調用平台所有服務，無需為每個服務單獨申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 充值通用餘額。

> 📘 完整文檔：[Cloudflare Turnstile 協議識別 API →](https://platform.acedata.cloud/documents/captcha-token-turnstile)

## 基本使用

首先先了解下基本的使用方式，就是輸入需要處理 Turnstile 驗證碼的網站 URL，便可獲得處理後的結果，首先需要簡單地傳遞一個 `website_url` 字段，我們的示例網站是：`https://react-turnstile.vercel.app`，我們需要在 `website_url` 頁面中獲取 `website_key`，首先需要打開這個網頁，按 F12 進入控制台，在 Element 頁面進行全局搜索 `cf-turnstile`，可以找到承載 Turnstile 的容器元素，其中 `data-sitekey` 對應的一串字符串便是 `website_key` 的值。

設置的 Request Headers 包括：

* `accept`：想要接收怎樣格式的響應結果，這裡填寫為 `application/json`，即 JSON 格式。
* `authorization`：調用 API 的密鑰，申請之後可以直接下拉選擇。

另外設置了 Request Body，包括：

* `website_url`：需要處理驗證碼的網站 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 驗證碼任務處理後的驗證結果。
* `started_at`、`finished_at`：本次請求開始處理與產出結果的時間，Unix 時間戳（秒，浮點）。
* `elapsed`：本次處理的總耗時（秒）。

可以看到我們得到了處理 Turnstile 驗證碼的驗證結果，然後我們可以用於 POST 或模擬提交給目標網站，一次性使用，有效期 120s，建議在 60s 內使用。提交時通常將該 token 作為 `cf-turnstile-response` 參數一併發送到目標網站，調用 token 驗證所對應的 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 是同步阻塞的：一次請求會一直等待，直到 token 處理完成才返回。如果你在做多打碼器輪換（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` 和 token：

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

計費說明：非同步模式下，創建任務和讀取「處理中」狀態都不計費；**客戶端首次讀取成功結果時計費一次**（與現有行為及同步模式價格一致）。伺服器會自主推進任務，但不會因為後台先完成就提前扣費。任務在 120 秒內未成功會終止為 HTTP 504 `timeout`，不計費。`/captcha/tasks` 不負責推進任務。

> 說明：Cloudflare Turnstile 暫不支持自帶代理（Bring Your Own Proxy），因此本接口不接受 `proxy` 參數；如傳入會返回 `400 invalid_proxy`。

## 錯誤處理

在調用 API 時，如果遇到錯誤，API 會返回相應的錯誤代碼和信息。例如：

* `400 token_mismatched`：錯誤的請求，可能是因為缺少或無效的參數。
* `400 invalid_proxy`：錯誤的請求，該 captcha 類型不支持代理。
* `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 驗證碼，僅需通過提交 Website Key 即可實現後台自動解碼，完成驗證。希望本文檔能幫助您更好地對接和使用該 API。如有任何問題，請隨時聯繫我們的技術支持團隊。


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