> ## 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`：Bad request, possibly due to missing or invalid parameters.
* `400 invalid_proxy`：Bad request, proxy is not supported for this captcha type.
* `401 invalid_token`：Unauthorized, invalid or missing authorization token.
* `429 too_many_requests`：Too many requests, you have exceeded the rate limit.
* `500 api_error`：Internal server error, something went wrong on the server.

### 错误响应示例

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