# Cloudflare Turnstile

> Lấy token Cloudflare Turnstile bằng YesCaptcha: TurnstileTaskProxyless, TurnstileTaskProxylessM1 và TurnstileTask dùng proxy của bạn, tham số, ví dụ và kết quả trả về; khác biệt với trang thử thách Cloudflare.

Source: https://docs.yescaptcha.com/vi/tasks/turnstile/ · Last verified: 2026-10-21

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/turnstile/

Tác vụ Cloudflare Turnstile trả về một token (`token`), bạn gửi token này cho website đích để vượt qua xác minh. `TurnstileTaskProxyless` có giá 25 điểm (≈ $3.75 / 1k) mỗi tác vụ, trả kết quả bất đồng bộ: gọi `createTask`, sau đó gọi `getTaskResult` mỗi 5 giây. Tác vụ thất bại hoặc quá thời gian sẽ tự động hoàn điểm.

- POST `https://api.yescaptcha.com/createTask` (Endpoint quốc tế)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint Trung Quốc)

Nội dung request là JSON, xác thực bằng `clientKey`. Tạo tác vụ ở endpoint nào thì truy vấn kết quả ở endpoint đó.

## Khi nào dùng

Trang web có khung xác minh của Cloudflare (“Xác nhận bạn là người”) nhúng trong biểu mẫu, và tải script từ `challenges.cloudflare.com/turnstile`.

Nếu toàn bộ trang bị Cloudflare chặn và hiện “Vui lòng đợi…” hoặc “Đang kiểm tra trình duyệt của bạn” thì đó là trang thử thách Cloudflare, không phải Turnstile; hãy dùng [trang thử thách Cloudflare](https://docs.yescaptcha.com/vi/tasks/cloudflare-challenge.md). Cách phân biệt xem [Xác định loại captcha](https://docs.yescaptcha.com/vi/guides/identify-captcha.md).

## Loại tác vụ và giá

| Loại tác vụ | Giá | Cách trả kết quả | Ghi chú |
| --- | --- | --- | --- |
| `TurnstileTaskProxyless` | $3.75 / 1k; 25 điểm/tác vụ · ¥25 / 1k | Bất đồng bộ |  |
| `TurnstileTaskProxylessM1` | $4.50 / 1k; 30 điểm/tác vụ · ¥30 / 1k | Bất đồng bộ |  |
| `TurnstileTask` | $3.75 / 1k; 25 điểm/tác vụ · ¥25 / 1k | Bất đồng bộ | Dùng proxy riêng |

Giá bằng đô la Mỹ chỉ là ước tính theo US$1 ≈ ¥6.67; tác vụ được trừ điểm.

-   `TurnstileTaskProxyless` và `TurnstileTaskProxylessM1` có cùng tham số nhưng khác đường truyền, có thể dùng làm dự phòng cho nhau.
-   `TurnstileTask` dùng proxy của bạn để tải captcha, cần truyền các trường proxy.

## Tham số request

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `type` | string | Có | Loại tác vụ; xem "Loại tác vụ và giá" trên trang này |
| `websiteURL` | string | Có | URL đầy đủ của trang hiển thị captcha. Điền trang web nơi bạn thấy captcha, không điền tên miền của nhà cung cấp captcha |
| `websiteKey` | string | Có | Khóa trang web (sitekey) của Turnstile, thường bắt đầu bằng 0x |
| `pageAction` | string | Không | Giá trị `action` mà trang truyền cho Turnstile (tùy chọn của `turnstile.render`, hoặc `data-action` trên phần tử widget), ví dụ `login`. Hầu hết trường hợp không cần; chỉ thêm khi tác vụ liên tục thất bại |
| `data` | string | Không | Giá trị `cData` mà trang truyền cho Turnstile (tùy chọn của `turnstile.render`, hoặc `data-cdata` trên phần tử widget), ví dụ `c0bd4b36-7419-4e18-83c6-378699f2a9a2`. Hầu hết trường hợp không cần; chỉ thêm khi tác vụ liên tục thất bại |
| `proxyType` | string | Một số loại | Giao thức proxy: `http`, `https`, `socks4` hoặc `socks5` (Bắt buộc với TurnstileTask) |
| `proxyAddress` | string | Một số loại | Địa chỉ IP hoặc tên máy chủ của proxy. Địa chỉ cục bộ hoặc nội bộ như 127.0.0.1 hay 192.168.x.x sẽ không hoạt động vì máy chủ của chúng tôi không truy cập được (Bắt buộc với TurnstileTask) |
| `proxyPort` | integer | Một số loại | Cổng proxy (Bắt buộc với TurnstileTask) |
| `proxyLogin` | string | Không | Tên người dùng proxy, nếu proxy yêu cầu xác thực (chỉ TurnstileTask) |
| `proxyPassword` | string | Không | Mật khẩu proxy, nếu proxy yêu cầu xác thực (chỉ TurnstileTask) |
| `userAgent` | string | Không | User-Agent của trình duyệt. Nếu kết quả có `userAgent`, hãy dùng giá trị đó khi gửi token (chỉ TurnstileTask) |

`websiteKey` thường bắt đầu bằng `0x`. Cách tìm xem [Tìm tham số Turnstile](https://docs.yescaptcha.com/vi/guides/find-turnstile-parameters.md).

### Khi chắc chắn vẫn không vượt qua: pageAction và data

Trong hầu hết trường hợp chỉ cần `websiteURL` và `websiteKey`, không cần hai tham số này. Nếu bạn chắc chắn `websiteURL` và `websiteKey` đúng mà tác vụ vẫn không vượt qua, hãy kiểm tra xem trang web có truyền `action` và `cData` khi gọi Turnstile không (tham số của `turnstile.render`, hoặc `data-action`, `data-cdata` trên phần tử khung xác minh). Nếu có, truyền nguyên giá trị:

-   `pageAction`: điền `action` của trang, ví dụ `login`
-   `data`: điền `cData` của trang, ví dụ `c0bd4b36-7419-4e18-83c6-378699f2a9a2`

POST https://api.yescaptcha.com/createTask

```json
{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "TurnstileTaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "0x4AAAAAAA_SITE_KEY",
    "pageAction": "login",
    "data": "c0bd4b36-7419-4e18-83c6-378699f2a9a2"
  }
}
```

## Ví dụ request

POST https://api.yescaptcha.com/createTask

```json
{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "TurnstileTaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "0x4AAAAAAA_SITE_KEY"
  }
}
```

**curl**

```bash
curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "TurnstileTaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "0x4AAAAAAA_SITE_KEY"
  }
}'

# Returns {"errorId":0,"taskId":"..."}; then poll every 5 seconds:
curl -s https://api.yescaptcha.com/getTaskResult \
  -H 'Content-Type: application/json' \
  -d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'
```

**Python**

solve.py

```python
import os
import time

import requests

API = "https://api.yescaptcha.com"
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]  # Read the clientKey from an environment variable

def call(method, payload):
    r = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30)
    data = r.json()
    if data.get("errorId"):
        raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
    return data

def solve(task):
    task_id = call("createTask", {"task": task})["taskId"]
    for _ in range(36):  # Poll every 5 seconds, for up to about 3 minutes
        time.sleep(5)
        result = call("getTaskResult", {"taskId": task_id})
        if result.get("status") == "ready":
            return result["solution"]
    raise TimeoutError(task_id)

solution = solve({
    "type": "TurnstileTaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "0x4AAAAAAA_SITE_KEY",
})
print(solution["token"])
```

**Node.js**

solve.mjs

```js
const API = 'https://api.yescaptcha.com';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY; // Read the clientKey from an environment variable

async function call(method, payload) {
  const res = await fetch(`${API}/${method}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ clientKey: CLIENT_KEY, ...payload }),
  });
  const data = await res.json();
  if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
  return data;
}

async function solve(task) {
  const { taskId } = await call('createTask', { task });
  for (let i = 0; i < 36; i++) { // Poll every 5 seconds, for up to about 3 minutes
    await new Promise((r) => setTimeout(r, 5000));
    const result = await call('getTaskResult', { taskId });
    if (result.status === 'ready') return result.solution;
  }
  throw new Error(`timeout: ${taskId}`);
}

const solution = await solve({
  type: "TurnstileTaskProxyless",
  websiteURL: "https://example.com/login",
  websiteKey: "0x4AAAAAAA_SITE_KEY",
});
console.log(solution.token);
```

Thay `websiteURL`, `websiteKey` bằng giá trị của website đích.

## Kết quả trả về

```json
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "0.ufq5RgSVZd11DPSX1brdrxnEs28KcVlKj2ORchqxSy2q9yAW6ciq3hriXDF4x...",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36"
  }
}
```

| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `token` | string | Token cần gửi cho website đích. Chỉ dùng một lần; nên gửi càng sớm càng tốt |
| `userAgent` | string | User-Agent đã dùng để lấy token. Hãy dùng giá trị này khi gửi token, kể cả khi nó khác với giá trị bạn đã gửi |

Điền `token` vào trường `cf-turnstile-response` của trang (hoặc trường mà API của website đích yêu cầu) rồi gửi đi; request gửi đi dùng `userAgent` được trả về làm User-Agent.

Khi đang xử lý, kết quả là `{"errorId": 0, "status": "processing"}`, hãy truy vấn lại sau 5 giây. Khi có lỗi, xử lý theo `errorCode`, xem [Mã lỗi](https://docs.yescaptcha.com/vi/api/errors.md).

## Câu hỏi thường gặp

### Token có hiệu lực trong bao lâu?

Chỉ dùng một lần, nên gửi ngay sau khi nhận được (token Turnstile thường hết hạn sau vài phút, do Cloudflare quyết định).

### Gửi xong website vẫn không chấp nhận?

Kiểm tra `websiteURL` là trang có khung xác minh và `websiteKey` đúng, đồng thời dùng `userAgent` được trả về khi gửi. Nếu trang có truyền `action` và `cData`, hãy thêm chúng vào dưới dạng `pageAction` và `data`, xem [Khi chắc chắn vẫn không vượt qua](#if-tasks-keep-failing-pageaction-and-data) ở trên. Nếu website còn kiểm tra IP, hãy dùng `TurnstileTask` và gửi qua cùng một proxy.

## Hướng dẫn liên quan

-   [Xác định loại captcha](https://docs.yescaptcha.com/vi/guides/identify-captcha.md)
-   [Tìm tham số Turnstile](https://docs.yescaptcha.com/vi/guides/find-turnstile-parameters.md)