# hCaptcha

> Lấy token hCaptcha bằng YesCaptcha: HCaptchaTaskProxyless, HCaptchaTaskProxylessM1 và HCaptchaTask dùng proxy riêng, cách điền userAgent, rqdata và cách dùng respKey trả về.

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

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

Tác vụ hCaptcha trả về một token (`gRecaptchaResponse`). Gửi token này cùng `userAgent` được trả về (đôi khi có thêm `respKey`) tới website đích là qua được bước xác minh. `HCaptchaTaskProxyless` tính 30 điểm (≈ $4.50 / 1k) mỗi tác vụ, `HCaptchaTask` dùng proxy riêng tính 15 điểm (≈ $2.25 / 1k) mỗi tác vụ; cả hai đều bất đồng bộ: gọi `createTask`, sau đó polling `getTaskResult` mỗi 5 giây. Nhận dạng thất bại hoặc hết 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ó hộp kiểm “Tôi là con người” của hCaptcha, hoặc hiện câu hỏi hình ảnh của hCaptcha. Muốn lấy token để gửi trực tiếp thì dùng các loại tác vụ trong trang này; muốn tự bấm vào hình ảnh trong trình duyệt thì dùng [nhận dạng hình ảnh hCaptcha](https://docs.yescaptcha.com/vi/tasks/hcaptcha-classification.md).

> **Ghi chú:** Tỷ lệ vượt qua của hCaptcha chênh lệch nhiều giữa các website, nên thử với một lô nhỏ trước.

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

| Loại tác vụ | Giá | Cách trả kết quả | Ghi chú |
| --- | --- | --- | --- |
| `HCaptchaTaskProxyless` | $4.50 / 1k; 30 điểm/tác vụ · ¥30 / 1k | Bất đồng bộ |  |
| `HCaptchaTaskProxylessM1` | $4.50 / 1k; 30 điểm/tác vụ · ¥30 / 1k | Bất đồng bộ | Cùng tham số với HCaptchaTaskProxyless nhưng đi qua tuyến khác; có thể dùng cái này làm dự phòng cho cái kia |
| `HCaptchaTask` | $2.25 / 1k; 15 điểm/tác vụ · ¥15 / 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.

-   `HCaptchaTaskProxyless` và `HCaptchaTaskProxylessM1` có tham số giống nhau, khác đường truyền, có thể dùng làm dự phòng cho nhau.
-   `HCaptchaTask` tải captcha qua proxy riêng của bạn, cần truyền các trường proxy; dùng khi website đích kiểm tra IP truy cập.

## 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 hCaptcha, thường có định dạng UUID |
| `userAgent` | string | Không | User-Agent của trình duyệt. Nên điền, nhưng chỉ chấp nhận giá trị do `GET https://api.yescaptcha.com/useragent` trả về; hãy gửi token cùng với `userAgent` trong kết quả |
| `isInvisible` | boolean | Không | Đặt là true cho phiên bản ẩn (invisible); nếu không thì bỏ qua |
| `rqdata` | string | Không | rqdata của hCaptcha enterprise; một số trang web yêu cầu và thường tìm thấy trong request tải captcha |
| `proxyType` | string | Một số loại | Giao thức proxy: `http`, `https`, `socks4` hoặc `socks5` (Bắt buộc với HCaptchaTask) |
| `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 HCaptchaTask) |
| `proxyPort` | integer | Một số loại | Cổng proxy (Bắt buộc với HCaptchaTask) |
| `proxyLogin` | string | Không | Tên người dùng proxy, nếu proxy yêu cầu xác thực (chỉ HCaptchaTask) |
| `proxyPassword` | string | Không | Mật khẩu proxy, nếu proxy yêu cầu xác thực (chỉ HCaptchaTask) |

-   `websiteURL` điền trang web hiển thị captcha, **không phải** hcaptcha.com.
-   `userAgent` nên điền, chỉ được dùng giá trị do [/useragent](https://docs.yescaptcha.com/vi/api/useragent.md) trả về.
-   `rqdata`: hCaptcha bản Enterprise (ví dụ một số website mạng xã hội, chat) yêu cầu tham số này, thường tìm thấy trong request tải captcha. Website thông thường thì không truyền.

Cách tìm tham số: xem [Tìm tham số hCaptcha](https://docs.yescaptcha.com/vi/guides/find-hcaptcha-parameters.md).

## Ví dụ request

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

```json
{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
  }
}
```

**curl**

```bash
curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
  }
}'

# 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": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
})
print(solution["gRecaptchaResponse"])
```

**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: "HCaptchaTaskProxyless",
  websiteURL: "https://accounts.hcaptcha.com/demo",
  websiteKey: "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
});
console.log(solution.gRecaptchaResponse);
```

Dùng proxy riêng:

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

```json
{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaTask",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
    "proxyType": "http",
    "proxyAddress": "proxy.example.com",
    "proxyPort": 8080,
    "proxyLogin": "user",
    "proxyPassword": "pass"
  }
}
```

## Kết quả trả về

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

| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `gRecaptchaResponse` | string | Token cần gửi cho website đích. Chỉ dùng một lần, có hiệu lực khoảng 120 giây; nên dùng trong vòng 60 giây |
| `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 |
| `respKey` | string | Giá trị mà một số website yêu cầu gửi cùng với token; nếu có thì hãy gửi kèm |

Khi gửi:

1.  Điền token vào trường `h-captcha-response` của trang (và `g-recaptcha-response`, nếu có), hoặc vào trường mà API của website đích yêu cầu.
2.  Khi gửi request, dùng `userAgent` được trả về làm User-Agent.
3.  Nếu có trả về `respKey`, gửi kèm theo yêu cầu của website.

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

### Vì sao tỷ lệ vượt qua không ổn định?

hCaptcha đánh giá dựa trên cài đặt của website, IP truy cập và môi trường trình duyệt, nên tỷ lệ vượt qua khác nhau tùy website. Hãy chắc chắn đã dùng `userAgent` được trả về; với website nhạy cảm về IP, dùng `HCaptchaTask` với proxy riêng và khi gửi cũng đi qua cùng proxy đó; cũng có thể đổi sang `HCaptchaTaskProxylessM1` để so sánh.

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

Chỉ dùng một lần, có hiệu lực khoảng 120 giây, nên gửi càng sớm càng tốt sau khi nhận.

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

-   [Tìm tham số hCaptcha](https://docs.yescaptcha.com/vi/guides/find-hcaptcha-parameters.md)
-   [Nhận dạng hình ảnh hCaptcha và mô phỏng bấm chuột (Selenium)](https://docs.yescaptcha.com/vi/guides/hcaptcha-click-selenium.md)