# YesCaptcha Docs (full text)
> YesCaptcha là API nhận dạng captcha. Dùng một API JSON để giải reCAPTCHA, hCaptcha, Cloudflare Turnstile, FunCaptcha, AWS WAF và captcha hình ảnh, trừ điểm theo từng tác vụ; tác vụ thất bại hoặc quá thời gian sẽ tự động hoàn điểm.
---
# Giải captcha bằng một API JSON
> YesCaptcha là API nhận dạng captcha. Dùng một API JSON để giải reCAPTCHA, hCaptcha, Cloudflare Turnstile, FunCaptcha, AWS WAF và captcha hình ảnh, trừ điểm theo từng tác vụ; tác vụ thất bại hoặc quá thời gian sẽ tự động hoàn điểm.
Source: https://docs.yescaptcha.com/vi/ · 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/
[API nhận dạng captchaTrạng thái](https://status.yescaptcha.com/?lang=en)
Giải reCAPTCHA, hCaptcha, Cloudflare Turnstile, FunCaptcha, AWS WAF và captcha hình ảnh chữ-số. Trừ điểm theo từng tác vụ, 1,000 điểm = ¥1; tác vụ thất bại hoặc quá thời gian sẽ tự động hoàn điểm.
[Bắt đầu nhanh](https://docs.yescaptcha.com/vi/getting-started/quickstart.md)[Tham chiếu API](https://docs.yescaptcha.com/vi/api/overview.md)
Phiên bản dành cho AI và chương trình:[llms.txt](https://docs.yescaptcha.com/vi/llms.txt)[llms-full.txt](https://docs.yescaptcha.com/vi/llms-full.txt)[OpenAPI](https://docs.yescaptcha.com/openapi.json)[Markdown](https://docs.yescaptcha.com/vi/index.md)
YesCaptcha chỉ được dùng cho mục đích hợp pháp, nghiêm cấm dùng vào mục đích bất hợp pháp.
POSTapi.yescaptcha.com/createTask
```
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}
```
1. /createTasktaskId 61138bb6-19fb-11ec-a9c8-0242ac110006
2. /getTaskResultprocessing
3. /getTaskResultprocessing
4. /getTaskResultready
5. gRecaptchaResponse03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU...
1. 1Tạo tác vụ
2. 2Lấy kết quả
3. 3Gửi
Ví dụ: reCAPTCHA v2, gọi lại để lấy kết quả mỗi 5 giây
Từ $0.30 / 1k
Giá thấp nhất mỗi tác vụ
1,000 điểm = ¥1
Tác vụ thất bại hoặc hết thời gian được hoàn điểm
2 endpoint
Endpoint quốc tế và endpoint Trung Quốc
9:00–21:00
Hỗ trợ trực tiếp (UTC+8)
[Bắt đầu nhanhĐăng ký, lấy clientKey và gửi yêu cầu đầu tiên trong 5 phút](https://docs.yescaptcha.com/vi/getting-started/quickstart.md)[Tham chiếu APIcreateTask, getTaskResult, mã lỗi và giới hạn đồng thời](https://docs.yescaptcha.com/vi/api/overview.md)[Loại tác vụ và giáGiá, cách trả kết quả và tham số của mọi loại tác vụ công khai](https://docs.yescaptcha.com/vi/tasks.md)[Tiện ích trình duyệtKhông cần viết code, tự động xác minh trên trang web](https://docs.yescaptcha.com/vi/extension.md)
## Captcha được hỗ trợ
[01reCAPTCHAv2, v3, bản Enterprise và nhận dạng hình ảnh v2Từ $0.90 / 1k](https://docs.yescaptcha.com/vi/tasks/recaptcha-v2.md)[02hCaptchaTrả về token, hoặc nhận dạng hình ảnh rồi tự nhấpTừ $1.20 / 1k](https://docs.yescaptcha.com/vi/tasks/hcaptcha.md)[03Cloudflare TurnstileToken xác minh của TurnstileTừ $3.75 / 1k](https://docs.yescaptcha.com/vi/tasks/turnstile.md)[04FunCaptchaNhận dạng câu hỏi hình ảnh của Arkose Labs, hỗ trợ mọi dạng câu hỏiTừ $0.45 / 1k](https://docs.yescaptcha.com/vi/tasks/funcaptcha-classification.md)[05AWS WAF / bCaptchaNhận dạng hình ảnh lưới 3×3Từ $1.20 / 1k](https://docs.yescaptcha.com/vi/tasks/aws-bcaptcha-classification.md)[06Hình ảnh chữ-sốCaptcha ký tự thông thường, trả kết quả đồng bộTừ $0.30 / 1k](https://docs.yescaptcha.com/vi/tasks/image-to-text.md)
## Tích hợp ba bước
1. 01
**Tạo tác vụ**
Dùng `createTask` gửi loại tác vụ và tham số của trang web, nhận về `taskId`. Các loại đồng bộ như nhận dạng hình ảnh, hình ảnh chữ-số trả kết quả ngay.
2. 02
**Lấy kết quả**
Cứ 5 giây gọi `getTaskResult` một lần; khi `status` chuyển thành `ready`, kết quả nằm trong `solution`.
3. 03
**Gửi cho trang web đích**
Điền token nhận được vào biểu mẫu hoặc yêu cầu của trang web. Token chỉ dùng một lần, nên dùng trong vòng 60 giây.
POST /createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}
```
POST /getTaskResult
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
}
}
```
## Lối tắt thường dùng
- [**Mã lỗi**Ý nghĩa của từng mã lỗi và cách xử lý](https://docs.yescaptcha.com/vi/api/errors.md)
- [**Giới hạn đồng thời và tự động tạm dừng**Điều gì xảy ra khi vượt giới hạn hoặc có quá nhiều lỗi](https://docs.yescaptcha.com/vi/api/rate-limits.md)
- [**Tính phí và hoàn điểm**Điểm, trừ điểm trước, hoàn điểm và hoàn điểm sau khi báo cáo](https://docs.yescaptcha.com/vi/getting-started/billing.md)
- [**Liên hệ**WeChat, QQ, Telegram, email; giờ phục vụ 9:00–21:00 (UTC+8)](https://docs.yescaptcha.com/vi/help/contact.md)
- [**Bảng điều khiển**Đăng ký, lấy clientKey, nạp tiền](https://yescaptcha.com/)
---
# Giới thiệu
> YesCaptcha là gì. Giải reCAPTCHA, hCaptcha, Turnstile, FunCaptcha và captcha hình ảnh qua API hoặc tiện ích trình duyệt, trừ điểm theo từng tác vụ, tác vụ thất bại được hoàn điểm tự động.
Source: https://docs.yescaptcha.com/vi/getting-started/introduction/ · 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/getting-started/introduction/
YesCaptcha là dịch vụ nhận dạng captcha. Bạn gửi thông tin của captcha đến API của YesCaptcha và nhận lại token để gửi thẳng cho trang web đích, hoặc kết quả nhận dạng của hình ảnh. Hỗ trợ reCAPTCHA (v2, v3 và Enterprise), hCaptcha, Cloudflare Turnstile, trang thử thách Cloudflare, FunCaptcha, AWS WAF, bCaptcha và captcha hình ảnh chữ và số. Điểm được trừ theo từng tác vụ, 1,000 điểm = ¥1; tác vụ nhận dạng thất bại hoặc hết thời gian chờ sẽ được hoàn điểm tự động.
YesCaptcha chỉ được dùng cho mục đích hợp pháp. Nghiêm cấm mọi hành vi sử dụng trái pháp luật.
## Hai cách sử dụng
| | API | Tiện ích trình duyệt (YesCaptcha Assistant) |
| --- | --- | --- |
| Phù hợp với | Nhà phát triển biết viết code, xử lý hàng loạt trong chương trình | Người không viết code, làm việc ngay trong trình duyệt |
| Cách dùng | Dùng `clientKey` để gọi `createTask`, `getTaskResult` | Cài tiện ích, nhập `clientKey`; gặp captcha sẽ tự động nhận dạng và nhấp |
| Hỗ trợ | Tất cả các loại tác vụ được liệt kê trên trang này | Câu hỏi hình ảnh và captcha ký tự của reCAPTCHA v2, hCaptcha, FunCaptcha, AWS WAF, bCaptcha |
| Chi phí | Trừ điểm theo loại tác vụ | Tiện ích miễn phí, trừ điểm theo các lệnh gọi API mà tiện ích sử dụng |
Cả hai cách dùng chung một tài khoản, một `clientKey` và một số dư.
## Ba loại kết quả
- **token**: hầu hết các loại tác vụ của reCAPTCHA, hCaptcha, Turnstile, FunCaptcha. Trả về một chuỗi, điền vào biểu mẫu hoặc yêu cầu của trang web là vượt qua xác minh, không cần nhấp vào hình ảnh. Tất cả đều bất đồng bộ: tạo tác vụ trước, sau đó cứ 5 giây gọi lại `getTaskResult` một lần để lấy kết quả (polling).
- **Kết quả nhận dạng hình ảnh**: các loại có tên kết thúc bằng `Classification`. Bạn gửi hình ảnh của captcha, kết quả trả về là những ô hoặc vị trí cần nhấp, chương trình của bạn tự nhấp trong trình duyệt. Trả về đồng bộ, một yêu cầu là có kết quả.
- **Văn bản hoặc Cookie**: nhận dạng hình ảnh chữ và số trả về văn bản trong hình; trang thử thách Cloudflare trả về Cookie sau khi vượt qua xác minh.
Toàn bộ các loại tác vụ và giá xem tại [Loại tác vụ và giá](https://docs.yescaptcha.com/vi/tasks.md).
## Bắt đầu từ đây
[Bắt đầu nhanh](https://docs.yescaptcha.com/vi/getting-started/quickstart.md)Đăng ký, lấy clientKey, gửi yêu cầu đầu tiên
[Địa chỉ truy cập](https://docs.yescaptcha.com/vi/getting-started/endpoints.md)Endpoint quốc tế và endpoint Trung Quốc
[Tính phí và hoàn điểm](https://docs.yescaptcha.com/vi/getting-started/billing.md)Điểm, trừ điểm trước, hoàn điểm, hoàn điểm sau khi báo cáo
[Tiện ích trình duyệt](https://docs.yescaptcha.com/vi/extension.md)Không cần viết code, tự động nhận dạng ngay trong trình duyệt
## SDK cộng đồng
SDK do người dùng đóng góp, không phải chính thức, hãy tự đánh giá trước khi sử dụng: xem [Mã mẫu và SDK](https://docs.yescaptcha.com/vi/samples.md).
---
# Bắt đầu nhanh
> Gửi yêu cầu YesCaptcha đầu tiên trong 5 phút: đăng ký, sao chép clientKey, nạp tiền, rồi nhận dạng một ảnh captcha bằng curl, Python hoặc Node.js (ImageToTextTaskOcrBase, trả kết quả đồng bộ, 2 điểm mỗi lần).
Source: https://docs.yescaptcha.com/vi/getting-started/quickstart/ · 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/getting-started/quickstart/
Trang này gửi yêu cầu đầu tiên bằng loại tác vụ đơn giản nhất là `ImageToTextTaskOcrBase` (nhận dạng chữ cái và chữ số trong ảnh). Loại này chạy đồng bộ: chỉ một yêu cầu `createTask` là có kết quả, mỗi lần 2 điểm (≈ $0.30 / 1k), không phụ thuộc trang web bên thứ ba, nên rất phù hợp để kiểm tra tài khoản và code đã hoạt động đúng chưa.
1. **Đăng ký tài khoản**
Mở [yescaptcha.com](https://yescaptcha.com/), đăng ký rồi đăng nhập.
2. **Sao chép clientKey**
Sau khi đăng nhập, vào bảng điều khiển ([yescaptcha.com/dashboard.html](https://yescaptcha.com/dashboard.html)), tìm mục «ClientKey của bạn» rồi bấm sao chép. Hãy sao chép đầy đủ.
> **Chú ý:** Mọi yêu cầu API đều được xác thực bằng clientKey, ai có nó cũng có thể dùng số dư của bạn. Đừng gửi cho người khác, cũng đừng ghi vào code công khai; nếu bị lộ, bạn có thể đặt lại ở cùng vị trí đó.
3. **Nạp tiền**
Số dư phải lớn hơn 10 điểm thì mới tạo được tác vụ. Các cách nạp tiền và điểm thưởng VIP xem tại [Nạp tiền và VIP](https://docs.yescaptcha.com/vi/account/recharge.md).
4. **Kiểm tra clientKey có dùng được không**
`getBalance` truy vấn số dư và không trừ điểm:
```bash
curl -s https://api.yescaptcha.com/getBalance \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY"}'
```
Nếu trả về `{"errorId": 0, "balance": 12345, ...}` nghĩa là đã dùng được, `balance` là số điểm còn lại. Nếu trả về `ERROR_KEY_DOES_NOT_EXIST` nghĩa là bạn đã sao chép sai khóa.
5. **Nhận dạng một ảnh**
Tải ảnh mẫu [captcha.jpg](https://docs.yescaptcha.com/samples/captcha.jpg) (bạn cũng có thể dùng ảnh captcha của riêng mình), đặt clientKey vào biến môi trường rồi chạy:
```bash
export YESCAPTCHA_CLIENT_KEY=your_client_key
```
**curl**
quickstart.sh
```bash
#!/usr/bin/env bash
# First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase (synchronous, 2 points per image)
# Usage: YESCAPTCHA_CLIENT_KEY=your_client_key bash quickstart.sh captcha.png
set -euo pipefail
IMAGE="${1:-captcha.png}"
BODY=$(base64 < "$IMAGE" | tr -d '\n') # no "data:" prefix, no line breaks
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d "{\"clientKey\": \"${YESCAPTCHA_CLIENT_KEY}\", \"task\": {\"type\": \"ImageToTextTaskOcrBase\", \"body\": \"${BODY}\"}}"
echo
```
**Python**
quickstart.py
```python
"""First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase
(synchronous, 2 points per image).
Usage:
export YESCAPTCHA_CLIENT_KEY=your_client_key
python quickstart.py captcha.png
"""
import base64
import os
import sys
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
image_path = sys.argv[1] if len(sys.argv) > 1 else "captcha.png"
with open(image_path, "rb") as f:
body = base64.b64encode(f.read()).decode() # no "data:" prefix
r = requests.post(
"https://api.yescaptcha.com/createTask",
json={
"clientKey": CLIENT_KEY,
"task": {"type": "ImageToTextTaskOcrBase", "body": body},
},
timeout=30,
)
data = r.json()
if data.get("errorId"):
raise SystemExit(f"{data.get('errorCode')}: {data.get('errorDescription')}")
print("text:", data["solution"]["text"])
```
**Node.js**
quickstart.mjs
```js
// First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase (synchronous, 2 points per image).
// Usage: YESCAPTCHA_CLIENT_KEY=your_client_key node quickstart.mjs captcha.png
import { readFileSync } from 'node:fs';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;
const body = readFileSync(process.argv[2] ?? 'captcha.png').toString('base64'); // no "data:" prefix
const res = await fetch('https://api.yescaptcha.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY, task: { type: 'ImageToTextTaskOcrBase', body } }),
});
const data = await res.json();
if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
console.log('text:', data.solution.text);
```
Chạy: `bash quickstart.sh captcha.jpg`, `python quickstart.py captcha.jpg` hoặc `node quickstart.mjs captcha.jpg`. Python cần chạy `pip install requests` trước; Node.js cần phiên bản 18 trở lên.
6. **Xem kết quả**
Khi thành công sẽ trả về:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"text": "LMResm"
},
"taskId": "2376919c-1863-11ec-a012-94e6f7355a0b"
}
```
`errorId` bằng 0 nghĩa là thành công, văn bản nhận dạng được nằm trong `solution.text`. Khi `errorId` bằng 1, hãy xem `errorCode`, ý nghĩa xem tại [Mã lỗi](https://docs.yescaptcha.com/vi/api/errors.md).
## Bước tiếp theo
- Các tác vụ trả về token như reCAPTCHA, hCaptcha là **bất đồng bộ**: `createTask` trả về `taskId` trước, sau đó cứ mỗi 5 giây gọi `getTaskResult` một lần. Quy trình đầy đủ xem tại [Yêu cầu và phản hồi](https://docs.yescaptcha.com/vi/api/overview.md), ví dụ xem tại [reCAPTCHA v2](https://docs.yescaptcha.com/vi/tasks/recaptcha-v2.md).
- Chọn loại tác vụ: [Loại tác vụ và giá](https://docs.yescaptcha.com/vi/tasks.md).
- Client có thể sao chép thẳng vào dự án: [Python](https://docs.yescaptcha.com/vi/samples/python.md), [Node.js](https://docs.yescaptcha.com/vi/samples/nodejs.md).
- Không cần viết code: [Tiện ích trình duyệt](https://docs.yescaptcha.com/vi/extension.md).
---
# Địa chỉ truy cập
> Hai endpoint của YesCaptcha API: endpoint quốc tế api.yescaptcha.com và endpoint Trung Quốc cn.yescaptcha.com; chỉ nhận HTTPS POST với JSON, tạo và truy vấn tác vụ trên cùng một endpoint.
Source: https://docs.yescaptcha.com/vi/getting-started/endpoints/ · 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/getting-started/endpoints/
YesCaptcha API có hai endpoint, giao diện và tham số hoàn toàn giống nhau. Hãy chọn endpoint theo vị trí đặt máy chủ của bạn:
| Endpoint | Địa chỉ | Phù hợp với |
| --- | --- | --- |
| Endpoint quốc tế | `https://api.yescaptcha.com` | Máy chủ ngoài Trung Quốc đại lục |
| Endpoint Trung Quốc | `https://cn.yescaptcha.com` | Máy chủ ở Trung Quốc đại lục |
Địa chỉ của một phương thức = địa chỉ endpoint + tên phương thức, ví dụ tạo tác vụ:
- POST `https://api.yescaptcha.com/createTask` (Endpoint quốc tế)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint Trung Quốc)
## Quy tắc
- Chỉ dùng HTTPS.
- Trừ [/useragent](https://docs.yescaptcha.com/vi/api/useragent.md), mọi phương thức đều dùng `POST`, nội dung yêu cầu là JSON, kèm header `Content-Type: application/json`. Nội dung yêu cầu không được vượt quá 6 MB.
- Xác thực bằng `clientKey` trong nội dung yêu cầu, không cần header nào khác.
> **Ghi chú:** Tạo tác vụ ở endpoint nào thì truy vấn bằng `getTaskResult` ở đúng endpoint đó, không dùng lẫn hai endpoint.
## Tất cả phương thức
| Phương thức | Chức năng | Ghi chú |
| --- | --- | --- |
| [createTask](https://docs.yescaptcha.com/vi/api/create-task.md) | Tạo tác vụ | Loại đồng bộ trả về kết quả ngay |
| [getTaskResult](https://docs.yescaptcha.com/vi/api/get-task-result.md) | Truy vấn kết quả tác vụ | Loại bất đồng bộ: polling 5 giây một lần |
| [getBalance](https://docs.yescaptcha.com/vi/api/get-balance.md) | Truy vấn số dư | Không trừ điểm |
| [getSoftID](https://docs.yescaptcha.com/vi/api/get-soft-id.md) | Truy vấn ID nhà phát triển | Dùng cho chia sẻ doanh thu cho nhà phát triển |
| [report](https://docs.yescaptcha.com/vi/api/report.md) | Báo cáo kết quả nhận dạng | Loại nhận dạng hình ảnh có thể yêu cầu hoàn điểm |
| [useragent](https://docs.yescaptcha.com/vi/api/useragent.md) | Lấy User-Agent được đề xuất | `GET`, dùng cho hCaptcha |
Nếu không kết nối được tới giao diện, xem [Sự cố kết nối và mạng](https://docs.yescaptcha.com/vi/help/troubleshooting.md).
---
# Tính phí và hoàn điểm
> Cách YesCaptcha trừ điểm: 1,000 điểm = ¥1, trừ theo loại tác vụ; nhận dạng thất bại và hết thời gian chờ được tự động hoàn điểm, yêu cầu trả về lỗi không bị trừ điểm; số dư phải lớn hơn 10 điểm; báo cáo nhận dạng hình ảnh thất bại sẽ được hoàn điểm sau khoảng 24 giờ.
Source: https://docs.yescaptcha.com/vi/getting-started/billing/ · 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/getting-started/billing/
YesCaptcha trừ điểm theo từng tác vụ: mỗi loại tác vụ có giá cố định, 1,000 điểm = ¥1. Ví dụ `NoCaptchaTaskProxyless` có giá 15 điểm (≈ $2.25 / 1k) mỗi tác vụ. Giá của từng loại xem tại [Loại tác vụ và giá](https://docs.yescaptcha.com/vi/tasks.md).
> **Mẹo:** Chỉ trả tiền cho tác vụ thành công: tác vụ nhận dạng thất bại hoặc hết thời gian chờ được tự động hoàn điểm, yêu cầu trả về lỗi không bị trừ điểm.
## Khi nào bị trừ điểm
- **Loại bất đồng bộ** (phần lớn các loại trả về token): trừ điểm khi tạo tác vụ thành công. Sau đó nếu nhận dạng thất bại (`ERROR_CAPTCHA_UNSOLVABLE`, v.v.) hoặc hết thời gian chờ (`ERROR_TASK_TIMEOUT`, thường là 110 giây), điểm được tự động hoàn lại.
- **Loại đồng bộ** (nhận dạng hình ảnh, `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle`): trừ điểm khi nhận dạng thành công và trả về kết quả.
- Yêu cầu trả về lỗi ngay khi tạo tác vụ (sai tham số, không đủ số dư, vượt giới hạn đồng thời, v.v.) không bị trừ điểm.
## Số dư
- Số dư phải **lớn hơn 10 điểm** mới tạo được tác vụ, nếu không sẽ trả về `ERROR_ZERO_BALANCE`.
- Dùng [getBalance](https://docs.yescaptcha.com/vi/api/get-balance.md) để xem số dư, không bị trừ điểm.
- Về nạp tiền và điểm thưởng VIP, xem [Nạp tiền và VIP](https://docs.yescaptcha.com/vi/account/recharge.md): khi tổng số tiền đã nạp đạt cấp VIP, mỗi lần nạp tiếp theo sẽ được tặng điểm theo tỷ lệ.
## Một số loại tính giá theo từng trường hợp
- **Nhận dạng hình ảnh reCAPTCHA v2** (`ReCaptchaV2Classification`): ảnh nhỏ 1x1 và ảnh lớn 3x3, 4x4 có giá khác nhau, xem [Nhận dạng hình ảnh reCAPTCHA v2](https://docs.yescaptcha.com/vi/tasks/recaptcha-classification.md).
- **Nhận dạng hình ảnh hCaptcha** (`HCaptchaClassification`): không bị trừ điểm khi không nhận dạng được mục tiêu (kết quả rỗng).
## Hoàn điểm sau khi báo cáo nhận dạng sai
Nếu kết quả nhận dạng hình ảnh bị click sai, bạn có thể dùng [report](https://docs.yescaptcha.com/vi/api/report.md) để báo cáo; các trường hợp đủ điều kiện sẽ được hoàn điểm:
- Chỉ áp dụng cho 5 loại nhận dạng hình ảnh: `FunCaptchaClassification`, `HCaptchaClassification`, `ReCaptchaV2Classification`, `AwsClassification`, `bCaptchaClassification`.
- Phải báo cáo trong vòng **1 giờ** sau khi tạo tác vụ, mỗi tác vụ chỉ tính một lần.
- Không hoàn điểm ngay lập tức mà được quyết toán chung **sau khoảng 24 giờ**.
- Khi quyết toán, hệ thống so sánh với những người dùng khác trong cùng kỳ, cùng câu hỏi: nếu tỷ lệ thất bại bạn báo cáo cao hơn rõ rệt so với mức của cùng kỳ, điểm được hoàn theo tỷ lệ thất bại của cùng kỳ.
- Hãy báo cáo trung thực cả trường hợp thành công lẫn thất bại; báo cáo chỉ gồm các trường hợp thất bại sẽ không được dùng làm tham chiếu cho cùng kỳ, và tỷ lệ thất bại được tính trên toàn bộ tác vụ bạn đã tạo.
- Nếu có thắc mắc về kết quả quyết toán, bạn có thể [liên hệ bộ phận hỗ trợ](https://docs.yescaptcha.com/vi/help/contact.md) để khiếu nại.
Với các loại trả về token (reCAPTCHA, hCaptcha, Turnstile, v.v.), việc token có được chấp nhận hay không do trang web đích quyết định, nên báo cáo không được hoàn điểm.
## Các trường hợp không bị trừ điểm
| Tình huống | Phản hồi |
| --- | --- |
| Sai tham số, loại tác vụ không tồn tại, `clientKey` sai | Mã lỗi tương ứng |
| Số dư không lớn hơn 10 điểm | `ERROR_ZERO_BALANCE` |
| Vượt giới hạn đồng thời | `ERROR_THREADS_MAXIMUM`, xem [Giới hạn đồng thời và tự động tạm dừng](https://docs.yescaptcha.com/vi/api/rate-limits.md) |
| Trong thời gian bị tự động tạm dừng | `ERROR_IP_BLOCKED_5MIN` |
| sitekey hoặc tên miền đã bị xác định là không hợp lệ (trong thời gian lưu cache) | Mã lỗi gốc, kèm `cached: true` |
| Nhận dạng thất bại, hết thời gian chờ | Điểm đã trừ được tự động hoàn lại |
## Chia sẻ doanh thu và thưởng
- Khi dùng phần mềm hoặc tiện ích của người khác, tác vụ có thể mang theo ID nhà phát triển, nhà phát triển sẽ được chia sẻ doanh thu và việc này không ảnh hưởng đến số điểm bạn bị trừ. Nếu tự phát triển phần mềm, xem [Chia sẻ doanh thu cho nhà phát triển](https://docs.yescaptcha.com/vi/account/developer.md).
- Mời người khác đăng ký, xem [Thưởng giới thiệu](https://docs.yescaptcha.com/vi/account/referral.md).
---
# Yêu cầu và phản hồi
> Quy ước chung của YesCaptcha API: POST JSON, xác thực bằng clientKey, định dạng phản hồi errorId, tác vụ đồng bộ và bất đồng bộ, polling mỗi 5 giây, timeout 110 giây, kết quả được lưu khoảng 10 phút, ngôn ngữ thông báo theo Accept-Language.
Source: https://docs.yescaptcha.com/vi/api/overview/ · 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/api/overview/
Mọi phương thức đều gửi JSON bằng HTTPS `POST` (chỉ `/useragent` dùng `GET`), xác thực bằng `clientKey` trong nội dung yêu cầu, và phản hồi đều là JSON: `errorId` bằng 0 là thành công, bằng 1 là thất bại và kèm `errorCode`. Giải một captcha gồm hai bước: `createTask` tạo tác vụ, `getTaskResult` kiểm tra kết quả mỗi 5 giây; các loại đồng bộ trả kết quả ngay trong `createTask`.
## Yêu cầu
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY", "task": {"type": "ImageToTextTaskOcrBase", "body": "BASE64_IMAGE"}}'
```
- Endpoint: `https://api.yescaptcha.com` (quốc tế) hoặc `https://cn.yescaptcha.com` (Trung Quốc), xem [Địa chỉ truy cập](https://docs.yescaptcha.com/vi/getting-started/endpoints.md).
- Nội dung yêu cầu là JSON, kèm header `Content-Type: application/json`, không quá 6 MB. JSON không được chứa chú thích.
- Mỗi yêu cầu đều phải có `clientKey`, sao chép đầy đủ giá trị hiển thị trong bảng điều khiển.
> **Chú ý:** Với requests của Python, hãy dùng `json=data`, không dùng `data=data`. Cách sau gửi dạng form và sẽ trả về `ERROR_TASK_ABSENT` hoặc `ERROR_REQUIRED_FIELDS`.
## Phản hồi
Thành công:
```json
{
"errorId": 0,
"taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```
Thất bại:
```json
{
"errorId": 1,
"errorCode": "ERROR_ZERO_BALANCE",
"errorDescription": "帐户余额不足"
}
```
| Trường | Mô tả |
| --- | --- |
| `errorId` | 0 là thành công, 1 là thất bại |
| `errorCode` | Mã lỗi khi thất bại; ý nghĩa và cách xử lý xem [Mã lỗi](https://docs.yescaptcha.com/vi/api/errors.md) |
| `errorDescription` | Mô tả bằng văn bản về nguyên nhân thất bại |
| `taskId` | ID tác vụ |
| `status` | `processing` (đang xử lý) hoặc `ready` (hoàn tất) |
| `solution` | Kết quả nhận dạng; các trường khác nhau tùy loại tác vụ, xem trang của từng loại tác vụ |
Hãy dựa vào `errorId` và `errorCode` để xử lý kết quả, đừng phân tích nội dung văn bản của `errorDescription` vì nội dung này có thể thay đổi.
## Đồng bộ và bất đồng bộ
| | Bất đồng bộ | Đồng bộ |
| --- | --- | --- |
| Những loại nào | Các loại trả về token (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), trang thử thách Cloudflare, `ImageToTextTask`, `ImageToTextTaskM1` | Nhận dạng hình ảnh (tên kết thúc bằng `Classification`), `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle` |
| `createTask` trả về | `taskId` | `status: "ready"` và `solution` |
| Cách lấy kết quả | Gọi `getTaskResult` mỗi 5 giây | Không cần kiểm tra thêm |
Mỗi loại thuộc nhóm nào, xem cột “Cách trả kết quả” trong [Loại tác vụ và giá](https://docs.yescaptcha.com/vi/tasks.md).
## Polling
1. Sau khi `createTask` trả về `taskId`, chờ 5 giây rồi gọi `getTaskResult`.
2. Nếu trả về `status: "processing"` thì chờ thêm 5 giây rồi thử lại; nếu trả về `status: "ready"` thì kết quả nằm trong `solution`.
3. Nếu trả về `errorId: 1` thì dừng polling tác vụ này và xử lý theo `errorCode`.
- Các truy vấn lặp lại cho cùng một `taskId` trong vòng 5 giây sẽ trả về ngay `processing`; truy vấn dày hơn cũng không nhận được kết quả nhanh hơn.
- Một tác vụ thường được xử lý tối đa 110 giây (một số ít loại là 180 đến 220 giây); quá thời gian sẽ trả về `ERROR_TASK_TIMEOUT` và tự động hoàn điểm.
- Kết quả được lưu trên máy chủ khoảng 10 phút, sau đó `taskId` hết hiệu lực và truy vấn sẽ trả về `ERROR_TASKID_INVALID`.
- Truy vấn kết quả không trừ điểm, chỉ trừ điểm khi tạo tác vụ.
## Ngôn ngữ của thông báo
Với các thông báo về tự động tạm dừng, bộ nhớ đệm tham số không hợp lệ và dừng polling, `errorDescription` chọn ngôn ngữ theo header `Accept-Language` của yêu cầu: bắt đầu bằng `zh` thì trả về tiếng Trung, các ngôn ngữ khác trả về tiếng Anh, nếu không có header này thì trả về cả tiếng Trung và tiếng Anh. Mô tả của các mã lỗi khác không bị ảnh hưởng.
## Bước tiếp theo
- [createTask: tạo tác vụ](https://docs.yescaptcha.com/vi/api/create-task.md)
- [getTaskResult: lấy kết quả](https://docs.yescaptcha.com/vi/api/get-task-result.md)
- [Giới hạn đồng thời và tự động tạm dừng](https://docs.yescaptcha.com/vi/api/rate-limits.md): quá nhiều lỗi sẽ bị tạm dừng vài phút
---
# createTask – Tạo tác vụ
> POST /createTask tạo một tác vụ nhận dạng captcha. Các tham số yêu cầu (clientKey, task, softID), thứ tự kiểm tra, loại bất đồng bộ trả về taskId, loại đồng bộ trả về solution trực tiếp; số dư phải lớn hơn 10 điểm.
Source: https://docs.yescaptcha.com/vi/api/create-task/ · 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/api/create-task/
`createTask` tạo một tác vụ nhận dạng; `task.type` cho biết cần giải loại captcha nào. Loại bất đồng bộ trả về `taskId`, sau đó dùng [getTaskResult](https://docs.yescaptcha.com/vi/api/get-task-result.md) để lấy kết quả; loại đồng bộ trả về kết quả trực tiếp.
> **Ghi chú:** Điểm bị trừ khi tác vụ được tạo thành công, và số dư phải lớn hơn 10 điểm mới tạo được tác vụ. Tác vụ nhận dạng thất bại hoặc hết thời gian chờ sẽ tự động được hoàn điểm.
- POST `https://api.yescaptcha.com/createTask` (Endpoint quốc tế)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint Trung Quốc)
## Tham số yêu cầu
| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `clientKey` | string | Có | Khóa tài khoản, sao chép trong bảng điều khiển tại [yescaptcha.com](https://yescaptcha.com/) |
| `task` | object | Có | Đối tượng tác vụ, bắt buộc có `type`; các trường khác điền theo loại tác vụ, xem từng trang loại tác vụ |
| `softID` | integer | Không | ID nhà phát triển. Khi phần mềm bạn phát triển được người khác sử dụng, hãy kèm theo ID này để nhận chia sẻ doanh thu, xem [Chia sẻ doanh thu cho nhà phát triển](https://docs.yescaptcha.com/vi/account/developer.md) |
## Ví dụ yêu cầu
Nhận dạng một captcha hình ảnh (đồng bộ):
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "ImageToTextTaskOcrBase",
"body": "BASE64_IMAGE"
}
}
```
Lấy token reCAPTCHA v2 (bất đồng bộ):
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}
```
Các trường `task` của từng loại tác vụ có trong các trang thuộc [Loại tác vụ và giá](https://docs.yescaptcha.com/vi/tasks.md).
## Kết quả trả về
Loại bất đồng bộ:
```json
{
"errorId": 0,
"taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```
Hãy lưu lại `taskId`, sau 5 giây bắt đầu gọi `getTaskResult` để truy vấn.
Loại đồng bộ:
```json
{
"errorId": 0,
"status": "ready",
"taskId": "2376919c-1863-11ec-a012-94e6f7355a0b",
"solution": {
"text": "LMResm"
}
}
```
Thất bại:
```json
{
"errorId": 1,
"errorCode": "ERROR_TASK_NOT_SUPPORTED",
"errorDescription": "任务类型不正确或不受支持"
}
```
## Thứ tự kiểm tra
Máy chủ kiểm tra yêu cầu theo thứ tự sau và trả về mã lỗi tương ứng ngay khi gặp vấn đề đầu tiên, không trừ điểm:
1. Nội dung yêu cầu là JSON hợp lệ: `ERROR_REQUEST_FORMATS`
2. Có `clientKey`: `ERROR_REQUIRED_FIELDS`
3. `clientKey` tồn tại: `ERROR_KEY_DOES_NOT_EXIST`
4. Không bị tự động tạm dừng: `ERROR_IP_BLOCKED_5MIN` (xem [Giới hạn đồng thời và tự động tạm dừng](https://docs.yescaptcha.com/vi/api/rate-limits.md))
5. Số dư lớn hơn 10 điểm: `ERROR_ZERO_BALANCE`
6. Có `task`: `ERROR_TASK_ABSENT`
7. `task.type` tồn tại: `ERROR_TASK_NOT_SUPPORTED`
8. Đủ các trường bắt buộc: `ERROR_REQUIRED_FIELDS` (`errorDescription` ghi rõ thiếu trường nào)
9. Với tác vụ hình ảnh, ảnh hợp lệ: `ERROR_ZERO_CAPTCHA_FILESIZE`, `ERROR_IMAGE_TYPE_NOT_SUPPORTED`, v.v.
## Ví dụ hoàn chỉnh
Tạo tác vụ và gọi lại để lấy kết quả (loại bất đồng bộ):
**curl**
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}'
# 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": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})
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: "NoCaptchaTaskProxyless",
websiteURL: "https://www.google.com/recaptcha/api2/demo",
websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
console.log(solution.gRecaptchaResponse);
```
---
# getTaskResult – Lấy kết quả
> POST /getTaskResult truy vấn kết quả của tác vụ bất đồng bộ. Gọi lại mỗi 5 giây, tiếp tục chờ khi processing, đọc solution khi ready, dừng khi có lỗi; tác vụ chạy tối đa khoảng 110 giây, kết quả được giữ khoảng 10 phút, truy vấn không trừ điểm.
Source: https://docs.yescaptcha.com/vi/api/get-task-result/ · 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/api/get-task-result/
`getTaskResult` truy vấn kết quả của tác vụ bất đồng bộ. Sau khi tạo tác vụ, hãy gọi mỗi 5 giây một lần: nếu trả về `processing` thì tiếp tục chờ, khi trả về `ready` thì kết quả nằm trong `solution`, nếu trả về lỗi thì dừng. Truy vấn không trừ điểm, dù bạn gọi bao nhiêu lần.
- POST `https://api.yescaptcha.com/getTaskResult` (Endpoint quốc tế)
- POST `https://cn.yescaptcha.com/getTaskResult` (Endpoint Trung Quốc)
## Tham số yêu cầu
| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `clientKey` | string | Có | `clientKey` của bạn, giống với khi tạo tác vụ |
| `taskId` | string | Có | ID tác vụ do [createTask](https://docs.yescaptcha.com/vi/api/create-task.md) trả về |
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```
## Kết quả trả về
| Trường hợp | Kết quả trả về | Cần làm gì |
| --- | --- | --- |
| Đang xử lý | `errorId` là 0, `status` là `processing` | Truy vấn lại sau 5 giây |
| Hoàn tất | `errorId` là 0, `status` là `ready`, kết quả nằm trong `solution` | Lấy `solution`; các trường của nó có trong trang của từng loại tác vụ |
| Giải thất bại | `errorId` là 1, `errorCode` là `ERROR_CAPTCHA_UNSOLVABLE` | Đã tự động hoàn điểm, bạn có thể tạo lại tác vụ |
| Hết thời gian | `errorId` là 1, `errorCode` là `ERROR_TASK_TIMEOUT` | Đã tự động hoàn điểm, bạn có thể tạo lại tác vụ |
| Tác vụ không tồn tại hoặc đã hết hạn | `errorId` là 1, `errorCode` là `ERROR_TASKID_INVALID` | Ngừng truy vấn `taskId` này |
Ví dụ khi hoàn tất (reCAPTCHA v2):
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
}
}
```
## Quy tắc
- **Truy vấn mỗi 5 giây một lần.** Các truy vấn lặp lại cho cùng một `taskId` trong vòng 5 giây sẽ trả về ngay `processing`; gọi dày hơn cũng không nhanh hơn.
- **Một tác vụ được xử lý tối đa khoảng 110 giây** (một số ít loại là 180 đến 220 giây); quá thời gian sẽ trả về `ERROR_TASK_TIMEOUT` và tự động hoàn điểm. Nên đặt thời gian chờ tối đa trong chương trình khoảng 3 phút.
- **Kết quả được giữ khoảng 10 phút**, sau đó `taskId` hết hiệu lực và trả về `ERROR_TASKID_INVALID`. Hãy dùng kết quả càng sớm càng tốt: bản thân token có thời hạn ngắn hơn (reCAPTCHA khoảng 120 giây).
- **Gặp lỗi thì dừng.** Sau khi trả về `errorId: 1`, tiếp tục truy vấn cùng một `taskId` thì kết quả không đổi; từ lần truy vấn thứ 3 trở đi với cùng một tác vụ đã kết thúc, cuối `errorDescription` sẽ có nhắc dừng polling. `ERROR_TASKID_INVALID` được tính vào số lần lỗi của cơ chế [tự động tạm dừng](https://docs.yescaptcha.com/vi/api/rate-limits.md) (cùng một ID chỉ tính lần đầu tiên).
- Tạo tác vụ ở endpoint nào thì truy vấn ở endpoint đó.
- `getTaskResult` không bị ảnh hưởng bởi tự động tạm dừng: các tác vụ đã được tạo trước khi tạm dừng vẫn truy vấn bình thường.
---
# getBalance - Truy vấn số dư
> POST /getBalance truy vấn số dư tài khoản (điểm, 1,000 điểm = ¥1) cùng số dư chia sẻ doanh thu cho nhà phát triển và thưởng giới thiệu. Không trừ điểm, có thể dùng để kiểm tra clientKey.
Source: https://docs.yescaptcha.com/vi/api/get-balance/ · 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/api/get-balance/
`getBalance` trả về số điểm còn lại của tài khoản (1,000 điểm = ¥1), cùng số dư chia sẻ doanh thu cho nhà phát triển và thưởng giới thiệu (đơn vị: nhân dân tệ). Không trừ điểm, thường dùng để xác nhận `clientKey` có đúng hay không.
- POST `https://api.yescaptcha.com/getBalance` (Endpoint quốc tế)
- POST `https://cn.yescaptcha.com/getBalance` (Endpoint Trung Quốc)
## Tham số yêu cầu
| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `clientKey` | string | Có | ClientKey của tài khoản |
```json
{
"clientKey": "YOUR_CLIENT_KEY"
}
```
## Kết quả trả về
```json
{
"errorId": 0,
"balance": 1071810,
"softBalance": 36.0098,
"inviteBalance": 0,
"inviteBy": 0
}
```
| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `balance` | integer | Số dư tài khoản, đơn vị là điểm (1,000 điểm = ¥1). Phải lớn hơn 10 điểm mới tạo được tác vụ |
| `softBalance` | number | Số dư chia sẻ doanh thu cho nhà phát triển, đơn vị là nhân dân tệ, xem [Chia sẻ doanh thu cho nhà phát triển](https://docs.yescaptcha.com/vi/account/developer.md) |
| `inviteBalance` | number | Số dư thưởng giới thiệu, đơn vị là nhân dân tệ, xem [Thưởng giới thiệu](https://docs.yescaptcha.com/vi/account/referral.md) |
| `inviteBy` | integer | ID người dùng của người đã mời bạn đăng ký, bằng 0 nếu không có |
| `keyQuotaRemaining` | integer | Hạn mức chi tiêu còn lại của `clientKey` này trong chu kỳ hiện tại, đơn vị là điểm. Chỉ có trường này khi `clientKey` được đặt hạn mức; lúc đó `balance` là giá trị nhỏ hơn giữa số dư tài khoản và hạn mức còn lại. `clientKey` không đặt hạn mức thì không có trường này |
Khi `clientKey` sai, API trả về `ERROR_KEY_DOES_NOT_EXIST`; khi `clientKey` có đặt danh sách IP cho phép mà IP gửi yêu cầu không nằm trong danh sách, API trả về `ERROR_KEY_IP_NOT_ALLOWED`. `getBalance` chịu ảnh hưởng của [tự động tạm dừng](https://docs.yescaptcha.com/vi/api/rate-limits.md): trong thời gian tạm dừng, API trả về `ERROR_IP_BLOCKED_5MIN`.
## Ví dụ
**curl**
get-balance.sh
```bash
#!/usr/bin/env bash
# Check the balance. getBalance is free and is a quick way to verify your clientKey
set -euo pipefail
curl -s https://api.yescaptcha.com/getBalance \
-H 'Content-Type: application/json' \
-d "{\"clientKey\": \"${YESCAPTCHA_CLIENT_KEY}\"}"
echo
```
**Python**
get_balance.py
```python
"""Check the balance. getBalance is free and is a quick way to verify your clientKey."""
import os
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
r = requests.post(
"https://api.yescaptcha.com/getBalance",
json={"clientKey": CLIENT_KEY},
timeout=30,
)
data = r.json()
if data.get("errorId"):
# e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
print("error:", data.get("errorCode"), data.get("errorDescription"))
else:
print("balance (points):", data["balance"])
```
**Node.js**
get-balance.mjs
```js
// Check the balance. getBalance is free and is a quick way to verify your clientKey. Node.js 18+
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;
const res = await fetch('https://api.yescaptcha.com/getBalance', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY }),
});
const data = await res.json();
if (data.errorId) {
// e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
console.log('error:', data.errorCode, data.errorDescription);
} else {
console.log('balance (points):', data.balance);
}
```
---
# getSoftID – Truy vấn ID nhà phát triển
> POST /getSoftID trả về ID nhà phát triển (softID) và tổng số tiền chia sẻ doanh thu đã tích lũy của bạn; đặt softID vào yêu cầu createTask khi người khác dùng phần mềm của bạn để nhận phần chia sẻ.
Source: https://docs.yescaptcha.com/vi/api/get-soft-id/ · 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/api/get-soft-id/
`getSoftID` trả về ID nhà phát triển (`softID`) và tổng số tiền chia sẻ doanh thu cho nhà phát triển đã tích lũy (đơn vị: nhân dân tệ, ¥). Khi người khác dùng phần mềm hoặc tiện ích bạn phát triển, hãy thêm ID này vào yêu cầu `createTask` của họ để nhận phần chia sẻ theo mức chi tiêu của họ. Quy tắc chia sẻ và cách rút tiền xem tại [Chia sẻ doanh thu cho nhà phát triển](https://docs.yescaptcha.com/vi/account/developer.md).
- POST `https://api.yescaptcha.com/getSoftID` (Endpoint quốc tế)
- POST `https://cn.yescaptcha.com/getSoftID` (Endpoint Trung Quốc)
## Tham số yêu cầu
| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `clientKey` | string | Có | `clientKey` của chính bạn (nhà phát triển) |
```json
{
"clientKey": "YOUR_CLIENT_KEY"
}
```
## Kết quả trả về
```json
{
"errorId": 0,
"softID": 3,
"balance": 0.004
}
```
| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `softID` | integer | ID nhà phát triển của bạn |
| `balance` | number | Số dư chia sẻ doanh thu cho nhà phát triển đã tích lũy, đơn vị là nhân dân tệ (¥) |
## Cách sử dụng
Trong yêu cầu `createTask` do người dùng phần mềm của bạn gửi, thêm trường `softID` ở cấp cao nhất:
```json
{
"clientKey": "THE_USERS_CLIENT_KEY",
"task": {
"type": "ImageToTextTaskOcrBase",
"body": "BASE64_IMAGE"
},
"softID": 3
}
```
> **Chú ý:** `softID` phải nằm ở cấp cao nhất của nội dung yêu cầu, ngang hàng với `clientKey` và `task`, viết hoa/thường đúng như trên; đặt bên trong `task` sẽ không có hiệu lực.
`clientKey` là khóa của chính người dùng, nên điểm được trừ từ tài khoản của người dùng; `softID` là ID nhà phát triển của bạn.
---
# report – Báo cáo kết quả
> POST /report báo cho YesCaptcha biết kết quả của tác vụ đúng hay sai; hãy báo cáo trung thực cả thành công lẫn thất bại. Với loại nhận dạng hình ảnh, báo cáo thất bại trong vòng 1 giờ sau khi tạo tác vụ sẽ được quyết toán hoàn điểm sau khoảng 24 giờ.
Source: https://docs.yescaptcha.com/vi/api/report/ · 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/api/report/
`report` dùng để báo cho chúng tôi biết kết quả của một nhóm tác vụ đúng hay sai, **hãy báo cáo cả thành công lẫn thất bại**. Với loại nhận dạng hình ảnh, nếu báo cáo “sai”, các tác vụ đủ điều kiện sẽ được hoàn điểm sau khoảng 24 giờ; kết quả báo cáo cũng được dùng để đánh giá và cải thiện khả năng nhận dạng.
- POST `https://api.yescaptcha.com/report` (Endpoint quốc tế)
- POST `https://cn.yescaptcha.com/report` (Endpoint Trung Quốc)
## Tham số yêu cầu
| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `id` | array of string | Có | Danh sách ID tác vụ, có thể báo cáo nhiều tác vụ cùng lúc |
| `isSuccess` | boolean | Có | `true` nếu nhận dạng đúng, `false` nếu nhận dạng sai |
Không cần `clientKey`, bản thân ID tác vụ đã xác định được tác vụ.
```json
{
"id": ["610ff5e0-68eb-11ef-95a6-22e70a0b794d", "65b88c06-68eb-11ef-8e9a-52540023ccb3"],
"isSuccess": false
}
```
## Kết quả trả về
```json
{
"errorId": 0,
"status": "success"
}
```
## Hãy báo cáo trung thực
Báo cáo vừa dùng để quyết toán hoàn điểm, vừa dùng để đánh giá và cải thiện khả năng nhận dạng, vì vậy hãy báo cáo theo kết quả thực tế:
- Tác vụ nhận dạng đúng thì báo `isSuccess: true`, sai thì báo `false`. Những báo cáo chỉ báo thất bại mà không báo thành công, hoặc báo thất bại cho tất cả bất kể đúng sai, sẽ không được dùng làm tham chiếu trong thống kê và quyết toán.
- Tỷ lệ thất bại được tính trên toàn bộ tác vụ bạn đã tạo trong khoảng thời gian đó, không chỉ những tác vụ đã báo cáo. Báo cáo thêm thất bại không giúp được hoàn thêm điểm: nếu tỷ lệ thất bại của bạn cao hơn rõ rệt so với cùng kỳ, chỉ hoàn điểm theo tỷ lệ thất bại của cùng kỳ.
- Khi một lần xác minh dùng nhiều ảnh (ví dụ FunCaptcha phải chọn 5 vòng) và bạn không biết ảnh nào sai, có thể báo cáo cả nhóm tác vụ này là thất bại; khi xác minh thành công, cũng báo cáo cả nhóm này là thành công.
## Hoàn điểm sau khi báo cáo thất bại
- Chỉ 5 loại nhận dạng hình ảnh được hoàn điểm: `FunCaptchaClassification`, `HCaptchaClassification`, `ReCaptchaV2Classification`, `AwsClassification`, `bCaptchaClassification`.
- Chỉ tính báo cáo gửi **trong vòng 1 giờ** sau khi tạo tác vụ; mỗi tác vụ chỉ được hoàn điểm một lần.
- Không hoàn điểm ngay lập tức mà được quyết toán chung **sau khoảng 24 giờ**.
- Khi quyết toán, tỷ lệ thất bại bạn báo cáo được so sánh với những người dùng khác trên cùng câu hỏi trong cùng kỳ; nếu cao hơn rõ rệt so với mặt bằng cùng kỳ, sẽ hoàn điểm theo tỷ lệ thất bại của cùng kỳ.
- Nếu có thắc mắc về kết quả quyết toán, bạn có thể [liên hệ bộ phận hỗ trợ](https://docs.yescaptcha.com/vi/help/contact.md) để khiếu nại.
Với các loại trả về token (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha, v.v.), token có hợp lệ hay không do trang web đích quyết định, nên báo cáo không được hoàn điểm. Tổng hợp quy tắc tính phí xem tại [Tính phí và hoàn điểm](https://docs.yescaptcha.com/vi/getting-started/billing.md).
---
# useragent - Lấy User-Agent
> GET https://api.yescaptcha.com/useragent trả về User-Agent trình duyệt nên dùng (văn bản thuần). Trường userAgent của tác vụ hCaptcha chỉ chấp nhận giá trị này.
Source: https://docs.yescaptcha.com/vi/api/useragent/ · 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/api/useragent/
`/useragent` trả về User-Agent trình duyệt hiện được khuyến nghị, dạng văn bản thuần. Không cần `clientKey` và không trừ điểm. Trường `userAgent` của tác vụ [hCaptcha](https://docs.yescaptcha.com/vi/tasks/hcaptcha.md) chỉ chấp nhận giá trị này; khi truy cập trang web đích, bạn cũng nên dùng nó để token dễ được chấp nhận hơn.
- GET `https://api.yescaptcha.com/useragent` (Endpoint quốc tế)
- GET `https://cn.yescaptcha.com/useragent` (Endpoint Trung Quốc)
## Ví dụ
```bash
curl -s https://api.yescaptcha.com/useragent
```
Kết quả trả về (giá trị ngày 2026-10-15, sẽ thay đổi theo phiên bản trình duyệt):
```text
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36
```
> **Ghi chú:** Giá trị trả về được cập nhật liên tục. Đừng viết cố định trong code; chỉ cần lấy một lần mỗi khi chương trình khởi động.
- Nếu kết quả nhận dạng có kèm `userAgent`, hãy dùng giá trị trong kết quả khi gửi token.
---
# Mã lỗi
> Ý nghĩa và cách xử lý tất cả mã lỗi của YesCaptcha API, chia theo nhóm: định dạng yêu cầu, tài khoản và số dư, giới hạn đồng thời và tạm dừng, kết quả tác vụ, tham số trang web, hình ảnh, proxy, phía máy chủ. Yêu cầu trả về lỗi không bị trừ điểm.
Source: https://docs.yescaptcha.com/vi/api/errors/ · 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/api/errors/
Khi giao diện gặp lỗi, API trả về `errorId: 1`; `errorCode` là mã lỗi, `errorDescription` là mô tả bằng văn bản. Yêu cầu trả về lỗi không bị trừ điểm: lỗi xảy ra ngay lúc tạo tác vụ thì không trừ, còn tác vụ nhận dạng thất bại hoặc hết thời gian sau khi đã tạo sẽ tự động hoàn điểm.
> **Mẹo:** Trong chương trình, hãy xử lý theo `errorCode`, đừng dựa vào nội dung của `errorDescription`, vì mô tả văn bản có thể thay đổi.
```json
{
"errorId": 1,
"errorCode": "ERROR_ZERO_BALANCE",
"errorDescription": "帐户余额不足"
}
```
## Nguyên tắc xử lý
1. **Lỗi tham số** (định dạng yêu cầu, clientKey, loại tác vụ, tham số trang web, hình ảnh): gửi lại vẫn không đổi kết quả, cần sửa yêu cầu trước.
2. **Nhận dạng thất bại và hết thời gian** (`ERROR_CAPTCHA_UNSOLVABLE`, `ERROR_TASK_TIMEOUT`): có thể tạo lại tác vụ.
3. Sau khi gặp lỗi, hãy **dừng polling** `taskId` đó, đừng gửi lại nguyên yêu cầu với tần suất cao.
4. Với lỗi được đánh dấu “Tính vào tự động tạm dừng”: nếu cùng một `clientKey` gặp 100 lỗi như vậy trong một phút, việc tạo tác vụ sẽ bị tạm dừng 5 phút. Lỗi được đánh dấu “Cache” thì không được tính, nhưng trong thời gian cache, cùng một yêu cầu sẽ trả về ngay lỗi ban đầu. Xem chi tiết tại [Giới hạn đồng thời và tự động tạm dừng](https://docs.yescaptcha.com/vi/api/rate-limits.md).
## Tất cả mã lỗi
### Định dạng yêu cầu
| Mã lỗi | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | Thiếu một trường bắt buộc (như `clientKey`, hoặc `websiteURL` / `websiteKey` theo loại tác vụ), hoặc nội dung yêu cầu không phải JSON | Bổ sung các trường còn thiếu được liệt kê trên trang loại tác vụ, và gửi JSON bằng `POST` kèm `Content-Type: application/json` |
| `ERROR_REQUEST_FORMATS` (Tính vào tự động tạm dừng) | Nội dung yêu cầu không phải JSON hợp lệ | Tạo nội dung yêu cầu bằng thư viện JSON thay vì ghép chuỗi; JSON không được chứa chú thích `//` |
| `ERROR_TASK_ABSENT` (Tính vào tự động tạm dừng) | Thiếu trường `task` trong lệnh gọi `createTask` | Đặt các tham số của tác vụ vào đối tượng `task`. Với Python requests hãy dùng `json=data`, không dùng `data=data` |
| `ERROR_TASK_NOT_SUPPORTED` (Tính vào tự động tạm dừng) | `task.type` bị sai chính tả hoặc loại tác vụ này đã ngừng cung cấp | Sao chép tên loại tác vụ từ "Loại tác vụ và bảng giá"; tên phân biệt chữ hoa chữ thường |
| `ERROR_PAGE_NOT_FOUND` | Đường dẫn được yêu cầu không tồn tại | Kiểm tra URL endpoint, ví dụ `https://api.yescaptcha.com/createTask`; tên phương thức phân biệt chữ hoa chữ thường |
| `ERROR_BAD_REQUEST` | Không thể xử lý yêu cầu, thường do dùng sai phương thức HTTP (GET thay vì POST) hoặc giá trị tham số không hợp lệ | Gửi JSON bằng `POST`, và kiểm tra kiểu cũng như giá trị của các tham số |
| `ERROR_ILLEGAL_PARAMETERS` | Giá trị tham số không hợp lệ. Thường gặp với trang thử thách Cloudflare: `websiteURL` không phải URL công khai bắt đầu bằng `http://` / `https://`, `postData` không phải đối tượng, hoặc `requiredCookies` không phải mảng chuỗi (do createTask trả về, không trừ điểm); hoặc không phân giải được tên miền đích qua proxy (do getTaskResult trả về, đã tự động hoàn điểm) | Sửa giá trị theo bảng tham số trên trang loại tác vụ. Nếu không phân giải được tên miền, hãy kiểm tra chính tả URL và xem proxy có truy cập được website đó không |
### Tài khoản và số dư
| Mã lỗi | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| `ERROR_KEY_DOES_NOT_EXIST` (Tính vào tự động tạm dừng) | `clientKey` không tồn tại: bị thừa hoặc thiếu ký tự khi sao chép, hoặc khóa đã được đặt lại trong bảng điều khiển | Sao chép lại khóa từ bảng điều khiển trên yescaptcha.com, không kèm dấu cách hoặc ký tự xuống dòng |
| `ERROR_KEY_EXPIRED` (Tính vào tự động tạm dừng) | `clientKey` đã hết hạn (do createTask và getBalance trả về, không trừ điểm). Có hai trường hợp: `clientKey` không được sử dụng trong thời gian dài nên hệ thống đã đặt thời hạn để bảo vệ tài khoản (sẽ có email nhắc trước khi hết hạn), hoặc thời hạn được đặt cho `clientKey` này đã qua | Đăng nhập vào bảng điều khiển trên yescaptcha.com. Nếu `clientKey` hết hạn do lâu không sử dụng, hãy tạo `clientKey` mới; số dư sẽ tự động chuyển sang `clientKey` mới. Nếu đã đặt thời hạn, hãy thay đổi thời hạn hoặc dùng `clientKey` khác. Sau đó cập nhật `clientKey` mới vào chương trình của bạn |
| `ERROR_KEY_IP_NOT_ALLOWED` | `clientKey` này có danh sách IP được phép (allowlist) và IP gửi yêu cầu không nằm trong danh sách đó (được trả về bởi createTask và getBalance, không trừ điểm, không tính vào tự động tạm dừng) | Đăng nhập vào bảng điều khiển yescaptcha.com và thêm IP công khai của máy đang gửi yêu cầu vào danh sách IP được phép của `clientKey` này, hoặc dùng `clientKey` khác. Nếu gọi API từ nhiều máy, hãy thêm IP công khai của từng máy (đây là IP gọi API của YesCaptcha, không phải proxy trong tham số tác vụ) |
| `ERROR_KEY_QUOTA_EXCEEDED` | `clientKey` này có hạn mức chi tiêu và phần còn lại của chu kỳ hiện tại ít hơn số điểm cần trừ cho tác vụ này (được trả về bởi createTask, không trừ điểm, không tính vào tự động tạm dừng). Hạn mức tính theo số điểm thực tế đã trừ; điểm được hoàn lại do tác vụ thất bại hoặc hết thời gian chờ cũng được trả về hạn mức | Đăng nhập vào bảng điều khiển yescaptcha.com và tăng hạn mức của `clientKey` này, hoặc chờ chu kỳ tiếp theo (đặt lại hằng ngày, vào thứ Hai hằng tuần hoặc ngày 1 hằng tháng, theo giờ Bắc Kinh; hạn mức dùng một lần không được đặt lại), hoặc dùng `clientKey` khác. `getBalance` trả về hạn mức còn lại của `clientKey` này (`keyQuotaRemaining`) |
| `ERROR_ZERO_BALANCE` | Số dư không đủ. Số dư phải lớn hơn 10 điểm mới tạo được tác vụ | Nạp tiền rồi thử lại. Dùng `getBalance` để kiểm tra số dư |
### Giới hạn đồng thời và tạm dừng
| Mã lỗi | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| `ERROR_THREADS_MAXIMUM` (Một số trường hợp tính vào tự động tạm dừng) | Tài khoản có quá nhiều tác vụ loại này đang được xử lý. `limit` trong phản hồi là giới hạn hiện tại. Yêu cầu không được xử lý và không bị trừ điểm | Chờ các yêu cầu đang xử lý trả về, hoặc chờ 1–2 giây rồi thử lại; hãy giới hạn số yêu cầu cùng chờ kết quả tại một thời điểm |
| `ERROR_IP_BLOCKED_5MIN` | `clientKey` này gây ra quá nhiều lỗi trong thời gian ngắn và đã bị tự động tạm dừng. `retryAfter` là số giây còn lại và `blockReason` là mã lỗi gây ra việc tạm dừng | Sửa yêu cầu theo `blockReason` và chờ `retryAfter` giây; việc tiếp tục gửi trong thời gian tạm dừng không làm kéo dài thời gian đó |
| `ERROR_NO_SLOT_AVAILABLE` | Dịch vụ nhận dạng tạm thời quá tải. Khi `createTask` trả về lỗi này thì không trừ điểm; tác vụ xếp hàng quá lâu cũng sẽ trả về lỗi này từ `getTaskResult`, và được hoàn điểm tự động | Chờ vài giây rồi tạo lại tác vụ |
### Tác vụ và kết quả
| Mã lỗi | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| `ERROR_TASKID_INVALID` (Tính vào tự động tạm dừng) | `taskId` không tồn tại, đã hết hạn (kết quả được lưu khoảng 10 phút), thuộc về `clientKey` khác, hoặc được tạo trên endpoint còn lại | Dừng polling tác vụ này. Truy vấn bằng đúng endpoint và `clientKey` đã dùng để tạo tác vụ |
| `ERROR_TASK_TIMEOUT` | Tác vụ không hoàn thành trong thời gian quy định (thường là 110 giây); điểm đã được hoàn tự động | Tạo tác vụ mới; nếu liên tục hết thời gian chờ, hãy thử loại tác vụ khác cho cùng loại captcha |
| `ERROR_CAPTCHA_UNSOLVABLE` | Lần này không nhận dạng được captcha; điểm đã được hoàn. Lỗi này không được tính vào tự động tạm dừng | Tạo tác vụ mới. Nếu vẫn liên tục thất bại, hãy kiểm tra `websiteURL`, `websiteKey` và các tham số khác, hoặc thử loại tác vụ khác cho cùng loại captcha |
| `ERROR_SETTLEMENT_FAILED` (Tính vào tự động tạm dừng) | Số dư không đủ tại thời điểm quyết toán nên không trả về kết quả | Nạp tiền rồi tạo tác vụ mới |
| `ERROR_NO_SUCH_CAPCHA_ID` | Tác vụ không còn hiệu lực | Dừng polling tác vụ này và tạo tác vụ mới |
| `ERROR_RECAPTCHA_TIMEOUT` | Nhận dạng captcha bị hết thời gian chờ; điểm đã được hoàn | Tạo tác vụ mới |
### Tham số website đích
| Mã lỗi | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| `ERROR_RECAPTCHA_INVALID_SITEKEY` (Dùng bộ nhớ đệm, không tính vào tạm dừng) | `websiteKey` không hợp lệ | Tìm lại sitekey trong trang web (xem các hướng dẫn tìm tham số). Trong thời gian lưu cache, các yêu cầu giống hệt sẽ trả về ngay lỗi này, kèm `cached: true` |
| `ERROR_RECAPTCHA_INVALID_DOMAIN` (Dùng bộ nhớ đệm, không tính vào tạm dừng) | Tên miền của `websiteURL` không khớp với `websiteKey` | Điền `websiteURL` là địa chỉ trang hiển thị captcha |
| `ERROR_INVALID_KEY_TYPE` (Dùng bộ nhớ đệm, không tính vào tạm dừng) | Sitekey thuộc về loại captcha khác, ví dụ dùng key của v3 cho loại tác vụ v2 | Hãy xác định loại captcha trước (xem "Xác định loại captcha") rồi chọn loại tác vụ tương ứng; với v2 ẩn (invisible), hãy truyền `isInvisible` |
| `ERROR_DOMAIN_NOT_ALLOWED` (Dùng bộ nhớ đệm, không tính vào tạm dừng) | Trang web này hiện chưa được hỗ trợ | Thử loại tác vụ khác cho cùng loại captcha, hoặc liên hệ bộ phận hỗ trợ |
| `ERROR_HIGH_DEMAND_DOMAIN` (Tính vào tự động tạm dừng) | Trang web này hiện chưa được hỗ trợ | Ngừng gửi tác vụ cho trang web này và liên hệ bộ phận hỗ trợ để xác nhận |
| `ERROR_FAILED_LOADING_WIDGET` | Không tải được captcha với các tham số đã cung cấp | Kiểm tra `websiteURL` và `websiteKey`; với các loại tác vụ dùng proxy riêng, kiểm tra proxy có truy cập được trang web đích hay không |
### Hình ảnh
| Mã lỗi | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| `ERROR_ZERO_CAPTCHA_FILESIZE` (Tính vào tự động tạm dừng) | Ảnh trống hoặc quá nhỏ | Kiểm tra dữ liệu Base64 đã đầy đủ chưa và không có tiền tố `data:image/...;base64,` |
| `ERROR_TOO_BIG_CAPTCHA_FILESIZE` (Tính vào tự động tạm dừng) | Ảnh quá lớn | Nén hoặc thu nhỏ ảnh rồi gửi lại; toàn bộ nội dung yêu cầu không được vượt quá 6 MB |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` (Tính vào tự động tạm dừng) | Định dạng ảnh không được hỗ trợ, hoặc ảnh không phải loại mà loại tác vụ này xử lý được. Chỉ cần xảy ra 1 lần là bị tạm dừng 30 phút | Dùng JPG hoặc PNG và đảm bảo ảnh phù hợp với loại tác vụ, ví dụ nhận dạng hình ảnh reCAPTCHA cần ảnh 100x100, 300x300 hoặc 450x450 |
| `ERROR_ILLEGAL_IMAGE` (Tính vào tự động tạm dừng) | Kích thước ảnh không đáp ứng yêu cầu của loại tác vụ này | Điều chỉnh kích thước ảnh theo mô tả ở trang loại tác vụ |
| `ERROR_PARSE_IMAGE_FAIL` | Không giải mã được ảnh, thường do Base64 bị cắt cụt hoặc có tiền tố | Kiểm tra mã hóa Base64 và xóa tiền tố `data:` cùng các ký tự xuống dòng |
| `ERROR_UNKNOWN_QUESTION` | `question` bị sai, hoặc câu hỏi này hiện chưa được hỗ trợ | Đối chiếu với danh sách câu hỏi ở trang loại tác vụ. Với câu hỏi chưa được hỗ trợ, hãy liên hệ bộ phận hỗ trợ; câu hỏi mới thường được hỗ trợ trong vòng 3 ngày làm việc |
| `ERROR_UNKNOW_450x450_QUESTION` | Câu hỏi này hiện chưa được hỗ trợ với ảnh 4x4 (450x450) | Tải lại thử thách trên trang để lấy câu hỏi khác |
### Proxy
| Mã lỗi | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| `ERROR_PROXY_CONNECT_REFUSED` | Proxy từ chối kết nối | Kiểm tra địa chỉ, cổng và giao thức của proxy, và đảm bảo proxy cho phép kết nối từ bên ngoài (không phải địa chỉ cục bộ như 127.0.0.1) |
| `ERROR_PROXY_CONNECT_TIMEOUT` | Kết nối tới proxy bị hết thời gian chờ | Dùng proxy ổn định hơn |
| `ERROR_PROXY_READ_TIMEOUT` | Đọc dữ liệu qua proxy bị hết thời gian chờ | Dùng proxy nhanh hơn |
| `ERROR_PROXY_BANNED` | Proxy không khả dụng, hoặc IP của proxy bị trang web đích chặn | Dùng proxy khác |
| `ERROR_PROXY_INCORRECT` | Tham số proxy sai định dạng | Kiểm tra định dạng của `proxyType`, `proxyAddress`, `proxyPort` (hoặc chuỗi `proxy`) |
| `ERROR_PROXY_TRANSPARENT` | Proxy là proxy trong suốt (transparent) và làm lộ IP thật | Dùng proxy ẩn danh (elite) |
| `ERROR_PROXY_NOT_AUTHORISED` | Tên người dùng hoặc mật khẩu của proxy không đúng | Kiểm tra `proxyLogin` và `proxyPassword` (hoặc thông tin đăng nhập trong chuỗi `proxy`) |
| `ERROR_PROXY_TLS_ERROR` | Bắt tay TLS với proxy thất bại, thường do `proxyType` sai (ví dụ đặt https cho proxy http) | Kiểm tra lại giao thức của proxy |
| `ERROR_PROXY_CONNECTION_FAILED` | Không kết nối được tới máy chủ proxy | Kiểm tra địa chỉ và cổng của proxy, và đảm bảo proxy đang hoạt động bình thường |
### Máy chủ
| Mã lỗi | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| `ERROR_SERVICE_UNAVALIABLE` | Dịch vụ tạm thời không khả dụng (mã lỗi được viết là `UNAVALIABLE`) | Thử lại sau; nếu tiếp tục xảy ra, hãy liên hệ bộ phận hỗ trợ |
| `ERROR_INTERNAL_SERVER_ERROR` | Đã xảy ra lỗi máy chủ nội bộ | Thử lại sau; nếu lỗi vẫn tiếp diễn, hãy liên hệ bộ phận hỗ trợ và cung cấp `taskId` |
| `ERROR_UNKNOWN` | Lỗi chưa được phân loại | Thử lại sau; nếu lỗi vẫn tiếp diễn, hãy liên hệ bộ phận hỗ trợ và cung cấp `taskId` |
## Trường bổ sung
Phản hồi của một số lỗi có kèm các trường bổ sung:
| Trường | Xuất hiện ở | Mô tả |
| --- | --- | --- |
| `retryAfter` | `ERROR_IP_BLOCKED_5MIN`, các lỗi được cache | Cần chờ thêm bao nhiêu giây |
| `blockReason` | `ERROR_IP_BLOCKED_5MIN` | Mã lỗi đã kích hoạt việc tạm dừng |
| `blockDetail` | `ERROR_IP_BLOCKED_5MIN` | Loại yêu cầu, URL và sitekey của yêu cầu đã kích hoạt tạm dừng, giúp xác định nguyên nhân |
| `cached` | Các lỗi được cache | `true` nghĩa là đây là kết quả được cache, chưa thực sự nhận dạng |
| `badRequest` | Các lỗi được cache | Tham số đã trúng cache |
| `limit` | `ERROR_THREADS_MAXIMUM` | Giới hạn đồng thời hiện tại của bạn |
Quy tắc về ngôn ngữ của `errorDescription` xem tại [Yêu cầu và phản hồi](https://docs.yescaptcha.com/vi/api/overview.md).
---
# Giới hạn đồng thời và tự động tạm dừng
> Giới hạn đồng thời của YesCaptcha (ERROR_THREADS_MAXIMUM, không trừ điểm, không tính vào tự động tạm dừng), tự động tạm dừng khi có quá nhiều lỗi (100 lần trong một phút thì tạm dừng 5 phút, ERROR_IP_BLOCKED_5MIN) và bộ nhớ đệm tham số không hợp lệ (cached).
Source: https://docs.yescaptcha.com/vi/api/rate-limits/ · 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/api/rate-limits/
Để giữ tốc độ nhận dạng cho mọi người dùng, YesCaptcha có ba quy tắc bảo vệ: giới hạn **số tác vụ đang xử lý cùng lúc** theo từng tài khoản (giới hạn đồng thời); `clientKey` tạo **quá nhiều lỗi trong thời gian ngắn sẽ bị tạm dừng** vài phút (tự động tạm dừng); **tham số đã bị xác định là không hợp lệ** sẽ được trả về đúng lỗi ban đầu trong một khoảng thời gian (bộ nhớ đệm tham số không hợp lệ). Cả ba trường hợp đều không trừ điểm.
## Giới hạn đồng thời
Chúng tôi giới hạn số tác vụ đang xử lý cùng một thời điểm theo từng tài khoản và từng loại tác vụ. Đây là giới hạn số lượng đồng thời, không phải số yêu cầu mỗi phút.
- Một tác vụ được tính là “đang xử lý” từ lúc gọi `createTask` đến khi lệnh gọi đó trả về. Các loại nhận dạng hình ảnh trả kết quả ngay trong `createTask`, nên **số đồng thời ≈ số tác vụ gửi mỗi giây × thời gian xử lý mỗi tác vụ**. Ví dụ mỗi tác vụ mất 0.5 giây, mỗi giây gửi 40 tác vụ thì số đồng thời khoảng 20.
- Các yêu cầu của cùng một tài khoản được tính gộp; mỗi loại tác vụ được tính riêng.
- Yêu cầu vượt hạn mức sẽ trả về `ERROR_THREADS_MAXIMUM` ngay lập tức, trường `limit` trong phản hồi là giới hạn hiện tại của bạn. **Không trừ điểm và không tính vào tự động tạm dừng.**
- Khi máy chủ nhận dạng quá tải, tài khoản chiếm nhiều thời gian nhận dạng nhất sẽ bị **giảm một nửa giới hạn của loại tác vụ đó trong thời gian tạm thời, tự động khôi phục sau 10 phút**. Đây chỉ là giảm tốc độ, không tạm dừng tài khoản.
- Nếu cần hạn mức cao hơn, hãy [liên hệ hỗ trợ](https://docs.yescaptcha.com/vi/help/contact.md). Sau khi chốt hạn mức mặc định của từng loại, chúng tôi sẽ công bố trên trang này và trong [nhật ký cập nhật dịch vụ](https://docs.yescaptcha.com/vi/changelog.md).
```json
{
"errorId": 1,
"errorCode": "ERROR_THREADS_MAXIMUM",
"errorDescription": "This account already has 30 tasks of this type in progress, which is the limit. Lower the concurrency and wait for pending requests to return before sending more; rejected requests are not charged and do not lead to a block.",
"limit": 30
}
```
(Con số trong ví dụ chỉ mang tính minh họa.)
### Cách làm khuyến nghị
1. Trong chương trình, hãy giới hạn “số yêu cầu đang chờ kết quả cùng lúc”, ví dụ dùng semaphore hoặc thread pool có kích thước cố định, thay vì chỉ kiểm soát số yêu cầu gửi mỗi giây.
2. Sau khi nhận `ERROR_THREADS_MAXIMUM`, hãy đợi các yêu cầu đã gửi trả về rồi mới gửi yêu cầu mới, hoặc đợi 1 đến 2 giây rồi thử lại. Không thử lại liên tục trong vòng lặp.
3. Với tác vụ hàng loạt, hãy gửi đều đặn, đừng gửi hàng nghìn tác vụ cùng một lúc.
Ví dụ Python (asyncio):
```python
import asyncio
import os
import aiohttp
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
LIMIT = 15 # below your concurrency limit
sem = asyncio.Semaphore(LIMIT)
async def solve(session, task):
async with sem: # at most LIMIT requests in progress at a time
result = {}
for attempt in range(5):
async with session.post(
"https://api.yescaptcha.com/createTask",
json={"clientKey": CLIENT_KEY, "task": task},
) as resp:
result = await resp.json()
if result.get("errorCode") != "ERROR_THREADS_MAXIMUM":
return result
await asyncio.sleep(1 + attempt) # over the limit: wait and retry
return result
```
## Tự động tạm dừng
Khi cùng một `clientKey` tạo ra nhiều yêu cầu lỗi trong thời gian ngắn, việc tạo tác vụ sẽ bị tự động tạm dừng:
| Điều kiện kích hoạt | Thời gian tạm dừng |
| --- | --- |
| Trong cùng một phút theo đồng hồ, các lỗi liệt kê bên dưới cộng dồn đạt 100 lần | 5 phút |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` xuất hiện 1 lần | 30 phút |
| Trong cùng một phút theo đồng hồ, trúng “bộ nhớ đệm tham số không hợp lệ” 1000 lần | 5 phút |
Các lỗi được tính vào tạm dừng:
- [`ERROR_REQUEST_FORMATS`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_REQUEST_FORMATS)
- [`ERROR_TASK_ABSENT`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_TASK_ABSENT)
- [`ERROR_TASK_NOT_SUPPORTED`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_TASK_NOT_SUPPORTED)
- [`ERROR_KEY_DOES_NOT_EXIST`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_KEY_DOES_NOT_EXIST)
- [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_KEY_EXPIRED)
- [`ERROR_TASKID_INVALID`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_TASKID_INVALID)
- [`ERROR_SETTLEMENT_FAILED`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_SETTLEMENT_FAILED)
- [`ERROR_HIGH_DEMAND_DOMAIN`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_HIGH_DEMAND_DOMAIN)
- [`ERROR_ZERO_CAPTCHA_FILESIZE`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_ZERO_CAPTCHA_FILESIZE)
- [`ERROR_TOO_BIG_CAPTCHA_FILESIZE`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_TOO_BIG_CAPTCHA_FILESIZE)
- [`ERROR_IMAGE_TYPE_NOT_SUPPORTED`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_IMAGE_TYPE_NOT_SUPPORTED)
- [`ERROR_ILLEGAL_IMAGE`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_ILLEGAL_IMAGE)
`ERROR_THREADS_MAXIMUM` do tài khoản vượt giới hạn đồng thời (có trường `limit`) không được tính; cùng mã lỗi này khi dịch vụ nhận dạng đang bận (không có `limit`) thì được tính. Nhận dạng thất bại (`ERROR_CAPTCHA_UNSOLVABLE`), số dư không đủ (`ERROR_ZERO_BALANCE`), thiếu trường (`ERROR_REQUIRED_FIELDS`), câu hỏi không được hỗ trợ (`ERROR_UNKNOWN_QUESTION`) và các lỗi tương tự không được tính.
Trong thời gian tạm dừng:
- Chỉ ảnh hưởng đến `createTask` và `getBalance`, hai lệnh này trả về `ERROR_IP_BLOCKED_5MIN`. `getTaskResult` không bị ảnh hưởng, các tác vụ đã tạo trước khi tạm dừng vẫn tra cứu kết quả bình thường.
- Phản hồi có `retryAfter` (số giây còn lại), `blockReason` (mã lỗi gây ra tạm dừng) và `blockDetail` (loại, URL, sitekey của các yêu cầu đó). Hãy dựa vào các trường này để sửa chương trình.
- Tiếp tục gửi yêu cầu không làm kéo dài thời gian tạm dừng; hết hạn sẽ tự động khôi phục, không cần liên hệ hỗ trợ.
- Trong bảng điều khiển tại [yescaptcha.com](https://yescaptcha.com/), bạn có thể xem lịch sử tạm dừng trong 24 giờ gần nhất.
```json
{
"errorId": 1,
"errorCode": "ERROR_IP_BLOCKED_5MIN",
"errorDescription": "...",
"retryAfter": 182,
"blockReason": "ERROR_TASK_NOT_SUPPORTED"
}
```
## Bộ nhớ đệm tham số không hợp lệ
Một số lỗi do chính tham số của yêu cầu quyết định, gửi lại với cùng tham số thì kết quả cũng không đổi:
- [`ERROR_RECAPTCHA_INVALID_SITEKEY`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_RECAPTCHA_INVALID_SITEKEY)
- [`ERROR_RECAPTCHA_INVALID_DOMAIN`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_RECAPTCHA_INVALID_DOMAIN)
- [`ERROR_INVALID_KEY_TYPE`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_INVALID_KEY_TYPE)
- [`ERROR_DOMAIN_NOT_ALLOWED`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_DOMAIN_NOT_ALLOWED)
Các lỗi này không được tính vào tự động tạm dừng mà được lưu đệm trên toàn hệ thống: lưu 2 phút sau lần xác định đầu tiên; nếu được xác nhận lại trong vòng 1 giờ thì lưu 10 phút. Trong thời gian lưu đệm, các yêu cầu giống nhau (cùng loại tác vụ và `websiteKey`, hoặc cùng tên miền trang web) sẽ trả về ngay lỗi ban đầu, không trừ điểm, phản hồi có `"cached": true`, `retryAfter` (số giây còn lại của bộ nhớ đệm) và `badRequest` (tham số bị trúng). Sửa `websiteKey` hoặc đổi loại tác vụ sẽ có hiệu lực ngay.
## Khác biệt giữa giới hạn đồng thời và tự động tạm dừng
| | Giới hạn đồng thời | Tự động tạm dừng |
| --- | --- | --- |
| Nguyên nhân | Có quá nhiều tác vụ đang xử lý cùng lúc | Có quá nhiều yêu cầu lỗi trong thời gian ngắn |
| Biểu hiện | Chỉ từ chối phần yêu cầu vượt mức, `ERROR_THREADS_MAXIMUM` | `clientKey` này bị tạm dừng tạo tác vụ, `ERROR_IP_BLOCKED_5MIN` |
| Khôi phục | Có yêu cầu xử lý xong là gửi được yêu cầu mới; giới hạn bị giảm một nửa sẽ khôi phục sau 10 phút | Hết hạn tự động khôi phục |
| Trừ điểm | Không trừ | Không trừ |
---
# Loại tác vụ và bảng giá
> Giá (điểm, 1 tệ = 1,000 điểm) và cách trả kết quả của tất cả loại tác vụ công khai của YesCaptcha: token cho reCAPTCHA, hCaptcha, Turnstile, Cookie cho trang thử thách Cloudflare, kết quả nhận dạng cho captcha ảnh chữ-số và nhận dạng hình ảnh.
Source: https://docs.yescaptcha.com/vi/tasks/ · Last verified: 2026-10-19
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/
Mỗi tác vụ bị trừ một số điểm cố định theo loại, 1 tệ = 1,000 điểm; tác vụ nhận dạng thất bại hoặc hết thời gian chờ sẽ tự động hoàn điểm. Bảng dưới liệt kê tất cả loại tác vụ công khai và có thể tìm theo tên. Phiên bản đọc được bằng máy: [/data/task-types.json](https://docs.yescaptcha.com/data/task-types.json).
| Captcha | Loại tác vụ | Giá | Cách trả kết quả |
| --- | --- | --- | --- |
| [reCAPTCHA v2](https://docs.yescaptcha.com/vi/tasks/recaptcha-v2.md) | `NoCaptchaTaskProxyless` | $2.25 / 1k; 15 điểm/tác vụ · ¥15 / 1k | Bất đồng bộ |
| [reCAPTCHA v2](https://docs.yescaptcha.com/vi/tasks/recaptcha-v2.md) | `RecaptchaV2TaskProxyless` | $3.00 / 1k; 20 điểm/tác vụ · ¥20 / 1k | Bất đồng bộ |
| [reCAPTCHA v2](https://docs.yescaptcha.com/vi/tasks/recaptcha-v2.md) | `NoCaptchaTask` Dùng proxy riêng | $2.25 / 1k; 15 điểm/tác vụ · ¥15 / 1k | Bất đồng bộ |
| [reCAPTCHA v2](https://docs.yescaptcha.com/vi/tasks/recaptcha-v2.md) | `RecaptchaV2EnterpriseTaskProxyless` | $3.00 / 1k; 20 điểm/tác vụ · ¥20 / 1k | Bất đồng bộ |
| [reCAPTCHA v2](https://docs.yescaptcha.com/vi/tasks/recaptcha-v2.md) | `RecaptchaV2EnterpriseTask` Dùng proxy riêng | $3.00 / 1k; 20 điểm/tác vụ · ¥20 / 1k | Bất đồng bộ |
| [reCAPTCHA v3](https://docs.yescaptcha.com/vi/tasks/recaptcha-v3.md) | `RecaptchaV3TaskProxyless` | $3.00 / 1k; 20 điểm/tác vụ · ¥20 / 1k | Bất đồng bộ |
| [reCAPTCHA v3](https://docs.yescaptcha.com/vi/tasks/recaptcha-v3.md) | `RecaptchaV3TaskProxylessM1` | $3.75 / 1k; 25 điểm/tác vụ · ¥25 / 1k | Bất đồng bộ |
| [reCAPTCHA v3](https://docs.yescaptcha.com/vi/tasks/recaptcha-v3.md) | `RecaptchaV3TaskProxylessM1S7` | $4.50 / 1k; 30 điểm/tác vụ · ¥30 / 1k | Bất đồng bộ |
| [reCAPTCHA v3](https://docs.yescaptcha.com/vi/tasks/recaptcha-v3.md) | `RecaptchaV3TaskProxylessM1S9` | $5.25 / 1k; 35 điểm/tác vụ · ¥35 / 1k | Bất đồng bộ |
| [reCAPTCHA v3](https://docs.yescaptcha.com/vi/tasks/recaptcha-v3.md) | `RecaptchaV3EnterpriseTask` | $3.00 / 1k; 20 điểm/tác vụ · ¥20 / 1k | Bất đồng bộ |
| [reCAPTCHA v3](https://docs.yescaptcha.com/vi/tasks/recaptcha-v3.md) | `RecaptchaV3EnterpriseTaskM1` | $3.75 / 1k; 25 điểm/tác vụ · ¥25 / 1k | Bất đồng bộ |
| [hCaptcha](https://docs.yescaptcha.com/vi/tasks/hcaptcha.md) | `HCaptchaTaskProxyless` | $4.50 / 1k; 30 điểm/tác vụ · ¥30 / 1k | Bất đồng bộ |
| [hCaptcha](https://docs.yescaptcha.com/vi/tasks/hcaptcha.md) | `HCaptchaTaskProxylessM1` | $4.50 / 1k; 30 điểm/tác vụ · ¥30 / 1k | Bất đồng bộ |
| [hCaptcha](https://docs.yescaptcha.com/vi/tasks/hcaptcha.md) | `HCaptchaTask` Dùng proxy riêng | $2.25 / 1k; 15 điểm/tác vụ · ¥15 / 1k | Bất đồng bộ |
| [Cloudflare Turnstile](https://docs.yescaptcha.com/vi/tasks/turnstile.md) | `TurnstileTaskProxyless` | $3.75 / 1k; 25 điểm/tác vụ · ¥25 / 1k | Bất đồng bộ |
| [Cloudflare Turnstile](https://docs.yescaptcha.com/vi/tasks/turnstile.md) | `TurnstileTaskProxylessM1` | $4.50 / 1k; 30 điểm/tác vụ · ¥30 / 1k | Bất đồng bộ |
| [Cloudflare Turnstile](https://docs.yescaptcha.com/vi/tasks/turnstile.md) | `TurnstileTask` Dùng proxy riêng | $3.75 / 1k; 25 điểm/tác vụ · ¥25 / 1k | Bất đồng bộ |
| [Trang thử thách Cloudflare](https://docs.yescaptcha.com/vi/tasks/cloudflare-challenge.md) | `CloudFlareTaskS2` Dùng proxy riêng | $3.75 / 1k; 25 điểm/tác vụ · ¥25 / 1k | Bất đồng bộ |
| [Trang thử thách Cloudflare](https://docs.yescaptcha.com/vi/tasks/cloudflare-challenge.md) | `CloudFlareTaskS3` Dùng proxy riêng | $3.00 / 1k; 20 điểm/tác vụ · ¥20 / 1k | Bất đồng bộ |
| [Nhận dạng hình ảnh sang văn bản](https://docs.yescaptcha.com/vi/tasks/image-to-text.md) | `ImageToTextTaskOcrBase` | $0.30 / 1k; 2 điểm/tác vụ · ¥2 / 1k | Đồng bộ |
| [Nhận dạng hình ảnh sang văn bản](https://docs.yescaptcha.com/vi/tasks/image-to-text.md) | `ImageToTextTaskMuggle` | $0.30 / 1k; 2 điểm/tác vụ · ¥2 / 1k | Đồng bộ |
| [Nhận dạng hình ảnh sang văn bản](https://docs.yescaptcha.com/vi/tasks/image-to-text.md) | `ImageToTextTask` | $0.60 / 1k; 4 điểm/tác vụ · ¥4 / 1k | Bất đồng bộ |
| [Nhận dạng hình ảnh sang văn bản](https://docs.yescaptcha.com/vi/tasks/image-to-text.md) | `ImageToTextTaskM1` | $2.25 / 1k; 15 điểm/tác vụ · ¥15 / 1k | Bất đồng bộ |
| [Nhận dạng hình ảnh reCAPTCHA v2](https://docs.yescaptcha.com/vi/tasks/recaptcha-classification.md) | `ReCaptchaV2Classification` | $0.90 / 1k; 6 điểm/tác vụ · ¥6 / 1k | Đồng bộ |
| [Nhận dạng hình ảnh hCaptcha](https://docs.yescaptcha.com/vi/tasks/hcaptcha-classification.md) | `HCaptchaClassification` | $1.20 / 1k; 8 điểm/tác vụ · ¥8 / 1k | Đồng bộ |
| [Nhận dạng hình ảnh FunCaptcha](https://docs.yescaptcha.com/vi/tasks/funcaptcha-classification.md) | `FunCaptchaClassification` | $0.45 / 1k; 3 điểm/tác vụ · ¥3 / 1k | Đồng bộ |
| [Nhận dạng hình ảnh AWS WAF / bCaptcha](https://docs.yescaptcha.com/vi/tasks/aws-bcaptcha-classification.md) | `AwsClassification` | $1.20 / 1k; 8 điểm/tác vụ · ¥8 / 1k | Đồng bộ |
| [Nhận dạng hình ảnh AWS WAF / bCaptcha](https://docs.yescaptcha.com/vi/tasks/aws-bcaptcha-classification.md) | `bCaptchaClassification` | $1.20 / 1k; 8 điểm/tác vụ · ¥8 / 1k | Đồng bộ |
Giá bằng đô la Mỹ chỉ là ước tính theo US$1 ≈ ¥6.67 (2026-10-27). Tác vụ được trừ điểm: 1,000 điểm = ¥1 khi nạp tiền bằng CNY; khi nạp bằng đô la Mỹ (PayPal, tiền điện tử), số tiền được quy đổi sang CNY theo tỷ giá tại thời điểm thanh toán, rồi quy đổi thành điểm.
## Chọn loại nào
| Bạn muốn | Dùng loại | Kết quả trả về |
| --- | --- | --- |
| Lấy token rồi gửi thẳng, không cần bấm chọn ảnh | [reCAPTCHA v2](https://docs.yescaptcha.com/vi/tasks/recaptcha-v2.md), [reCAPTCHA v3](https://docs.yescaptcha.com/vi/tasks/recaptcha-v3.md), [hCaptcha](https://docs.yescaptcha.com/vi/tasks/hcaptcha.md), [Turnstile](https://docs.yescaptcha.com/vi/tasks/turnstile.md) | token, bất đồng bộ |
| Vượt qua trang kiểm tra “Just a moment…” của Cloudflare | [Trang thử thách Cloudflare](https://docs.yescaptcha.com/vi/tasks/cloudflare-challenge.md) | Cookie, User-Agent và nội dung trang, bất đồng bộ |
| Tự bấm chọn ảnh trong trình duyệt | [Nhận dạng hình ảnh reCAPTCHA v2](https://docs.yescaptcha.com/vi/tasks/recaptcha-classification.md), [Nhận dạng hình ảnh hCaptcha](https://docs.yescaptcha.com/vi/tasks/hcaptcha-classification.md), [Nhận dạng hình ảnh FunCaptcha](https://docs.yescaptcha.com/vi/tasks/funcaptcha-classification.md), [Nhận dạng hình ảnh AWS WAF / bCaptcha](https://docs.yescaptcha.com/vi/tasks/aws-bcaptcha-classification.md) | Cần bấm vào những ảnh hoặc vị trí nào, đồng bộ |
| Nhận dạng ký tự trong ảnh | [Nhận dạng captcha ảnh chữ-số](https://docs.yescaptcha.com/vi/tasks/image-to-text.md) | Văn bản, phần lớn là đồng bộ |
Không biết đó là loại captcha nào? Xem [Xác định loại captcha](https://docs.yescaptcha.com/vi/guides/identify-captcha.md).
## Quy tắc đặt tên
- **`Proxyless`**: tải captcha qua mạng của chúng tôi, không cần proxy. Loại không có `Proxyless` trong tên (như `NoCaptchaTask`, `HCaptchaTask`) dùng proxy của bạn, cần truyền các trường proxy, phù hợp khi website đích kiểm tra IP truy cập.
- **Hậu tố như `M1`**: một tuyến khác cho cùng loại captcha, tham số giống nhau, giá khác nhau. Khi một loại có tỷ lệ vượt chưa như ý, có thể đổi sang loại kia, hoặc dùng làm dự phòng cho nhau.
- **`Classification`**: nhận dạng hình ảnh, trả về vị trí cần bấm, không trả về token.
- **`Enterprise`**: reCAPTCHA Enterprise.
## Lưu ý
- Nhận dạng hình ảnh reCAPTCHA v2 tính giá theo kích thước ảnh; nhận dạng hình ảnh hCaptcha không trừ điểm khi không nhận ra mục tiêu, xem trang của từng loại.
- Giá lấy theo trang này; giao diện API trừ điểm theo loại tác vụ, truy vấn kết quả không trừ điểm. Quy tắc tính phí xem [Tính phí và hoàn điểm](https://docs.yescaptcha.com/vi/getting-started/billing.md).
---
# reCAPTCHA v2
> Lấy token reCAPTCHA v2 (bản thường, bản ẩn, bản Enterprise) với YesCaptcha: loại tác vụ và giá, tham số yêu cầu, ví dụ curl/Python/Node.js và kết quả trả về.
Source: https://docs.yescaptcha.com/vi/tasks/recaptcha-v2/ · 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/recaptcha-v2/
Tác vụ reCAPTCHA v2 trả về một token (`gRecaptchaResponse`). Gửi token này cho trang web đích là qua được bước xác minh, không cần bấm chọn hình ảnh. Loại hay dùng nhất là `NoCaptchaTaskProxyless`, giá 15 điểm (≈ $2.25 / 1k) mỗi tác vụ, trả kết quả bất đồng bộ: gọi `createTask` để tạo tác vụ, sau đó cứ 5 giây gọi `getTaskResult` một lần để lấy kết quả. Tác vụ 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 yêu cầu là JSON, xác thực bằng `clientKey` (sao chép trong bảng điều khiển tại [yescaptcha.com](https://yescaptcha.com/)). Tạo tác vụ ở endpoint nào thì truy vấn kết quả ở endpoint đó.
## Trường hợp sử dụng
- Trang web có ô đánh dấu “Tôi không phải là người máy” (I’m not a robot): bản thường.
- Không có ô đánh dấu, chỉ sau khi bấm nút gửi mới hiện câu hỏi hình ảnh: bản ẩn, thêm `"isInvisible": true`.
- Trang tải `recaptcha/enterprise.js`, hoặc địa chỉ yêu cầu có chứa `enterprise`: bản Enterprise, dùng loại có `Enterprise` trong tên.
Nếu không chắc là loại nào, xem [Xác định loại captcha](https://docs.yescaptcha.com/vi/guides/identify-captcha.md). Nếu token có tỷ lệ qua chưa như ý, có thể chuyển sang [nhận dạng hình ảnh reCAPTCHA v2](https://docs.yescaptcha.com/vi/tasks/recaptcha-classification.md): API cho biết cần bấm vào những ảnh nào, bạn tự bấm trong trình duyệt.
## Loại tác vụ và giá
| Loại tác vụ | Giá | Cách trả kết quả | Ghi chú |
| --- | --- | --- | --- |
| `NoCaptchaTaskProxyless` | $2.25 / 1k; 15 điểm/tác vụ · ¥15 / 1k | Bất đồng bộ | |
| `RecaptchaV2TaskProxyless` | $3.00 / 1k; 20 điểm/tác vụ · ¥20 / 1k | Bất đồng bộ | Cùng tham số với NoCaptchaTaskProxyless 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 |
| `NoCaptchaTask` | $2.25 / 1k; 15 điểm/tác vụ · ¥15 / 1k | Bất đồng bộ | Dùng proxy riêng |
| `RecaptchaV2EnterpriseTaskProxyless` | $3.00 / 1k; 20 điểm/tác vụ · ¥20 / 1k | Bất đồng bộ | |
| `RecaptchaV2EnterpriseTask` | $3.00 / 1k; 20 điểm/tác vụ · ¥20 / 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.
- `NoCaptchaTaskProxyless` và `RecaptchaV2TaskProxyless` có tham số giống nhau nhưng đi tuyến khác nhau. Nếu một loại có tỷ lệ qua chưa như ý, hãy thử loại còn lại.
- Các loại không có `Proxyless` trong tên (`NoCaptchaTask`, `RecaptchaV2EnterpriseTask`) tải captcha qua proxy của bạn, cần truyền các trường `proxyType`, `proxyAddress`, `proxyPort`, v.v. Dùng chúng khi trang web đích có yêu cầu về IP truy cập.
## Tham số yêu cầu
Đối tượng `task` của `createTask`:
| 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), tìm trong mã nguồn trang hoặc trong các request mạng; thường không thay đổi |
| `isInvisible` | boolean | Không | Đặt là true cho phiên bản ẩn (invisible); nếu không thì bỏ qua |
| `proxyType` | string | Một số loại | Giao thức proxy: `http`, `https`, `socks4` hoặc `socks5` (Bắt buộc với NoCaptchaTask, RecaptchaV2EnterpriseTask) |
| `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 NoCaptchaTask, RecaptchaV2EnterpriseTask) |
| `proxyPort` | integer | Một số loại | Cổng proxy (Bắt buộc với NoCaptchaTask, RecaptchaV2EnterpriseTask) |
| `proxyLogin` | string | Không | Tên người dùng proxy, nếu proxy yêu cầu xác thực (chỉ NoCaptchaTask, RecaptchaV2EnterpriseTask) |
| `proxyPassword` | string | Không | Mật khẩu proxy, nếu proxy yêu cầu xác thực (chỉ NoCaptchaTask, RecaptchaV2EnterpriseTask) |
| `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ỉ NoCaptchaTask, RecaptchaV2EnterpriseTask) |
| `enterprisePayload` | object | Không | Tham số bổ sung của phiên bản enterprise, ví dụ giá trị `s` của reCAPTCHA Enterprise: `{"s": "..."}`. Bỏ qua nếu trang không dùng (chỉ RecaptchaV2EnterpriseTaskProxyless, RecaptchaV2EnterpriseTask) |
Cách tìm `websiteURL` và `websiteKey`: xem [Tìm tham số reCAPTCHA](https://docs.yescaptcha.com/vi/guides/find-recaptcha-parameters.md).
## Ví dụ yêu cầu
Lấy trang demo chính thức của Google làm ví dụ:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}
```
Mã đầy đủ (tạo tác vụ, cứ 5 giây truy vấn một lần, in token). Trước khi chạy, hãy đặt clientKey vào biến môi trường `YESCAPTCHA_CLIENT_KEY`:
**curl**
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}'
# 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": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})
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: "NoCaptchaTaskProxyless",
websiteURL: "https://www.google.com/recaptcha/api2/demo",
websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
console.log(solution.gRecaptchaResponse);
```
Với bản Enterprise, nếu trang web truyền giá trị `s` cho reCAPTCHA, hãy đặt giá trị đó vào `enterprisePayload`:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "RecaptchaV2EnterpriseTaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "SITE_KEY_OF_THE_PAGE",
"enterprisePayload": {
"s": "S_VALUE_FROM_THE_PAGE"
}
}
}
```
Dùng proxy của bạn:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTask",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
"proxyType": "http",
"proxyAddress": "proxy.example.com",
"proxyPort": 8080,
"proxyLogin": "user",
"proxyPassword": "pass"
}
}
```
## Kết quả trả về
`createTask` trả về ID tác vụ:
```json
{
"errorId": 0,
"taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```
Dùng ID này để gọi `getTaskResult`. Khi tác vụ còn đang xử lý sẽ trả về `{"errorId": 0, "status": "processing"}`, hãy truy vấn lại sau 5 giây; khi hoàn thành sẽ trả về:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
}
}
```
| 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 |
Một tác vụ được xử lý tối đa khoảng 110 giây, quá thời gian sẽ trả về `ERROR_TASK_TIMEOUT` và hoàn điểm. Khi có lỗi, `errorId` bằng 1, hãy xử lý theo `errorCode`, xem [Mã lỗi](https://docs.yescaptcha.com/vi/api/errors.md). Cách gửi token sau khi nhận được: xem [Dùng token để hoàn thành reCAPTCHA](https://docs.yescaptcha.com/vi/guides/submit-recaptcha-token.md).
> **Mẹo:** Token chỉ dùng được một lần, có hiệu lực khoảng 120 giây, nên gửi trong vòng 60 giây sau khi nhận.
## Câu hỏi thường gặp
### Tại sao token của cùng một trang web lúc qua lúc không?
Việc có qua hay không do trang web đích quyết định. Trang web chấm điểm từng lần xác minh và đặt ngưỡng, ngưỡng này có thể thay đổi bất cứ lúc nào, nên tỷ lệ qua khác nhau tùy trang web và không phải token nào cũng qua. Bạn có thể đổi sang loại tác vụ cùng nhóm để so sánh tỷ lệ qua, hoặc chuyển sang [nhận dạng hình ảnh](https://docs.yescaptcha.com/vi/tasks/recaptcha-classification.md).
### Token có hiệu lực trong bao lâu?
Dùng được một lần, có hiệu lực khoảng 120 giây, nên gửi trong vòng 60 giây sau khi nhận. Thời hạn do Google quyết định.
### Nhận dạng thất bại có bị trừ điểm không?
Không. Tác vụ trả về `ERROR_CAPTCHA_UNSOLVABLE` hoặc hết thời gian sẽ tự động hoàn điểm, xem [Tính phí và hoàn điểm](https://docs.yescaptcha.com/vi/getting-started/billing.md).
## 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ố reCAPTCHA](https://docs.yescaptcha.com/vi/guides/find-recaptcha-parameters.md)
- [Dùng token để hoàn thành reCAPTCHA](https://docs.yescaptcha.com/vi/guides/submit-recaptcha-token.md)
- [Nhận dạng hình ảnh reCAPTCHA v2 và mô phỏng bấm chuột (Selenium)](https://docs.yescaptcha.com/vi/guides/recaptcha-click-selenium.md)
---
# reCAPTCHA v3
> Lấy token reCAPTCHA v3 (gồm cả bản Enterprise) bằng YesCaptcha: cách điền pageAction, các loại có điểm cố định 0.7 và 0.9, loại tác vụ và giá, tham số, ví dụ và kết quả trả về.
Source: https://docs.yescaptcha.com/vi/tasks/recaptcha-v3/ · 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/recaptcha-v3/
reCAPTCHA v3 không có ô đánh dấu và không có hình ảnh; trang web chấm điểm người truy cập ở chế độ nền. YesCaptcha trả về một token (`gRecaptchaResponse`) để bạn gửi cho trang web đích. `RecaptchaV3TaskProxyless` có giá 20 điểm (≈ $3.00 / 1k) cho mỗi tác vụ, trả kết quả bất đồng bộ: gọi `createTask` trước, rồi cứ 5 giây gọi lại `getTaskResult` một lần. Nếu nhận dạng thất bại hoặc hết thời gian chờ, hệ thống 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 yêu cầu 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 đó.
## Trường hợp áp dụng
- Mã nguồn trang web có `grecaptcha.execute(...)`, hoặc tải `recaptcha/api.js?render=SITE_KEY`: reCAPTCHA v3 bản thường.
- Trang gọi `grecaptcha.enterprise.execute(...)`, hoặc tải `recaptcha/enterprise.js`: reCAPTCHA v3 Enterprise, dùng `RecaptchaV3EnterpriseTask` hoặc `RecaptchaV3EnterpriseTaskM1`.
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ú |
| --- | --- | --- | --- |
| `RecaptchaV3TaskProxyless` | $3.00 / 1k; 20 điểm/tác vụ · ¥20 / 1k | Bất đồng bộ | |
| `RecaptchaV3TaskProxylessM1` | $3.75 / 1k; 25 điểm/tác vụ · ¥25 / 1k | Bất đồng bộ | |
| `RecaptchaV3TaskProxylessM1S7` | $4.50 / 1k; 30 điểm/tác vụ · ¥30 / 1k | Bất đồng bộ | Yêu cầu điểm 0.7; không cần tham số bổ sung |
| `RecaptchaV3TaskProxylessM1S9` | $5.25 / 1k; 35 điểm/tác vụ · ¥35 / 1k | Bất đồng bộ | Yêu cầu điểm 0.9; không cần tham số bổ sung |
| `RecaptchaV3EnterpriseTask` | $3.00 / 1k; 20 điểm/tác vụ · ¥20 / 1k | Bất đồng bộ | |
| `RecaptchaV3EnterpriseTaskM1` | $3.75 / 1k; 25 điểm/tác vụ · ¥25 / 1k | Bất đồng bộ | |
Giá bằng đô la Mỹ chỉ là ước tính theo US$1 ≈ ¥6.67; tác vụ được trừ điểm.
- `RecaptchaV3TaskProxyless` và `RecaptchaV3TaskProxylessM1` có tham số giống nhau nhưng đi qua đường khác nhau, có thể dùng làm dự phòng cho nhau.
- Khi trang web đích yêu cầu điểm cao, hãy dùng `RecaptchaV3TaskProxylessM1S7` (0.7) hoặc `RecaptchaV3TaskProxylessM1S9` (0.9) với điểm cố định, không cần tham số bổ sung.
## Tham số yêu cầu
| 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), tìm trong mã nguồn trang hoặc trong các request mạng; thường không thay đổi |
| `pageAction` | string | Không | Giá trị action của reCAPTCHA v3; phải khớp với giá trị trang truyền vào `grecaptcha.execute`, nếu không token có thể bị từ chối |
`pageAction` phải khớp với `action` mà trang web truyền vào khi gọi `grecaptcha.execute(SITE_KEY, {action: '...'})`; điền sai thì trang web có thể từ chối token. Cách tìm xem [Tìm tham số reCAPTCHA](https://docs.yescaptcha.com/vi/guides/find-recaptcha-parameters.md).
## Ví dụ yêu cầu
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "SITE_KEY_OF_THE_PAGE",
"pageAction": "login"
}
}
```
**curl**
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "SITE_KEY_OF_THE_PAGE",
"pageAction": "login"
}
}'
# 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": "RecaptchaV3TaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "SITE_KEY_OF_THE_PAGE",
"pageAction": "login",
})
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: "RecaptchaV3TaskProxyless",
websiteURL: "https://example.com/login",
websiteKey: "SITE_KEY_OF_THE_PAGE",
pageAction: "login",
});
console.log(solution.gRecaptchaResponse);
```
Thay `websiteURL`, `websiteKey`, `pageAction` bằng giá trị của trang web đích.
## Kết quả trả về
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
}
}
```
| 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 |
Khi đang xử lý, hệ thống trả về `{"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ách gửi token sau khi nhận được xem [Dùng token để vượt reCAPTCHA](https://docs.yescaptcha.com/vi/guides/submit-recaptcha-token.md).
## Câu hỏi thường gặp
### Vì sao đôi khi trang web không chấp nhận token?
Với v3, trang web đích quyết định dựa trên điểm số, và ngưỡng do trang web đặt có thể thay đổi bất cứ lúc nào, nên không phải token nào cũng qua được. Hãy kiểm tra `pageAction` đã đúng chưa; nếu trang web yêu cầu điểm cao, thử `M1S7`, `M1S9`; cũng có thể so sánh với các loại tương tự khác.
### Điền reCAPTCHA v3 Enterprise như thế nào?
Giống bản thường: điền `websiteURL`, `websiteKey`, `pageAction`, và đổi loại tác vụ thành `RecaptchaV3EnterpriseTask` hoặc `RecaptchaV3EnterpriseTaskM1`.
### Token có hiệu lực trong bao lâu?
Chỉ dùng được một lần, có hiệu lực khoảng 120 giây; nên gửi trong vòng 60 giây.
## 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ố reCAPTCHA](https://docs.yescaptcha.com/vi/guides/find-recaptcha-parameters.md) (gồm cách tìm `pageAction`)
- [Dùng token để vượt reCAPTCHA](https://docs.yescaptcha.com/vi/guides/submit-recaptcha-token.md)
---
# 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)
---
# 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)
---
# Trang thử thách Cloudflare (5 giây)
> Dùng YesCaptcha vượt qua trang kiểm tra "Just a moment..." của Cloudflare (trang thử thách 5 giây) để nhận cookie như cf_clearance, User-Agent và nội dung trang: tham số của CloudFlareTaskS2 và CloudFlareTaskS3, yêu cầu về proxy, kết quả trả về, cách dùng kết quả và các lỗi thường gặp.
Source: https://docs.yescaptcha.com/vi/tasks/cloudflare-challenge/ · Last verified: 2026-10-19
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/cloudflare-challenge/
Trang thử thách Cloudflare (5 giây) là trang kiểm tra chặn toàn bộ trang web và hiển thị “Just a moment…” hoặc “Đang kiểm tra trình duyệt của bạn”. YesCaptcha mở trang qua proxy bạn cung cấp, vượt qua bước kiểm tra, rồi trả về cookie như `cf_clearance`, User-Agent đã dùng, request header, response header và HTML của trang sau khi vượt qua. `CloudFlareTaskS2` có giá 25 điểm (≈ $3.75 / 1k) mỗi tác vụ, `CloudFlareTaskS3` có giá 20 điểm (≈ $3.00 / 1k) mỗi tác vụ; hai loại có cùng tham số, kết quả trả về và hiệu quả, chỉ khác giá. Tác vụ bất đồng bộ, thường mất 6 đến 35 giây, chênh lệch khá nhiều giữa các trang web. Nếu nhận dạng thất bại hoặc hết thời gian chờ, hệ thống 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)
## Khi nào dùng
- Mã nguồn trang có `__cf_chl_rt_tk` hoặc `cdn-cgi/challenge-platform`, tiêu đề là `Just a moment...`: đây là trang thử thách 5 giây. Trang kiểm tra yêu cầu tick ô “Xác nhận bạn là người thật” cũng dùng trang này.
- Nếu chỉ là khung xác minh của Cloudflare nhúng trong biểu mẫu thì đó là [Turnstile](https://docs.yescaptcha.com/vi/tasks/turnstile.md), không dùng trang này.
- Khi dùng thư viện như requests mà nhận về 403 kèm “Just a moment…” nhưng trình duyệt mở trang bình thường: nhiều khả năng chỉ bị chặn do dấu vân tay TLS. Hãy dùng thư viện có thể mô phỏng dấu vân tay TLS của trình duyệt (như curl\_cffi) là request được, không cần vượt trang thử thách.
## Loại tác vụ và giá
| Loại tác vụ | Giá | Cách trả kết quả | Ghi chú |
| --- | --- | --- | --- |
| `CloudFlareTaskS2` | $3.75 / 1k; 25 điểm/tác vụ · ¥25 / 1k | Bất đồng bộ | Dùng proxy riêng |
| `CloudFlareTaskS3` | $3.00 / 1k; 20 điểm/tác vụ · ¥20 / 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.
## Tham số yêu cầu
| 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 nằm sau trang thử thách. Phải là URL công khai bắt đầu bằng `http://` hoặc `https://`; địa chỉ IP nội bộ và tên máy chủ cục bộ hoặc nội bộ như `localhost` sẽ bị từ chối |
| `proxy` | string | Có | Proxy dưới dạng một chuỗi: `http://user:pass@proxy.example.com:8080` (proxy HTTP, thông tin đăng nhập là tùy chọn) hoặc `socks5://proxy.example.com:1080` (không có thông tin đăng nhập). Proxy `https://` và SOCKS5 có thông tin đăng nhập không được hỗ trợ, địa chỉ cục bộ hoặc nội bộ sẽ bị từ chối. Mọi request tới trang đích đều đi qua proxy này |
| `userAgent` | string | Không | Thường không cần điền. Chỉ User-Agent của Chrome trên Linux (máy tính) được sử dụng; các loại khác (Windows, macOS, di động, trình duyệt khác) sẽ bị bỏ qua. Với các request sau đó, luôn dùng `user_agent` trong kết quả |
| `waitLoad` | boolean | Không | Mặc định là false. Nếu là true, sau khi vượt qua kiểm tra, tác vụ sẽ đợi đến khi hoạt động mạng của trang ổn định rồi mới trả về, nhờ đó `content` có thêm nội dung được tải động; mất thêm vài giây |
| `requiredCookies` | array | Không | Danh sách tên Cookie bắt buộc phải lấy được, dạng mảng chuỗi, ví dụ `["cf_clearance"]`. Nếu đặt, tác vụ chỉ thành công khi lấy được tất cả; nếu không sẽ trả về `ERROR_CAPTCHA_UNSOLVABLE` và hoàn điểm. Nếu bỏ qua, tác vụ vẫn cố lấy `cf_clearance`, nhưng vẫn thành công (và bị trừ điểm) với bất kỳ Cookie nào khác lấy được, vì vậy hãy truyền rõ ràng nếu bạn cần `cf_clearance` |
| `blockImage` | boolean | Không | Nếu là true, hình ảnh trên trang đích sẽ không được tải (trừ những hình mà chính bước kiểm tra của Cloudflare cần), giúp tiết kiệm lưu lượng proxy |
| `postData` | object | Không | Nếu đặt, dữ liệu được gửi tới `websiteURL` như một form HTML POST thông thường (`application/x-www-form-urlencoded`): mỗi khóa là một trường form và giá trị được gửi dưới dạng chuỗi, ví dụ `{"name": "hi"}`. Phải là một đối tượng |
### Yêu cầu về proxy
`proxy` là bắt buộc, mọi request mở trang đích đều đi qua proxy này. `cf_clearance` gắn với IP đầu ra, vì vậy khi truy cập trang đích sau đó cũng phải dùng cùng proxy.
| Cách viết | Có hỗ trợ không |
| --- | --- |
| `http://user:pass@proxy.example.com:8080` | Hỗ trợ: proxy http, có tài khoản và mật khẩu |
| `http://proxy.example.com:8080` | Hỗ trợ: proxy http, không có tài khoản và mật khẩu |
| `socks5://proxy.example.com:1080` | Hỗ trợ: proxy socks5, không có tài khoản và mật khẩu; `socks5h://` được xử lý như `socks5://` |
| `socks5://user:pass@proxy.example.com:1080` | Không hỗ trợ, trả về `ERROR_PROXY_INCORRECT`; nếu cần tài khoản và mật khẩu, hãy dùng proxy http |
| `https://proxy.example.com:443` hoặc giao thức khác, hoặc thiếu cổng | Không hỗ trợ, trả về `ERROR_PROXY_INCORRECT` |
| Địa chỉ máy cục bộ, mạng nội bộ hoặc địa chỉ dành riêng như `127.0.0.1`, `192.168.x.x`, `10.x.x.x`, hoặc tên miền phân giải ra các địa chỉ này | Từ chối, trả về `ERROR_PROXY_BANNED` |
> **Được kiểm tra ngay khi tạo tác vụ:** Nếu URL hoặc proxy không hợp lệ, `createTask` trả lỗi ngay và không trừ điểm. Nếu một proxy không kết nối được nhiều lần trong thời gian ngắn, thì trong một khoảng thời gian sau đó, tạo tác vụ với proxy này cũng sẽ trả về `ERROR_PROXY_BANNED`; hãy đổi proxy hoặc thử lại sau.
### User-Agent
Thông thường không cần truyền `userAgent`. Chúng tôi dùng Chrome bản desktop trên Linux để vượt qua kiểm tra, nên chỉ User-Agent của Chrome desktop trên Linux mới được áp dụng; các loại khác (Windows, macOS, điện thoại hoặc trình duyệt khác) sẽ bị bỏ qua: qua thử nghiệm thực tế, khi môi trường trình duyệt thực tế không khớp với User-Agent thì Cloudflare không cho vượt qua. Các request sau đó luôn dùng `user_agent` trong kết quả.
## Ví dụ yêu cầu
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "CloudFlareTaskS3",
"websiteURL": "https://example.com/",
"proxy": "http://user:pass@proxy.example.com:8080",
"requiredCookies": ["cf_clearance"]
}
}
```
- Muốn dùng `CloudFlareTaskS2` thì chỉ đổi `type`, các phần khác giữ nguyên.
- Nếu truyền `requiredCookies` là `["cf_clearance"]`, khi không lấy được `cf_clearance` thì tác vụ thất bại và hoàn điểm; nếu không truyền, trường hợp không lấy được `cf_clearance` mà chỉ có cookie khác vẫn được tính là thành công và bị trừ điểm.
- Nếu cần gửi biểu mẫu, thêm `postData`, ví dụ `{"name": "hi"}`; dữ liệu sẽ được gửi tới `websiteURL` dưới dạng biểu mẫu POST.
Sau khi tạo, gọi `getTaskResult` mỗi 5 giây; quy trình giống các tác vụ bất đồng bộ khác, xem [getTaskResult](https://docs.yescaptcha.com/vi/api/get-task-result.md).
## Kết quả trả về
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36",
"cookies": {
"cf_clearance": "Wq3vXk9...-1760860800-1.2.1.1-..."
},
"request_headers": {
"accept-language": "en-US,en;q=0.9",
"user-agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36"
},
"headers": {
"content-type": "text/html; charset=UTF-8",
"server": "cloudflare"
},
"content": "..."
}
}
```
Giá trị cookie và request header ở trên chỉ mang tính minh họa, hãy dùng dữ liệu thực tế do API trả về.
| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `cookies` | object | Toàn bộ cookie trong trình duyệt sau khi vượt qua bước kiểm tra (đối tượng ánh xạ tên sang giá trị), thường bao gồm `cf_clearance`; nếu bạn đặt `requiredCookies`, mọi cookie trong đó đều được đảm bảo có mặt. Hãy dùng cùng với `user_agent` được trả về và proxy bạn đã cung cấp |
| `user_agent` | string | User-Agent mà trình duyệt thực sự đã dùng để vượt qua bước kiểm tra (Chrome desktop trên Linux). `cf_clearance` gắn với giá trị này, vì vậy hãy dùng nó cho mọi yêu cầu tiếp theo |
| `request_headers` | object | Các request header mà trình duyệt đã gửi trong yêu cầu cuối cùng tới trang đích; nên dùng lại chúng trong các yêu cầu tiếp theo |
| `headers` | object | Các response header của trang đích sau khi vượt qua bước kiểm tra |
| `content` | string | Mã nguồn HTML của trang đích sau khi vượt qua bước kiểm tra |
## Cách dùng kết quả
1. Các request tiếp theo phải dùng **đồng thời** `cookies` trả về, `user_agent` trả về và cùng proxy đã dùng khi tạo tác vụ. `cf_clearance` gắn với User-Agent và IP đầu ra; chỉ cần một trong ba thứ không khớp, trang thử thách 5 giây sẽ xuất hiện lại.
2. Nên gửi kèm request header theo `request_headers`, và dùng dấu vân tay TLS giống trình duyệt (ví dụ tham số `impersonate` của curl\_cffi).
3. `cf_clearance` có thời hạn (do trang đích quy định, có trang lên tới 1 giờ); trong thời hạn này không cần vượt lại. Gửi request quá nhanh có thể khiến Cloudflare chặn IP.
4. Nếu chỉ cần nội dung trang, có thể dùng trực tiếp `content`, không cần request lại lần nữa.
## Lỗi thường gặp
Lỗi trả về khi tạo tác vụ không bị trừ điểm; tác vụ thất bại hoặc hết thời gian chờ sau khi tạo thành công sẽ được tự động hoàn điểm. API chỉ trả về mã lỗi và mô tả chung, hãy đối chiếu nguyên nhân cụ thể theo bảng dưới.
| Mã lỗi | Khi nào trả về | Cách xử lý |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | Khi tạo tác vụ: thiếu `websiteURL` hoặc `proxy` | Bổ sung hai trường bắt buộc |
| `ERROR_ILLEGAL_PARAMETERS` | Khi tạo tác vụ: `websiteURL` không phải URL công khai bắt đầu bằng `http://` / `https://`, `postData` không phải đối tượng, hoặc `requiredCookies` không phải mảng chuỗi. Khi truy vấn kết quả: không phân giải được tên miền của URL đích qua proxy | Sửa tham số; kiểm tra chính tả URL và xem proxy có truy cập được trang này không |
| `ERROR_PROXY_INCORRECT` | Khi tạo tác vụ: proxy sai định dạng, thiếu cổng, dùng proxy `https://` hoặc socks5 có tài khoản và mật khẩu | Sửa theo cách viết trong mục “Yêu cầu về proxy” ở trên; nếu cần tài khoản và mật khẩu thì dùng proxy http |
| `ERROR_PROXY_BANNED` | Khi tạo tác vụ: proxy là địa chỉ máy cục bộ, mạng nội bộ hoặc địa chỉ dành riêng, hoặc proxy này không kết nối được nhiều lần trong thời gian ngắn. Khi truy vấn kết quả: Cloudflare của trang đích chặn thẳng IP của proxy này (trang “Sorry, you have been blocked”, “Access denied”) | Đổi sang proxy khác; IP chất lượng càng tốt càng dễ vượt qua |
| `ERROR_PROXY_CONNECT_REFUSED` | Không kết nối được proxy (bị từ chối kết nối, không phân giải được tên miền của proxy), hoặc khi mở trang qua proxy thì kết nối bị từ chối hoặc bị reset | Kiểm tra địa chỉ và cổng của proxy, xác nhận proxy đang hoạt động và cho phép truy cập từ bên ngoài; nếu vẫn lỗi thì đổi proxy |
| `ERROR_PROXY_CONNECT_TIMEOUT` | Kết nối tới proxy hoặc mở trang qua proxy bị hết thời gian chờ | Đổi sang proxy nhanh và ổn định hơn |
| `ERROR_PROXY_NOT_AUTHORISED` | Tài khoản hoặc mật khẩu của proxy sai | Kiểm tra tài khoản và mật khẩu trong `proxy`; ký tự đặc biệt cần được mã hóa URL |
| `ERROR_PROXY_TLS_ERROR` | Bắt tay TLS bị lỗi khi mở trang qua proxy | Xác nhận địa chỉ, cổng và giao thức của proxy không bị điền sai; nếu vẫn lỗi thì đổi proxy |
| `ERROR_CAPTCHA_UNSOLVABLE` | Không vượt qua kiểm tra trong thời gian quy định, sau khi vượt qua vẫn dừng ở trang kiểm tra, hoặc không lấy được cookie yêu cầu trong `requiredCookies` | Thử lại với proxy khác trước; với một số trang web cụ thể, hãy liên hệ bộ phận hỗ trợ |
| `ERROR_NO_SLOT_AVAILABLE` | Khi tạo tác vụ: hàng đợi đã đầy. Khi truy vấn kết quả: chờ trong hàng đợi quá lâu mà chưa bắt đầu, đã hoàn điểm | Chờ vài giây rồi tạo lại tác vụ |
| `ERROR_TASK_TIMEOUT` | Tác vụ không hoàn thành trong thời gian quy định | Tạo lại tác vụ; nếu liên tục hết thời gian chờ thì thường là do proxy quá chậm |
Xem toàn bộ mã lỗi tại [Mã lỗi](https://docs.yescaptcha.com/vi/api/errors.md).
## Liên quan
- [Xác định loại captcha](https://docs.yescaptcha.com/vi/guides/identify-captcha.md): sự khác nhau giữa trang thử thách 5 giây và Turnstile
- [Cloudflare Turnstile](https://docs.yescaptcha.com/vi/tasks/turnstile.md)
---
# Nhận dạng chữ và số trong ảnh
> Dùng YesCaptcha để đọc chữ cái và chữ số trong ảnh: ImageToTextTaskOcrBase và ImageToTextTaskMuggle trả kết quả đồng bộ; ImageToTextTask và ImageToTextTaskM1 bất đồng bộ, hỗ trợ phân biệt hoa/thường, chỉ chữ số, phép tính; có thể định chế mô hình riêng.
Source: https://docs.yescaptcha.com/vi/tasks/image-to-text/ · 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/image-to-text/
Chuyển một ảnh captcha ký tự sang Base64 rồi gửi lên, bạn sẽ nhận lại chữ cái và chữ số trong ảnh (`solution.text`). `ImageToTextTaskOcrBase` có giá 2 điểm (≈ $0.30 / 1k) cho mỗi ảnh và trả kết quả đồng bộ: chỉ một yêu cầu `createTask` là có kết quả. Khi cần chỉ định phân biệt hoa/thường, chỉ chữ số, phép tính, v.v., hãy dùng `ImageToTextTask` (bất đồng bộ).
- POST `https://api.yescaptcha.com/createTask` (Endpoint quốc tế)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint Trung Quốc)
Nội dung yêu cầu là JSON, xác thực bằng `clientKey`.
## Loại tác vụ và giá
| Loại tác vụ | Giá | Cách trả kết quả | Ghi chú |
| --- | --- | --- | --- |
| `ImageToTextTaskOcrBase` | $0.30 / 1k; 2 điểm/tác vụ · ¥2 / 1k | Đồng bộ | |
| `ImageToTextTaskMuggle` | $0.30 / 1k; 2 điểm/tác vụ · ¥2 / 1k | Đồng bộ | Không hỗ trợ các tùy chọn case/numeric; dùng project\_name để chọn mô hình tùy chỉnh |
| `ImageToTextTask` | $0.60 / 1k; 4 điểm/tác vụ · ¥4 / 1k | Bất đồng bộ | |
| `ImageToTextTaskM1` | $2.25 / 1k; 15 điểm/tác vụ · ¥15 / 1k | Bất đồng bộ | |
Giá bằng đô la Mỹ chỉ là ước tính theo US$1 ≈ ¥6.67; tác vụ được trừ điểm.
| Nhu cầu | Dùng loại nào |
| --- | --- |
| Captcha chữ và số thông thường, rẻ nhất, nhanh nhất | `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle` (đồng bộ) |
| Nhận dạng bằng mô hình được định chế riêng cho bạn | `ImageToTextTaskMuggle` kèm `project_name` |
| Cần phân biệt hoa/thường, chỉ có chữ số, tính giá trị phép tính, giới hạn độ dài | `ImageToTextTask`, `ImageToTextTaskM1` (bất đồng bộ) |
Mỗi loại dùng mô hình và đường xử lý khác nhau, nên với cùng một kiểu ảnh kết quả có thể khác nhau. Hãy thử cả các loại rồi chọn loại phù hợp.
## Tham số yêu cầu
| 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 |
| `body` | string | Có | Ảnh mã hóa Base64, không có tiền tố `data:image/...;base64,` và không có ký tự xuống dòng |
| `project_name` | string | Không | Tên mô hình tùy chỉnh, chỉ `ImageToTextTaskMuggle` hỗ trợ. Bỏ qua để dùng mô hình chữ và số thông dụng. Liên hệ bộ phận hỗ trợ nếu cần mô hình tùy chỉnh (chỉ ImageToTextTaskMuggle) |
| `phrase` | boolean | Không | true nghĩa là đáp án chứa ít nhất một khoảng trắng (chỉ ImageToTextTask, ImageToTextTaskM1) |
| `case` | boolean | Không | true nghĩa là đáp án phân biệt chữ hoa chữ thường (chỉ ImageToTextTask, ImageToTextTaskM1) |
| `numeric` | integer | Không | 0 không có yêu cầu; 1 chỉ gồm chữ số; 2 không chứa chữ số (chỉ ImageToTextTask, ImageToTextTaskM1) |
| `math` | boolean | Không | true nghĩa là ảnh là một phép tính và đáp án là kết quả của phép tính đó (chỉ ImageToTextTask, ImageToTextTaskM1) |
| `minLength` | integer | Không | Độ dài tối thiểu của đáp án; 0 nghĩa là không giới hạn (chỉ ImageToTextTask, ImageToTextTaskM1) |
| `maxLength` | integer | Không | Độ dài tối đa của đáp án; 0 nghĩa là không giới hạn (chỉ ImageToTextTask, ImageToTextTaskM1) |
`body` là chuỗi Base64 của tệp ảnh, ảnh WebP sẽ được tự động chuyển đổi.
> **Chú ý:** Base64 không được có tiền tố `data:image/...;base64,` và không được có ký tự xuống dòng.
## Ví dụ yêu cầu
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "ImageToTextTaskOcrBase",
"body": "BASE64_IMAGE"
}
}
```
Mã đầy đủ (đọc tệp `captcha.png` trong thư mục hiện tại):
**curl**
```bash
# Replace BASE64_IMAGE with the Base64-encoded image
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "ImageToTextTaskOcrBase",
"body": "BASE64_IMAGE"
}
}'
```
**Python**
solve.py
```python
import os
import base64
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):
return call("createTask", {"task": task})["solution"]
# Base64-encode the image (no data: prefix)
with open("captcha.png", "rb") as f:
image_b64 = base64.b64encode(f.read()).decode()
solution = solve({
"type": "ImageToTextTaskOcrBase",
"body": image_b64,
})
print(solution["text"])
```
**Node.js**
solve.mjs
```js
import { readFileSync } from 'node:fs';
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 { solution } = await call('createTask', { task });
return solution;
}
// Base64-encode the image (no data: prefix)
const imageB64 = readFileSync('captcha.png').toString('base64');
const solution = await solve({
type: "ImageToTextTaskOcrBase",
body: imageB64,
});
console.log(solution.text);
```
Tác vụ bất đồng bộ kèm yêu cầu:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "ImageToTextTask",
"body": "BASE64_IMAGE",
"case": true,
"numeric": 0,
"minLength": 4,
"maxLength": 6
}
}
```
## Kết quả trả về
Các loại đồng bộ trả kết quả ngay trong `createTask`:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"text": "LMResm"
},
"taskId": "2376919c-1863-11ec-a012-94e6f7355a0b"
}
```
Các loại bất đồng bộ (`ImageToTextTask`, `ImageToTextTaskM1`) trả về `taskId` trước, sau đó cứ mỗi 5 giây gọi `getTaskResult` để kiểm tra (polling). Khi hoàn tất, `solution` có định dạng giống như trên.
| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `text` | string | Văn bản đã nhận dạng |
## Mô hình định chế riêng
Mô hình chung dùng được cho mọi captcha chữ và số, nhưng độ chính xác thấp hơn một chút so với mô hình được huấn luyện riêng. Nếu ảnh bạn cần nhận dạng luôn có cùng một kiểu, bạn có thể [liên hệ bộ phận hỗ trợ](https://docs.yescaptcha.com/vi/help/contact.md) để định chế mô hình, sau đó chỉ định bằng `ImageToTextTaskMuggle` cùng `project_name`.
## Câu hỏi thường gặp
### Nhận dạng sai có bị trừ điểm không?
Với các loại đồng bộ, hễ trả về kết quả là bị trừ điểm, kể cả khi kết quả sai. Bạn có thể đổi sang loại khác để so sánh hiệu quả, hoặc định chế mô hình riêng.
### Nhận được `ERROR_ZERO_CAPTCHA_FILESIZE` hoặc `ERROR_PARSE_IMAGE_FAIL`?
Base64 của ảnh không đầy đủ, hoặc có tiền tố `data:` hay ký tự xuống dòng. Hãy kiểm tra lại phần mã hóa, xem [Mã lỗi](https://docs.yescaptcha.com/vi/api/errors.md).
## Ví dụ liên quan
- [Bắt đầu nhanh](https://docs.yescaptcha.com/vi/getting-started/quickstart.md): gửi yêu cầu đầu tiên với `ImageToTextTaskOcrBase`
- [Ví dụ Python](https://docs.yescaptcha.com/vi/samples/python.md)
---
# Nhận dạng hình ảnh reCAPTCHA v2
> Dùng YesCaptcha để nhận dạng câu hỏi hình ảnh của reCAPTCHA v2 (ReCaptchaV2Classification): tải lên ảnh 3x3, 4x4 hoặc 1x1 cùng ID câu hỏi, nhận về ngay (đồng bộ) các ô cần nhấp; tính phí theo kích thước ảnh, kèm bảng ID câu hỏi.
Source: https://docs.yescaptcha.com/vi/tasks/recaptcha-classification/ · 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/recaptcha-classification/
`ReCaptchaV2Classification` nhận dạng câu hỏi hình ảnh mà reCAPTCHA v2 hiển thị: bạn gửi ảnh và ID câu hỏi, API trả về các ô cần nhấp, chương trình của bạn sẽ nhấp trong trình duyệt. Loại này **không trả về token**. Kết quả trả về đồng bộ, chỉ cần một yêu cầu `createTask`; mỗi ảnh 3x3 hoặc 4x4 là 6 điểm (≈ $0.90 / 1k), ảnh nhỏ 1x1 rẻ hơn, xem bảng bên dưới.
> **Mẹo:** Nếu không muốn tự viết logic nhấp chuột, bạn có thể dùng [tiện ích trình duyệt](https://docs.yescaptcha.com/vi/extension.md), tiện ích này dựa trên chính API này và tự động nhấp.
- POST `https://api.yescaptcha.com/createTask` (Endpoint quốc tế)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint Trung Quốc)
## Loại tác vụ và giá
| Loại tác vụ | Giá | Cách trả kết quả | Ghi chú |
| --- | --- | --- | --- |
| `ReCaptchaV2Classification` | $0.90 / 1k; 6 điểm/tác vụ · ¥6 / 1k | Đồng bộ | 2 điểm cho ô ảnh 1x1 (100x100); 6 điểm cho 3x3 (300x300) và 4x4 (450x450) |
Giá bằng đô la Mỹ chỉ là ước tính theo US$1 ≈ ¥6.67; tác vụ được trừ điểm.
## Tham số yêu cầu
| 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 |
| `image` | string | Có | Ảnh câu hỏi mã hóa Base64, không có tiền tố `data:` |
| `question` | string | Có | ID câu hỏi, ví dụ `/m/0k4j`; xem "ID câu hỏi" trên trang này |
| `confidence` | number | Không | Ngưỡng độ tin cậy từ 0 đến 1, chỉ dùng cho ảnh 3x3. Nếu đặt (nên bắt đầu với 0.5), mọi ô có độ tin cậy cao hơn ngưỡng sẽ được trả về; nếu bỏ qua, 3 ô có khả năng cao nhất sẽ được trả về |
> **Chú ý:** Ảnh phải được thu phóng về đúng một trong các kích thước chuẩn trong bảng dưới; máy chủ dựa vào kích thước để xác định loại câu hỏi.
| Loại câu hỏi | Kích thước ảnh | Kết quả trả về |
| --- | --- | --- |
| Lưới 3x3 (“Select all images with …”) | 300 × 300 | `objects`: các ô cần nhấp |
| Lưới 4x4 (“Select all squares with …”) | 450 × 450 | `objects`: các ô cần nhấp |
| Ảnh nhỏ 1x1 (ảnh đơn xuất hiện sau khi nhấp ở lưới 3x3) | 100 × 100 | `hasObject`: ảnh này có cần nhấp hay không |
Nếu dùng ảnh chụp màn hình, hãy phân biệt qua nội dung câu hỏi: câu hỏi 3x3 là “Select all images with …”, câu hỏi 4x4 là “Select all squares with …”.
## Ví dụ yêu cầu
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "ReCaptchaV2Classification",
"image": "BASE64_IMAGE",
"question": "/m/0k4j"
}
}
```
## Kết quả trả về
3x3, 4x4:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"objects": [1, 5, 8],
"type": "multi"
},
"taskId": "3a9e8cb8-3871-11ec-9794-94e6f7355a0b"
}
```
Ảnh nhỏ 1x1:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"hasObject": true,
"type": "single"
}
}
```
| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `objects` | array | Chỉ số của các ô cần nhấp, bắt đầu từ 0, từ trái sang phải và từ trên xuống dưới |
| `hasObject` | boolean | Được trả về với ảnh nhỏ 1x1; cho biết ảnh có chứa mục tiêu hay không |
| `type` | string | Loại câu hỏi: `multi` (ảnh lớn 3x3 hoặc 4x4, xem `objects`), `single` (ảnh nhỏ 1x1, xem `hasObject`); `drag` với câu hỏi kéo thả của hCaptcha |
Các ô được đánh số từ 0, từ trái sang phải, từ trên xuống dưới:
## confidence: trả về một lần tất cả các ô phù hợp
Sau khi nhấp xong câu hỏi 3x3, thường sẽ xuất hiện các ảnh nhỏ 1x1 mới cần tiếp tục kiểm tra. Nếu khó lấy các ảnh nhỏ này (ví dụ khi phát triển trên di động), bạn có thể truyền `confidence`:
- Không truyền: với ảnh 3x3, trả về 3 ô có điểm cao nhất (reCAPTCHA yêu cầu nhấp ít nhất 3 ô).
- Có truyền (nên dùng `0.5`): trả về tất cả các ô có điểm cao hơn giá trị này, có thể nhiều hơn hoặc ít hơn 3 ô; nếu không có ô nào phù hợp thì trả về mảng rỗng. Như vậy bạn không cần chụp thêm ảnh nhỏ 1x1.
- Không có tác dụng với ảnh 4x4 và 1x1.
## ID câu hỏi
`question` điền ID của câu hỏi (bắt đầu bằng `/m/`), không phải nội dung chữ của câu hỏi. ID nằm trong phản hồi của yêu cầu mà reCAPTCHA dùng để tải câu hỏi (`reload` hoặc `userverify`), được gửi cùng với ảnh. Bảng dưới là các câu hỏi thường gặp, phần tiếng Trung chỉ để tham khảo:
Tổng cộng 16
| ID câu hỏi | Câu hỏi (tiếng Anh) |
| --- | --- |
| `/m/0pg52` | `taxis` |
| `/m/01bjv` | `bus` |
| `/m/04_sv` | `motorcycles` |
| `/m/013xlm` | `tractors` |
| `/m/01jk_4` | `chimneys` |
| `/m/014xcs` | `crosswalks` |
| `/m/015qff` | `traffic lights` |
| `/m/0199g` | `bicycles` |
| `/m/015qbp` | `parking meters` |
| `/m/0k4j` | `cars` |
| `/m/015kr` | `bridges` |
| `/m/019jd` | `boats` |
| `/m/0cdl1` | `palm trees` |
| `/m/09d_r` | `mountains or hills` |
| `/m/01pns0` | `fire hydrant` |
| `/m/01lynh` | `stairs` |
Không có câu hỏi phù hợp
Nếu trả về `ERROR_UNKNOWN_QUESTION` nghĩa là ID bị điền sai hoặc câu hỏi này chưa được hỗ trợ; `ERROR_UNKNOW_450x450_QUESTION` nghĩa là câu hỏi này chưa hỗ trợ ảnh 4x4, chỉ cần làm mới trên trang web để đổi câu hỏi khác.
## Báo cáo và hoàn điểm
Nếu nhấp xong mà xác minh thất bại, bạn có thể báo cáo bằng [report](https://docs.yescaptcha.com/vi/api/report.md) trong vòng 1 giờ; khoảng 24 giờ sau sẽ quyết toán hoàn điểm, xem quy tắc tại [Tính phí và hoàn điểm](https://docs.yescaptcha.com/vi/getting-started/billing.md). Trường hợp xác minh thành công cũng nên dùng report để báo cáo `isSuccess: true`.
## Hướng dẫn liên quan
- [Mô phỏng nhấp chuột nhận dạng hình ảnh reCAPTCHA v2 (Selenium)](https://docs.yescaptcha.com/vi/guides/recaptcha-click-selenium.md)
- [reCAPTCHA v2 (trả về token)](https://docs.yescaptcha.com/vi/tasks/recaptcha-v2.md)
---
# Nhận dạng hình ảnh hCaptcha
> Dùng YesCaptcha để nhận dạng câu hỏi hình ảnh của hCaptcha (HCaptchaClassification): chọn trong lưới 3×3, nhấp vào vị trí chỉ định, kéo đến vị trí chỉ định, câu hỏi động; trả kết quả đồng bộ, không trừ điểm khi không nhận ra mục tiêu.
Source: https://docs.yescaptcha.com/vi/tasks/hcaptcha-classification/ · 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-classification/
`HCaptchaClassification` nhận dạng các câu hỏi hình ảnh mà hCaptcha hiển thị: bạn gửi câu hỏi và hình ảnh, kết quả trả về cho biết nên chọn những ảnh nào, nhấp vào vị trí nào hoặc kéo từ đâu đến đâu, chương trình của bạn sẽ thao tác trong trình duyệt. Loại này **không trả về token**. Kết quả trả về đồng bộ, mỗi lần 8 điểm (≈ $1.20 / 1k), không trừ điểm khi không nhận ra mục tiêu (kết quả rỗng).
> **Mẹo:** Nếu không muốn tự viết logic nhấp chuột, bạn có thể dùng trực tiếp [tiện ích trình duyệt](https://docs.yescaptcha.com/vi/extension.md), tiện ích hỗ trợ tất cả các dạng câu hỏi này. Nếu cần token thay vì vị trí nhấp, hãy dùng [hCaptcha](https://docs.yescaptcha.com/vi/tasks/hcaptcha.md).
- POST `https://api.yescaptcha.com/createTask` (Endpoint quốc tế)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint Trung Quốc)
## Loại tác vụ và giá
| Loại tác vụ | Giá | Cách trả kết quả | Ghi chú |
| --- | --- | --- | --- |
| `HCaptchaClassification` | $1.20 / 1k; 8 điểm/tác vụ · ¥8 / 1k | Đồng bộ | Không trừ điểm khi không tìm thấy mục tiêu |
Giá bằng đô la Mỹ chỉ là ước tính theo US$1 ≈ ¥6.67; tác vụ được trừ điểm.
## Tham số yêu cầu
| 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 |
| `queries` | array | Có | Danh sách ảnh câu hỏi được mã hóa Base64, theo thứ tự trên trang (lưới 3×3 có 9 ảnh nhỏ) |
| `question` | string | Không | Toàn bộ câu hỏi như hiển thị trên trang (khuyến nghị tiếng Trung giản thể hoặc tiếng Anh), ví dụ `Please click each image containing a bicycle`. Gửi ít nhất một trong `question` và `anchors`; khuyến nghị gửi cả hai |
| `anchors` | array | Không | Danh sách ảnh mẫu (ảnh nhỏ hiển thị cạnh câu hỏi) được mã hóa Base64; bắt buộc với các câu hỏi có ảnh mẫu |
- `question` lấy nguyên câu hỏi hiển thị trên trang, không cần dịch; nên chuyển hCaptcha sang tiếng Trung giản thể hoặc tiếng Anh. Các câu hỏi mới thường được hỗ trợ rất nhanh, các loại hoàn toàn mới được hỗ trợ trong vòng 3 ngày làm việc.
> **Chú ý:** Nếu góc trên bên phải của câu hỏi có ảnh mẫu nhỏ, bạn phải đưa ảnh đó vào `anchors`. Những câu hỏi bắt buộc phải xem ảnh mẫu mới trả lời được sẽ không nhận dạng được nếu thiếu `anchors`.
## Chọn trong lưới 3×3
Câu hỏi có dạng “Hãy nhấp vào mọi hình ảnh chứa …”, bên dưới có 9 ảnh nhỏ. `queries` chứa Base64 của 9 ảnh nhỏ theo thứ tự:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "HCaptchaClassification",
"question": "Please click each image containing a bicycle",
"queries": ["BASE64_IMAGE_1", "BASE64_IMAGE_2"]
}
}
```
Kết quả trả về:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"objects": [true, false, false, true, true, false, true, true, false],
"top_k": [0, 3, 4, 6, 7],
"confidences": [1.0, 0.0, 0.0, 1.0, 1.0, 0.0, 1.0, 1.0, 0.0]
}
}
```
`objects` và `top_k` mang cùng ý nghĩa: `objects` cho biết từng ảnh có phải mục tiêu hay không, `top_k` là thứ tự của các ảnh mục tiêu (bắt đầu từ 0). Chỉ cần nhấp vào các ảnh đó.
## Nhấp vào vị trí chỉ định
Câu hỏi có dạng “Hãy nhấp vào …”, bên dưới là một ảnh lớn, bạn cần nhấp vào một (hoặc vài) vị trí trên ảnh.
1. `question` lấy từ câu hỏi trên trang; nếu có ảnh mẫu nhỏ thì đưa vào `anchors`.
2. `queries` chứa một ảnh: tốt nhất dùng ảnh gốc xuất trực tiếp từ canvas (nên chuyển sang JPG); nếu chỉ chụp màn hình được thì chụp vùng ảnh lớn trong khung đỏ bên dưới, không thừa không thiếu.
3. `box` trả về là các tọa độ cần nhấp, lần lượt là x1, y1, x2, y2…, lấy góc trên bên trái của ảnh đã tải lên làm gốc.
4. Khi kích thước ảnh tải lên khác với kích thước hiển thị trên trang thì phải quy đổi: x trên trang = x trả về × chiều rộng hiển thị ÷ chiều rộng ảnh tải lên (y tương tự). Ví dụ trả về x = 769, canvas hiển thị rộng 350, ảnh tải lên rộng 1000, thì trên trang cần nhấp 769 × 350 ÷ 1000 ≈ 269.
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "HCaptchaClassification",
"question": "Please click on the entity present in the sample image.",
"anchors": ["BASE64_ANCHOR_1", "BASE64_ANCHOR_2", "BASE64_ANCHOR_3"],
"queries": ["BASE64_OF_THE_BIG_IMAGE"]
}
}
```
Kết quả trả về:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"box": ["221", "213"]
}
}
```
Khi cần nhấp nhiều mục tiêu, `box` chứa lần lượt nhiều cặp tọa độ: `["221", "213", "340", "118", ...]`.
## Kéo đến vị trí chỉ định
Câu hỏi có dạng “Kéo … đến …”, bạn cần kéo mảnh nhỏ bên phải đến vị trí tương ứng trong ảnh.
1. `question` lấy từ câu hỏi trên trang.
2. Chụp một ảnh đưa vào `queries`, trong ảnh phải có **đồng thời** mảnh cần kéo và vị trí đích, mỗi cạnh của ảnh không nhỏ hơn 260 pixel.
3. Mỗi phần tử trong `box` trả về là một lần kéo: `start` là vị trí của mảnh, `end` là vị trí cần kéo đến. Nếu có nhiều mảnh thì kéo lần lượt từng mảnh.
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"type": "drag",
"box": [
{
"start": [644, 218],
"end": [239, 315]
}
]
}
}
```
Nếu bạn lấy được dữ liệu giao thức (ảnh của mảnh, tọa độ của mảnh và ảnh nền lớn) thay vì ảnh chụp màn hình, trước hết hãy ghép các mảnh vào ảnh lớn theo tọa độ, tạo ra ảnh giống với ảnh chụp màn hình của trang rồi mới gửi.
## Câu hỏi động
Khi ảnh của câu hỏi là ảnh động, hãy đưa Base64 của ảnh động (GIF hoặc định dạng tương tự) vào `queries`. Nên dùng ảnh động dài ít nhất 3 giây, tốt nhất 5 đến 6 giây, tốc độ khung hình khoảng 12 FPS.
## Báo cáo và hoàn điểm
Nếu sau khi nhấp mà xác minh thất bại, bạn có thể báo cáo bằng [report](https://docs.yescaptcha.com/vi/api/report.md) trong vòng 1 giờ, khoảng 24 giờ sau sẽ quyết toán hoàn điểm, quy tắc xem tại [Tính phí và hoàn điểm](https://docs.yescaptcha.com/vi/getting-started/billing.md).
## Hướng dẫn liên quan
- [Nhận dạng hình ảnh hCaptcha và mô phỏng nhấp chuột (Selenium)](https://docs.yescaptcha.com/vi/guides/hcaptcha-click-selenium.md)
---
# Nhận dạng hình ảnh FunCaptcha
> Dùng YesCaptcha để nhận dạng câu đố hình ảnh của FunCaptcha (Arkose Labs) (FunCaptchaClassification): tải lên ảnh câu đố (lưới 6 ô hoặc ảnh mũi tên ghép trái-phải) cùng câu hỏi tiếng Anh, nhận ngay kết quả đồng bộ là nên chọn ảnh thứ mấy; hỗ trợ mọi dạng câu đố.
Source: https://docs.yescaptcha.com/vi/tasks/funcaptcha-classification/ · Last verified: 2026-10-16
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/funcaptcha-classification/
`FunCaptchaClassification` nhận dạng câu đố hình ảnh của FunCaptcha (Arkose Labs): bạn gửi ảnh câu đố và câu hỏi tiếng Anh, API trả về nên chọn ảnh thứ mấy, còn chương trình của bạn sẽ click trong trình duyệt. Loại này **không trả về token**. Kết quả trả về đồng bộ, mỗi lần 3 điểm (≈ $0.45 / 1k).
> **Mẹo:** Nếu không muốn viết code, hãy dùng [tiện ích trình duyệt](https://docs.yescaptcha.com/vi/extension.md) để tự động giải ngay trên trang web.
- POST `https://api.yescaptcha.com/createTask` (Endpoint quốc tế)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint Trung Quốc)
## Loại tác vụ và giá
| Loại tác vụ | Giá | Cách trả kết quả | Ghi chú |
| --- | --- | --- | --- |
| `FunCaptchaClassification` | $0.45 / 1k; 3 điểm/tác vụ · ¥3 / 1k | Đồng bộ | |
Giá bằng đô la Mỹ chỉ là ước tính theo US$1 ≈ ¥6.67; tác vụ được trừ điểm.
## Tham số yêu cầu
| 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 |
| `image` | string | Có | Ảnh câu hỏi mã hóa Base64, không có tiền tố `data:` |
| `question` | string | Có | Nội dung câu hỏi bằng tiếng Anh (ví dụ `Pick the image that is the correct way up`); các câu hỏi được hỗ trợ được liệt kê trong trang này |
- `image` chỉ chứa phần ảnh của câu đố (lưới 6 ô, hoặc ảnh ghép trái-phải của câu đố mũi tên); đừng chụp lẫn tiêu đề và nút bấm phía trên. Ảnh chụp phải đầy đủ, thiếu một phần sẽ làm giảm độ chính xác. Lưới 6 ô xếp dọc có thể tải lên nguyên ảnh gốc.
- `question` là toàn văn câu hỏi tiếng Anh hiển thị trên trang, giữ đúng chữ hoa, chữ thường, không tự dịch. Nếu trang đang hiển thị ngôn ngữ khác, hãy chuyển captcha sang tiếng Anh trước. Máy chủ dựa vào câu hỏi để xác định dạng câu đố, vì vậy câu hỏi phải chính xác.
## Ví dụ yêu cầu
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "FunCaptchaClassification",
"image": "BASE64_IMAGE",
"question": "Pick the bread"
}
}
```
## Kết quả trả về
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"objects": [4],
"labels": ["parrot", "panda", "octopus", "owl", "bread", "dog"]
},
"taskId": "04a3fa76-11a0-11ed-a58c-0ef20f419382"
}
```
| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `objects` | array | Chỉ số của ảnh cần chọn, bắt đầu từ 0, từ trái sang phải và từ trên xuống dưới |
| `labels` | array | Các nhãn đã nhận dạng |
`objects: [4]` nghĩa là chọn ảnh thứ 5 (chỉ số bắt đầu từ 0, từ trái sang phải, từ trên xuống dưới). Một câu đố thường có vài vòng liên tiếp; mỗi vòng cần chụp lại ảnh và gọi lại API.
## Câu hỏi được hỗ trợ
**Hỗ trợ mọi dạng câu đố**, không cần tra danh sách câu hỏi trước: chỉ cần gửi câu hỏi tiếng Anh và ảnh câu đố trên trang. Nếu nhận được `ERROR_UNKNOWN_QUESTION`, hãy [liên hệ hỗ trợ](https://docs.yescaptcha.com/vi/help/contact.md).
Dạng phổ biến hiện nay là câu đố mũi tên ghép trái-phải: bên trái là mẫu để đối chiếu, bên phải là ảnh hiện tại, bạn dùng mũi tên trên trang để đổi ảnh bên phải cho đến khi tìm được ảnh khớp với câu hỏi. Hãy tải lên toàn bộ ảnh (cả hai nửa trái và phải) đúng như hiển thị trên trang, ví dụ:
`Use the arrows to change the number of objects until it matches the left image`Số lượng khớp với ảnh bên trái
`use the arrows to choose the image where all the darts add up to the number in the left image`Tổng các số trên phi tiêu bằng số ở ảnh bên trái
`use the arrows to find the jigsaw puzzle that is missing the puzzle piece shown on the left`Thiếu đúng mảnh ghép ở bên trái
`find the image that has the prize on the left held by the claw in the machine on the right`Chiếc càng đang gắp phần thưởng ở bên trái
Dạng còn lại là câu đố chọn ảnh trong lưới 6 ô (ví dụ `Pick the bread`): chỉ cần tải lên phần lưới 6 ô, xem ví dụ yêu cầu ở trên.
## Báo cáo và hoàn điểm
Nếu một nhóm câu đố cuối cùng gửi lên bị thất bại mà bạn không biết vòng nào sai, có thể báo cáo cả nhóm ID tác vụ cùng lúc bằng [report](https://docs.yescaptcha.com/vi/api/report.md) (trong vòng 1 giờ). Khoảng 24 giờ sau hệ thống sẽ quyết toán và hoàn điểm; quy tắc xem tại [Tính phí và hoàn điểm](https://docs.yescaptcha.com/vi/getting-started/billing.md).
---
# Nhận dạng hình ảnh AWS WAF / bCaptcha
> Dùng YesCaptcha để nhận dạng câu hỏi hình ảnh lưới 3×3 của AWS WAF CAPTCHA và bCaptcha (AwsClassification, bCaptchaClassification): tải lên toàn bộ ảnh và câu hỏi, nhận về đồng bộ các ô cần nhấp.
Source: https://docs.yescaptcha.com/vi/tasks/aws-bcaptcha-classification/ · 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/aws-bcaptcha-classification/
`AwsClassification` nhận dạng câu hỏi hình ảnh lưới 3×3 của AWS WAF CAPTCHA, `bCaptchaClassification` nhận dạng câu hỏi hình ảnh lưới 3×3 của bCaptcha: gửi toàn bộ ảnh và câu hỏi, API trả về cần nhấp vào những ô nào, chương trình của bạn sẽ nhấp trong trình duyệt. Các loại này **không trả về token**. Trả về đồng bộ, mỗi lần 8 điểm (≈ $1.20 / 1k).
Nếu không muốn viết code, bạn có thể dùng [tiện ích trình duyệt](https://docs.yescaptcha.com/vi/extension.md).
- POST `https://api.yescaptcha.com/createTask` (Endpoint quốc tế)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint Trung Quốc)
## Loại tác vụ và giá
| Loại tác vụ | Giá | Cách trả kết quả | Ghi chú |
| --- | --- | --- | --- |
| `AwsClassification` | $1.20 / 1k; 8 điểm/tác vụ · ¥8 / 1k | Đồng bộ | |
| `bCaptchaClassification` | $1.20 / 1k; 8 điểm/tác vụ · ¥8 / 1k | Đồng bộ | |
Giá bằng đô la Mỹ chỉ là ước tính theo US$1 ≈ ¥6.67; tác vụ được trừ điểm.
Hai loại này có cùng tham số và định dạng kết quả; chọn theo nguồn của captcha: AWS WAF dùng `AwsClassification`, bCaptcha dùng `bCaptchaClassification`.
## Tham số yêu cầu
| 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 |
| `queries` | string | Có | Base64 của toàn bộ ảnh lưới 3×3 (một ảnh duy nhất) |
| `question` | string | Không | Toàn bộ câu hỏi như hiển thị trên trang, ví dụ `Select all hats`; các ngôn ngữ khác sẽ được tự động dịch |
`queries` chứa **toàn bộ** ảnh lưới 3×3 (một ảnh, không phải 9 ảnh nhỏ); `question` lấy nguyên câu hỏi trên trang web, tiếng Trung hoặc tiếng Anh đều được, các ngôn ngữ khác sẽ được tự động dịch.
## Ví dụ yêu cầu
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "AwsClassification",
"queries": "BASE64_IMAGE",
"question": "Select all hats"
}
}
```
## Kết quả trả về
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"label": "Select All Hats",
"objects": [false, true, false, false, true, true, true, true, false],
"top_k": [1, 4, 5, 6, 7],
"confidences": [0.0, 1.0, 0.0, 0.255, 1.0, 1.0, 0.9637, 0.9999, 0.0]
},
"taskId": "2053f690-3c3b-11f0-8ffb-d2c180657082"
}
```
| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `label` | string | Mục tiêu của câu hỏi đã nhận dạng |
| `objects` | array | Mỗi ô trong 9 ô có phải là mục tiêu hay không (true / false), từ trái sang phải và từ trên xuống dưới |
| `top_k` | array | Chỉ số (từ 0) của các ảnh là mục tiêu; ý nghĩa giống `objects`, dùng một trong hai |
| `confidences` | array | Độ tin cậy của từng kết quả |
9 ô được đánh số từ 0 đến 8 theo lưới 3×3, từ trái sang phải, từ trên xuống dưới. `objects` và `top_k` có cùng ý nghĩa, chỉ cần dùng một trong hai: nhấp vào các ô có `objects` là `true`, hoặc các số thứ tự trong `top_k`.
## Báo cáo và hoàn điểm
Nếu xác minh thất bại sau khi nhấp, bạn có thể dùng [report](https://docs.yescaptcha.com/vi/api/report.md) để báo cáo trong vòng 1 giờ; khoảng 24 giờ sau sẽ quyết toán hoàn điểm. Quy tắc xem tại [Thanh toán và hoàn điểm](https://docs.yescaptcha.com/vi/getting-started/billing.md).
---
# YesCaptcha Assistant - tiện ích trình duyệt
> YesCaptcha Assistant (tiện ích trình duyệt) tự động nhận dạng và nhấp captcha reCAPTCHA, hCaptcha, FunCaptcha, AWS WAF, v.v. trên Chrome và Firefox. Tiện ích miễn phí, chỉ trừ điểm theo các API dùng để nhận dạng. Có liên kết cửa hàng, gói cài đặt và video hướng dẫn cài trên Chrome, BitBrowser, Kiwi Browser.
Source: https://docs.yescaptcha.com/vi/extension/ · Last verified: 2026-10-24
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/extension/
YesCaptcha Assistant là tiện ích trình duyệt cho Chrome và Firefox: khi mở trang có captcha, tiện ích gửi hình ảnh captcha đến YesCaptcha để nhận dạng rồi tự động nhấp, không cần viết code. Bản thân tiện ích miễn phí; khi nhận dạng sẽ trừ điểm theo các API được dùng, dùng chung tài khoản và số dư với API.
## Tiện ích làm được gì
- Tự động nhận dạng và nhấp các câu hỏi bằng hình ảnh của reCAPTCHA v2, hCaptcha, FunCaptcha, AWS WAF, bCaptcha.
- Captcha ký tự thông thường: nhấp chuột phải vào ảnh và chọn “Mark as captcha source”, nhấp chuột phải vào ô nhập và chọn “Put captcha answer here”; tiện ích sẽ nhận dạng và điền vào.
- Trong phần cài đặt, bạn có thể bật/tắt riêng từng loại captcha, chỉnh tốc độ nhấp, số lần thử lại khi thất bại, v.v.
> **Ghi chú:** Không phải trang web nào cũng vượt qua được, nên dùng thử trước.
## Cài đặt
**Cài từ cửa hàng (khuyến nghị, tự động cập nhật):**
- Chrome (và các trình duyệt nhân Chromium như Edge): [Chrome Web Store](https://chromewebstore.google.com/detail/yescaptcha-assistant/jiofmdifioeejeilfkpegipdjiopiekl)
- Firefox: [Firefox Add-ons](https://addons.mozilla.org/firefox/addon/yescaptcha-assistant/)
Mở trang tiện ích trên Chrome Web Store, nhấp “Thêm vào Chrome”, rồi nhấp biểu tượng tiện ích trên thanh công cụ và điền `clientKey`:
Trình duyệt của bạn không phát được video này. Hãy tải xuống để xem: [Video: cài từ Chrome Web Store (34 giây)](https://docs.yescaptcha.com/videos/extension-chrome-store.mp4)
Video: cài từ Chrome Web Store (34 giây)
**Nếu không mở được cửa hàng, hãy tải gói cài đặt:**
Phiên bản Chrome
Phiên bản
1.4.12
Dung lượng
1.1 MB
Cập nhật
2026-11-10
[Tải xuống](https://api.yescaptcha.com/extension/chrome/latest)[Chrome Web Store](https://chromewebstore.google.com/detail/yescaptcha-assistant/jiofmdifioeejeilfkpegipdjiopiekl)
Phiên bản Firefox
Phiên bản
0.4.6
Dung lượng
0.9 MB
Cập nhật
2026-10-31
[Tải xuống](https://api.yescaptcha.com/extension/firefox/latest)[Firefox Add-ons](https://addons.mozilla.org/firefox/addon/yescaptcha-assistant/)
Phiên bản trên cửa hàng Firefox có thể cũ hơn gói cài đặt ở đây; cần bản mới nhất thì dùng gói cài đặt.
### Cài Chrome bằng gói cài đặt
1. Tải tệp zip và giải nén vào một thư mục cố định.
2. Mở `chrome://extensions` trên thanh địa chỉ, bật “Chế độ nhà phát triển” ở góc trên bên phải.
3. Nhấp “Tải tiện ích đã giải nén” và chọn thư mục vừa giải nén.
4. Nhấp biểu tượng tiện ích trên thanh công cụ và điền `clientKey` của bạn.
Bạn cũng có thể trước khi tải, dùng trình soạn thảo văn bản mở tệp `config.js` đã giải nén, điền `clientKey` của bạn vào giữa cặp dấu nháy trong `clientKey: ''` rồi lưu lại; sau khi cài xong không cần điền nữa. Cách này tiện hơn khi cài tiện ích trên nhiều môi trường trình duyệt.
Trình duyệt của bạn không phát được video này. Hãy tải xuống để xem: [Video: cài Chrome bằng gói cài đặt, điền sẵn clientKey trong config.js (44 giây, video quay bằng phiên bản cũ, các bước giống nhau)](https://docs.yescaptcha.com/videos/extension-chrome-zip.mp4)
Video: cài Chrome bằng gói cài đặt, điền sẵn clientKey trong config.js (44 giây, video quay bằng phiên bản cũ, các bước giống nhau)
> **Chú ý:** Sau đó không được xóa hoặc di chuyển thư mục đã giải nén, nếu không trình duyệt sẽ không tải được tiện ích. Tiện ích cài bằng gói cài đặt không tự động cập nhật; khi có phiên bản mới cần tải lại.
### Cài Firefox bằng gói cài đặt
1. Tải tệp `.xpi`.
2. Mở `about:addons` trên thanh địa chỉ, nhấp biểu tượng bánh răng, chọn “Cài đặt tiện ích từ tệp”, rồi chọn tệp vừa tải.
3. Nhấp biểu tượng tiện ích trên thanh công cụ và điền `clientKey` của bạn.
## Cài trong BitBrowser
BitBrowser và các trình duyệt chống phát hiện (anti-detect browser) khác dùng nhân Chrome; tiện ích cần được thêm trong “Extension Center” (扩展中心) của trình duyệt, sau khi thêm có thể gán cho tất cả cửa sổ hoặc cửa sổ chỉ định. Các bước và video dưới đây được quay bằng BitBrowser 6.0 với giao diện tiếng Trung; phiên bản mới hơn có thể hơi khác.
### Thêm từ Chrome Web Store
1. Ở thanh bên trái của BitBrowser, nhấp “Extension Center” (扩展中心), nhấp “Thêm tiện ích tùy chỉnh” (添加自定义扩展), rồi chọn “Thêm tiện ích từ Chrome Web Store” (添加 Chrome 商店扩展).
2. Dán địa chỉ Chrome Web Store của tiện ích `https://chromewebstore.google.com/detail/yescaptcha-assistant/jiofmdifioeejeilfkpegipdjiopiekl` vào ô “URL chi tiết tiện ích” (扩展详情 URL), nhấp nút bên phải ô nhập để nhận diện; khi nhận ra “YesCaptcha Assistant” thì nhấp “OK” (确定).
3. Sau khi thêm, nhấp “Cài đặt” (设置) trên thẻ của YesCaptcha Assistant, chọn nơi bật tiện ích: tất cả cửa sổ, hoặc chọn cửa sổ chỉ định rồi tích vào các cửa sổ cần dùng, nhấp “OK”.
4. Mở một cửa sổ trình duyệt, nhấp biểu tượng tiện ích trên thanh công cụ, tìm YesCaptcha Assistant và điền `clientKey` của bạn; thấy số dư hiện ra là đã cài xong.
Trình duyệt của bạn không phát được video này. Hãy tải xuống để xem: [Video: thêm từ Chrome Web Store trong BitBrowser (30 giây)](https://docs.yescaptcha.com/videos/extension-bit-store.mp4)
Video: thêm từ Chrome Web Store trong BitBrowser (30 giây)
### Thêm bằng gói cài đặt
1. Tải gói cài đặt phiên bản Chrome ở trên và giải nén vào một thư mục cố định.
2. (Tùy chọn) Dùng trình soạn thảo văn bản mở `config.js` trong thư mục, điền `clientKey` của bạn vào giữa cặp dấu nháy trong `clientKey: ''` rồi lưu lại. Như vậy mỗi cửa sổ sau khi cài xong không cần điền lại.
3. Trong “Extension Center”, nhấp “Thêm tiện ích tùy chỉnh” (添加自定义扩展), chọn “Thêm tiện ích cục bộ” (添加本地扩展), trong phần “Tải lên tiện ích” (上传扩展) chọn thư mục vừa giải nén (cấp có chứa `manifest.json`), nhấp “OK” (确定).
4. Sau khi tải lên thành công, nhấp “Cài đặt” (设置) trên thẻ của YesCaptcha Assistant, chọn cách bật (tất cả cửa sổ hoặc cửa sổ chỉ định), nhấp “OK”.
5. Mở cửa sổ trình duyệt, nhấp YesCaptcha Assistant trong biểu tượng tiện ích; thấy ClientKey và số dư là đã cài xong.
Trình duyệt của bạn không phát được video này. Hãy tải xuống để xem: [Video: thêm bằng gói cài đặt trong BitBrowser (46 giây, video quay bằng phiên bản cũ, các bước giống nhau)](https://docs.yescaptcha.com/videos/extension-bit-zip.mp4)
Video: thêm bằng gói cài đặt trong BitBrowser (46 giây, video quay bằng phiên bản cũ, các bước giống nhau)
## Dùng trên điện thoại Android (Kiwi Browser)
> **Chú ý:** Kiwi Browser đã ngừng được bảo trì từ tháng 1 năm 2025 và bị gỡ khỏi Google Play, sau đó không còn cập nhật và bản vá bảo mật. Các bước và video dưới đây lấy từ tài liệu cũ, dành cho người dùng vẫn đang dùng Kiwi Browser; phiên bản tiện ích hiện tại chưa được kiểm thử lại trên Kiwi Browser.
1. Tải gói cài đặt phiên bản Chrome (`.zip`) về điện thoại, không cần giải nén. Nếu cần điền sẵn ClientKey, hãy giải nén trên máy tính, sửa `config.js`, rồi nén lại thành zip (`manifest.json` phải nằm ở cấp ngoài cùng của tệp nén).
2. Trong Kiwi Browser, nhấp menu ở góc trên bên phải, chọn “Extensions”.
3. Bật “Developer mode”, nhấp “+ (from .zip/.crx/.user.js)” và chọn gói cài đặt đã tải.
4. Nhấp menu ở góc trên bên phải lần nữa, YesCaptcha Assistant sẽ hiện ở dưới cùng; mở ra và điền `clientKey` của bạn, thấy số dư hiện ra là đã cài xong.
Trình duyệt của bạn không phát được video này. Hãy tải xuống để xem: [Video: cài trong Kiwi Browser (16 giây, video quay bằng phiên bản cũ, các bước giống nhau)](https://docs.yescaptcha.com/videos/extension-kiwi.mp4)
Video: cài trong Kiwi Browser (16 giây, video quay bằng phiên bản cũ, các bước giống nhau)
## Thiết lập
1. Đăng ký và nạp tiền tại [yescaptcha.com](https://yescaptcha.com/), sao chép `clientKey` trong bảng điều khiển, xem [Bắt đầu nhanh](https://docs.yescaptcha.com/vi/getting-started/quickstart.md).
2. Nhấp biểu tượng tiện ích, điền ClientKey vào bảng cài đặt; thấy số dư hiện ra là đã thiết lập xong.
3. Mở trang web có captcha, tiện ích sẽ tự động bắt đầu nhận dạng.
## Chi phí
Tiện ích miễn phí. Khi nhận dạng, điểm được trừ theo loại tác vụ được dùng, ví dụ câu hỏi bằng hình ảnh của reCAPTCHA tính giá theo [reCAPTCHA v2 nhận dạng hình ảnh](https://docs.yescaptcha.com/vi/tasks/recaptcha-classification.md), hCaptcha tính giá theo [hCaptcha nhận dạng hình ảnh](https://docs.yescaptcha.com/vi/tasks/hcaptcha-classification.md). Kết quả nhấp sai có thể báo cáo để được hoàn điểm, xem [Thanh toán và hoàn điểm](https://docs.yescaptcha.com/vi/getting-started/billing.md).
---
# Nhận biết loại captcha
> Cách nhận biết trang web dùng loại captcha nào: reCAPTCHA v2, v2 ẩn, v3, bản Enterprise, hCaptcha, sự khác nhau giữa Cloudflare Turnstile và trang thử thách Cloudflare, cùng loại tác vụ YesCaptcha tương ứng.
Source: https://docs.yescaptcha.com/vi/guides/identify-captcha/ · 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/guides/identify-captcha/
Bước đầu tiên để chọn đúng loại tác vụ là nhận ra captcha. Cách đáng tin cậy nhất là mở công cụ dành cho nhà phát triển của trình duyệt (F12) và xem trong bảng Network trang web tải script của captcha nào; bạn cũng có thể nhận biết qua giao diện.
## Nhận biết qua hình dạng
Hình dạng của từng loại captcha trên trang web (hình minh họa động, không phải ảnh chụp màn hình); nhấn vào thẻ để mở trang loại tác vụ tương ứng. Nếu khó phân biệt bằng mắt, hãy xác nhận bằng bảng tra nhanh và bảng Network bên dưới.
- [reCAPTCHA v2: Ô đánh dấu · Ẩn](https://docs.yescaptcha.com/vi/tasks/recaptcha-v2.md)
- [reCAPTCHA v3](https://docs.yescaptcha.com/vi/tasks/recaptcha-v3.md)
- [Nhận dạng hình ảnh reCAPTCHA v2: Lưới 3×3 · Lưới 4×4 · Một ảnh 1×1](https://docs.yescaptcha.com/vi/tasks/recaptcha-classification.md)
- [hCaptcha](https://docs.yescaptcha.com/vi/tasks/hcaptcha.md)
- [Nhận dạng hình ảnh hCaptcha: Lưới ảnh · Nhấp vào một điểm · Kéo và thả · Hoạt ảnh](https://docs.yescaptcha.com/vi/tasks/hcaptcha-classification.md)
- [Cloudflare Turnstile: Tự động · Ô đánh dấu](https://docs.yescaptcha.com/vi/tasks/turnstile.md)
- [Trang thử thách Cloudflare (5 giây): Tự động · Ô đánh dấu](https://docs.yescaptcha.com/vi/tasks/cloudflare-challenge.md)
- [Nhận dạng hình ảnh FunCaptcha: Mũi tên · Lưới 6 ảnh](https://docs.yescaptcha.com/vi/tasks/funcaptcha-classification.md)
- [Nhận dạng hình ảnh AWS WAF / bCaptcha: AWS WAF · bCaptcha](https://docs.yescaptcha.com/vi/tasks/aws-bcaptcha-classification.md)
- [Nhận dạng chữ và số trong ảnh: Có nhiễu · Đường nhiễu · Phép tính](https://docs.yescaptcha.com/vi/tasks/image-to-text.md)
## Bảng tra nhanh
| Bạn thấy | Đó là | Loại tác vụ cần dùng |
| --- | --- | --- |
| Ô tích “I’m not a robot” (Tôi không phải là người máy) | reCAPTCHA v2 | [reCAPTCHA v2](https://docs.yescaptcha.com/vi/tasks/recaptcha-v2.md) |
| Không có ô tích, bấm gửi mới hiện câu hỏi bằng hình ảnh; có logo nhỏ reCAPTCHA ở góc dưới bên phải | reCAPTCHA v2 ẩn (hoặc v3) | Xem mục “Các phiên bản reCAPTCHA” bên dưới |
| Không có bất kỳ tương tác nào, chỉ có logo nhỏ reCAPTCHA ở góc dưới bên phải | reCAPTCHA v3 | [reCAPTCHA v3](https://docs.yescaptcha.com/vi/tasks/recaptcha-v3.md) |
| Ô tích “Tôi là con người”, câu hỏi hình ảnh có nhãn hCaptcha | hCaptcha | [hCaptcha](https://docs.yescaptcha.com/vi/tasks/hcaptcha.md) |
| Khung xác minh của Cloudflare nằm trong biểu mẫu, tích xong trang không chuyển hướng | Cloudflare Turnstile | [Turnstile](https://docs.yescaptcha.com/vi/tasks/turnstile.md) |
| Cả trang hiện “Vui lòng chờ… / Đang kiểm tra kết nối của bạn”, rồi tự động chuyển hướng | Trang thử thách Cloudflare | [Trang thử thách Cloudflare](https://docs.yescaptcha.com/vi/tasks/cloudflare-challenge.md) |
| Câu đố ghép hình, chọn ảnh của Arkose Labs (ví dụ “chọn hình ảnh hướng đúng chiều lên trên”) | FunCaptcha | [FunCaptcha nhận dạng hình ảnh](https://docs.yescaptcha.com/vi/tasks/funcaptcha-classification.md) |
| Một ảnh chứa chữ cái và chữ số bị méo | Captcha ký tự | [Nhận dạng chữ và số trong ảnh](https://docs.yescaptcha.com/vi/tasks/image-to-text.md) |
## Các phiên bản reCAPTCHA
Tìm `api.js` hoặc `enterprise.js` trong bảng Network:
| Script được tải | Phiên bản |
| --- | --- |
| `recaptcha/api.js`, không có tham số `render` hoặc `render=explicit` | v2 thường |
| Như trên, và địa chỉ của yêu cầu `anchor` có `size=invisible` | v2 ẩn, thêm `"isInvisible": true` vào tác vụ |
| `recaptcha/api.js?render=SITE_KEY` (`render` không phải `explicit`) | v3 thường |
| `recaptcha/enterprise.js`, không có tham số `render` hoặc `render=explicit` | v2 Enterprise |
| `recaptcha/enterprise.js?render=SITE_KEY` | v3 Enterprise |
Ví dụ:
```text
https://www.google.com/recaptcha/api.js?onload=onloadcallback&render=explicit → v2
https://www.google.com/recaptcha/api.js?render=6LdyC2cUAAAAACGuDKpXeDorzUDWXmdqeg-xy696 → v3
https://www.google.com/recaptcha/enterprise.js?render=explicit → v2 Enterprise
```
Đôi khi v2 ẩn chỉ vượt qua được khi dùng loại tác vụ của v3, hãy thử cả hai.
Bạn cũng có thể chạy đoạn mã dưới đây trong Console. Nó liệt kê tất cả reCAPTCHA trên trang cùng phiên bản, khóa trang web, địa chỉ trang và hàm callback:
find-recaptcha-clients.js
```js
// Paste into the browser DevTools console on a page with reCAPTCHA, then run findRecaptchaClients().
// Lists every reCAPTCHA on the page: version (V2/V3), sitekey, page URL and the callback function.
function findRecaptchaClients() {
if (typeof ___grecaptcha_cfg === 'undefined') return [];
return Object.entries(___grecaptcha_cfg.clients).map(([cid, client]) => {
const data = { id: cid, version: cid >= 10000 ? 'V3' : 'V2' };
const objects = Object.entries(client).filter(([, value]) => value && typeof value === 'object');
objects.forEach(([toplevelKey, toplevel]) => {
const found = Object.entries(toplevel).find(
([, value]) => value && typeof value === 'object' && 'sitekey' in value && 'size' in value,
);
if (toplevel instanceof HTMLElement && toplevel.tagName === 'DIV') data.pageurl = toplevel.baseURI;
if (found) {
const [sublevelKey, sublevel] = found;
data.sitekey = sublevel.sitekey;
const callbackKey = data.version === 'V2' ? 'callback' : 'promise-callback';
const callback = sublevel[callbackKey];
if (!callback) {
data.callback = null;
data.function = null;
} else {
data.function = callback;
const keys = [cid, toplevelKey, sublevelKey, callbackKey].map((key) => `['${key}']`).join('');
data.callback = `___grecaptcha_cfg.clients${keys}`;
}
}
});
return data;
});
}
findRecaptchaClients();
```
Kết quả ví dụ:
```json
[
{
"id": "0",
"version": "V2",
"sitekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
"function": "onSuccess",
"callback": "___grecaptcha_cfg.clients['0']['l']['l']['callback']",
"pageurl": "https://www.google.com/recaptcha/api2/demo"
}
]
```
Có thể dùng các trang demo chính thức của Google để đối chiếu: v2 thường `https://www.google.com/recaptcha/api2/demo`, v2 ẩn `https://www.google.com/recaptcha/api2/demo?invisible=true`.
## Turnstile và trang thử thách Cloudflare
Cả hai đều của Cloudflare nhưng không phải cùng một loại:
- **Turnstile** là khung xác minh nhúng trong biểu mẫu của trang web. Sau khi xác minh xong sẽ hiện dấu tích, bản thân trang không chuyển hướng. Trang tải `challenges.cloudflare.com/turnstile/v0/api.js`. Dùng [Turnstile](https://docs.yescaptcha.com/vi/tasks/turnstile.md).
- **Trang thử thách Cloudflare** thay toàn bộ trang bằng trang kiểm tra của Cloudflare, hiện “Vui lòng chờ…”, “xx.com cần kiểm tra bảo mật kết nối của bạn trước khi tiếp tục”, bên trong có thể cũng có một khung xác minh; sau khi vượt qua sẽ tự động chuyển đến trang thật. Mã nguồn có `__cf_chl_rt_tk` hoặc `cdn-cgi/challenge-platform`. Dùng [trang thử thách Cloudflare](https://docs.yescaptcha.com/vi/tasks/cloudflare-challenge.md).
Nếu khi gửi yêu cầu bằng chương trình bạn nhận được 403 cùng “Just a moment…”, nhưng trình duyệt mở trang trực tiếp được, thì nhiều khả năng chỉ là dấu vân tay TLS bị chặn. Hãy dùng thư viện có thể giả lập dấu vân tay TLS của trình duyệt (ví dụ curl\_cffi) là gửi yêu cầu được, không cần vượt trang thử thách.
---
# Tìm tham số reCAPTCHA
> Cách tìm websiteKey (sitekey), websiteURL, pageAction của v3 và hàm callback của reCAPTCHA trong các tab Network, Sources và Console của công cụ dành cho nhà phát triển, kèm script tự động tìm.
Source: https://docs.yescaptcha.com/vi/guides/find-recaptcha-parameters/ · 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/guides/find-recaptcha-parameters/
Để tạo tác vụ reCAPTCHA, bạn cần `websiteURL` (địa chỉ trang hiển thị captcha) và `websiteKey` (khóa của website); v3 cần thêm `pageAction`. Khi mô phỏng thao tác gửi bằng Selenium hoặc công cụ tương tự, bạn còn cần biết hàm callback. Tất cả đều có thể tìm thấy trong công cụ dành cho nhà phát triển của trình duyệt (F12).
## Cách nhanh nhất: script tự động tìm
Mở trang có captcha, nhấn F12 để mở Console, dán và chạy:
find-recaptcha-clients.js
```js
// Paste into the browser DevTools console on a page with reCAPTCHA, then run findRecaptchaClients().
// Lists every reCAPTCHA on the page: version (V2/V3), sitekey, page URL and the callback function.
function findRecaptchaClients() {
if (typeof ___grecaptcha_cfg === 'undefined') return [];
return Object.entries(___grecaptcha_cfg.clients).map(([cid, client]) => {
const data = { id: cid, version: cid >= 10000 ? 'V3' : 'V2' };
const objects = Object.entries(client).filter(([, value]) => value && typeof value === 'object');
objects.forEach(([toplevelKey, toplevel]) => {
const found = Object.entries(toplevel).find(
([, value]) => value && typeof value === 'object' && 'sitekey' in value && 'size' in value,
);
if (toplevel instanceof HTMLElement && toplevel.tagName === 'DIV') data.pageurl = toplevel.baseURI;
if (found) {
const [sublevelKey, sublevel] = found;
data.sitekey = sublevel.sitekey;
const callbackKey = data.version === 'V2' ? 'callback' : 'promise-callback';
const callback = sublevel[callbackKey];
if (!callback) {
data.callback = null;
data.function = null;
} else {
data.function = callback;
const keys = [cid, toplevelKey, sublevelKey, callbackKey].map((key) => `['${key}']`).join('');
data.callback = `___grecaptcha_cfg.clients${keys}`;
}
}
});
return data;
});
}
findRecaptchaClients();
```
Trong kết quả trả về, `sitekey` là `websiteKey`, `pageurl` là `websiteURL`, `version` cho biết là v2 hay v3, còn `function` và `callback` là hàm callback:
```json
[
{
"id": "0",
"version": "V2",
"sitekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
"function": "onSuccess",
"callback": "___grecaptcha_cfg.clients['0']['l']['l']['callback']",
"pageurl": "https://www.google.com/recaptcha/api2/demo"
}
]
```
Mảng rỗng nghĩa là trang chưa tải reCAPTCHA; hãy chạy lại sau khi captcha xuất hiện.
## websiteKey và websiteURL
Trong tab Network, tìm `anchor` và chọn request có dạng như sau:
```text
https://www.google.com/recaptcha/api2/anchor?ar=1&k=6LfW6wATAAAAAHLqO2pb8bDBahxlMxNdo9g947u9&co=...&hl=en&size=normal
```
- Giá trị sau `k=` chính là `websiteKey`.
- `websiteURL` là địa chỉ đầy đủ của trang hiển thị captcha (thường chính là `Referer` của request này).
Bạn cũng có thể tìm `data-sitekey` trong mã nguồn trang.
## pageAction (v3)
`pageAction` là `action` mà trang truyền khi gọi `grecaptcha.execute(khóa website, {action: '...'})`, và phải khớp với trang.
**Cách 1: tìm trong mã nguồn.** Trong tab Sources của công cụ dành cho nhà phát triển, nhấp chuột phải và chọn “Search in all files”. Với v3 thường, tìm `.execute(`; với v3 Enterprise, tìm `.enterprise.execute`, rồi xem `action` phía sau:
```js
grecaptcha.ready(function () {
grecaptcha.execute('6LdpS-gUAAAAAL3Qr2yP7rkrQjkKBVvEY_48JS5l', { action: 'login' }).then(function (token) {
// ...
});
});
```
Ở đây `pageAction` là `login`.
**Cách 2: đặt breakpoint.** Khi mã bị làm rối (obfuscate) và không tìm thấy, hãy chạy `debug(grecaptcha.execute)` trong Console (bản Enterprise dùng `debug(grecaptcha.enterprise.execute)`), rồi thực hiện thao tác trên trang có kích hoạt xác minh (ví dụ nhấp đăng nhập). Khi trình gỡ lỗi dừng lại, xem giá trị của `action` trong Scope ở bên phải.
Một website có thể dùng các `action` khác nhau ở những bước khác nhau (ví dụ khi đăng ký, trước là `signup/submit_email` rồi đến `signup/success`); hãy lấy giá trị của bước bạn cần vượt qua. Nhấn F8 để tiếp tục chạy, bạn sẽ thấy `action` tiếp theo.
## Hàm callback
Khi điền token vào trình duyệt bằng Selenium hoặc công cụ tương tự, sau khi điền xong bạn cần gọi hàm callback của trang để báo cho trang biết đã xác minh xong:
- Tìm `data-callback` trong tab Elements; giá trị của nó là tên hàm callback, ví dụ `data-callback="onSuccess"`.
- Hoặc tìm `grecaptcha.render` và xem `callback` trong các tham số.
- Hoặc xem `___grecaptcha_cfg.clients` trong Console, hoặc dùng script tự động tìm ở trên.
Cách gọi:
```python
driver.execute_script("onSuccess(arguments[0])", g_recaptcha_response)
```
Một số trang không có hàm callback; chỉ cần điền token vào ô văn bản `g-recaptcha-response` rồi gửi biểu mẫu. Xem quy trình đầy đủ tại [Dùng token để hoàn thành reCAPTCHA](https://docs.yescaptcha.com/vi/guides/submit-recaptcha-token.md).
---
# Tìm tham số hCaptcha
> Cách tìm websiteKey (sitekey), websiteURL và rqdata của bản Enterprise: tìm data-sitekey trong mã nguồn trang, hoặc tìm các request checksiteconfig, getcaptcha trong Network.
Source: https://docs.yescaptcha.com/vi/guides/find-hcaptcha-parameters/ · 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/guides/find-hcaptcha-parameters/
Để tạo tác vụ [hCaptcha](https://docs.yescaptcha.com/vi/tasks/hcaptcha.md), bạn cần `websiteURL` (địa chỉ trang web hiển thị captcha) và `websiteKey` (khóa của website, định dạng UUID); với bản Enterprise, đôi khi cần thêm `rqdata`. Bạn có thể tìm tất cả trong công cụ dành cho nhà phát triển của trình duyệt (F12).
## websiteKey
**Cách 1: tìm trong mã nguồn trang.** Trong bảng Elements, nhấn Ctrl+F (Cmd+F trên Mac) và tìm `data-sitekey`:
```html
```
Giá trị của `data-sitekey` chính là `websiteKey`.
**Cách 2: xem request mạng.** Trong bảng Network, tìm `hcaptcha`, mở request `checksiteconfig`; giá trị đứng sau `sitekey=` trong địa chỉ chính là `websiteKey`:
```text
https://api.hcaptcha.com/checksiteconfig?v=...&host=example.com&sitekey=51829642-2cda-4b09-896c-594f89d700cc&sc=1&swa=1
```
## websiteURL
Điền địa chỉ đầy đủ của trang web hiển thị captcha, **không phải** `hcaptcha.com`. `host=` trong request ở trên chính là tên miền của trang web đó.
## rqdata (bản Enterprise)
Một số website dùng hCaptcha bản Enterprise: mỗi lần tải captcha, website cấp một `rqdata`, nếu không gửi kèm thì không thể vượt qua. Giá trị này thường xuất hiện trong phản hồi từ API của chính website (ví dụ `captcha_rqdata` do API đăng nhập trả về), hoặc được truyền vào khi gọi `hcaptcha.render` / `hcaptcha.setData`. Sau khi lấy được, hãy đưa vào trường `rqdata` của tác vụ; `rqdata` thường chỉ dùng được một lần, nên mỗi lần phải lấy giá trị mới.
## userAgent
`userAgent` chỉ được điền giá trị do [/useragent](https://docs.yescaptcha.com/vi/api/useragent.md) trả về; khi gửi token, dùng `userAgent` có trong kết quả nhận dạng.
---
# Tìm tham số Turnstile
> Cách tìm websiteKey (sitekey, bắt đầu bằng 0x) và websiteURL của Cloudflare Turnstile: tìm data-sitekey hoặc turnstile.render trong mã nguồn trang, hoặc xem các request tới challenges.cloudflare.com trong Network.
Source: https://docs.yescaptcha.com/vi/guides/find-turnstile-parameters/ · 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/guides/find-turnstile-parameters/
Tạo tác vụ [Turnstile](https://docs.yescaptcha.com/vi/tasks/turnstile.md) cần `websiteURL` (địa chỉ trang hiển thị khung xác minh) và `websiteKey` (khóa của website, thường bắt đầu bằng `0x`). Trước tiên hãy xác nhận đó là Turnstile chứ không phải trang thử thách Cloudflare, xem [Xác định loại captcha](https://docs.yescaptcha.com/vi/guides/identify-captcha.md).
## websiteKey
**Cách 1: tìm trong mã nguồn trang.** Trong bảng Elements của công cụ dành cho nhà phát triển (F12), tìm `data-sitekey`:
```html
```
**Cách 2: tìm trong script.** Nếu khung xác minh được render bằng JavaScript, nhấp chuột phải trong bảng Sources, chọn “Search in all files”, tìm `turnstile.render` rồi xem `sitekey` trong tham số:
```js
turnstile.render('#container', { sitekey: '0x4AAAAAAAxxxxxxxxxxxxxx', callback: onDone });
```
**Cách 3: xem request mạng.** Trong bảng Network, tìm `challenges.cloudflare.com`; địa chỉ iframe của khung xác minh chứa khóa website bắt đầu bằng `0x`.
## websiteURL
Điền địa chỉ đầy đủ của trang hiển thị khung xác minh, ví dụ `https://example.com/login`.
## action và cData (thường không cần)
Phần lớn trường hợp không cần. Chỉ tìm khi bạn chắc chắn `websiteKey` và `websiteURL` đều đúng mà tác vụ vẫn không qua được: xem trong tham số của `turnstile.render` hoặc trên phần tử khung xác minh có `action`, `cData` hay không (trên phần tử là `data-action`, `data-cdata`):
```js
turnstile.render('#container', { sitekey: '0x4AAAAAAAxxxxxxxxxxxxxx', action: 'login', cData: 'c0bd4b36-7419-4e18-83c6-378699f2a9a2' });
```
Nếu có, khi tạo tác vụ hãy điền `action` vào `pageAction` và `cData` vào `data`, xem [Turnstile](https://docs.yescaptcha.com/vi/tasks/turnstile.md).
## Gửi token
Sau khi nhận dạng xong, điền `token` vào trường ẩn có tên `cf-turnstile-response` trong biểu mẫu (nếu trang dùng `turnstile.render` và đặt `callback`, hãy gọi hàm callback đó với token), rồi gửi biểu mẫu. Request gửi đi dùng `userAgent` trong kết quả nhận dạng làm User-Agent.
---
# Dùng token để vượt reCAPTCHA
> Cách dùng token reCAPTCHA (gRecaptchaResponse) sau khi nhận được: nguyên lý, gửi trực tiếp bằng request HTTP (trường g-recaptcha-response), hoặc điền vào trình duyệt rồi gọi hàm callback, kèm ví dụ Python hoàn chỉnh trên trang demo của Google.
Source: https://docs.yescaptcha.com/vi/guides/submit-recaptcha-token/ · 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/guides/submit-recaptcha-token/
`gRecaptchaResponse` mà YesCaptcha trả về chính là kết quả Google giao cho trang web sau khi người dùng giải xong captcha. Khi đã có nó, bạn cần **gửi nó đến website đích** (không phải gửi cho Google hay YesCaptcha) giống như trình duyệt, website sẽ đối chiếu với Google rồi cho qua. Có hai cách: gửi request trực tiếp, hoặc điền token vào trang trong trình duyệt rồi gửi.
## Nguyên lý
Luồng khi truy cập bình thường:
1. Trang web tải reCAPTCHA, người dùng hoàn thành xác minh;
2. Google đưa cho trang một token, trang đặt token vào ô văn bản `g-recaptcha-response` (hoặc truyền cho hàm callback);
3. Người dùng gửi biểu mẫu, token được gửi kèm đến máy chủ của website;
4. Máy chủ của website dùng token để đối chiếu với Google, hợp lệ thì cho qua.
Khi dùng YesCaptcha, bước 1 và 2 do chúng tôi thực hiện: bạn tạo tác vụ với `websiteURL` và `websiteKey`, nhận token, rồi tiếp tục từ bước 3.
> **Chú ý:** Token chỉ dùng được một lần và có hiệu lực khoảng 120 giây; nên gửi trong vòng 60 giây sau khi nhận. Website sẽ không chấp nhận token đã hết hạn.
## Cách 1: Gửi request trực tiếp (khuyến nghị)
1. Thao tác thủ công một lần trong trình duyệt: nhấn F12 mở bảng Network, giải captcha và gửi biểu mẫu, rồi tìm request gửi biểu mẫu đó.
2. Trong Payload (hoặc Form Data) của request, tìm trường mang token, thường tên là `g-recaptcha-response`, token bắt đầu bằng `03A`; một số website đổi tên, ví dụ `grecaptcharesponse`, `captcha`.
3. Trong chương trình của bạn, gửi một request giống hệt, thay giá trị của trường đó bằng token YesCaptcha trả về. Các trường khác, Cookie và header cũng phải khớp với trình duyệt, vì website thường kiểm tra cả những thứ này.
Ví dụ hoàn chỉnh trên trang demo của Google: nhận token trước, rồi gửi lại cho trang demo qua trường `g-recaptcha-response`:
recaptcha_requests.py
```python
"""Solve reCAPTCHA v2 on Google's demo page and submit the token with plain HTTP (no browser).
Run: pip install requests
export YESCAPTCHA_CLIENT_KEY=your_client_key
python recaptcha_requests.py
Each run creates one NoCaptchaTaskProxyless task (charged per the price list).
"""
import os
import time
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
API = "https://api.yescaptcha.com"
WEBSITE_URL = "https://www.google.com/recaptcha/api2/demo"
WEBSITE_KEY = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
def call(method, payload):
data = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30).json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data
def get_token():
task = {"type": "NoCaptchaTaskProxyless", "websiteURL": WEBSITE_URL, "websiteKey": WEBSITE_KEY}
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"]["gRecaptchaResponse"]
raise TimeoutError(task_id)
token = get_token()
print("token:", token[:40], "...")
# Submit the token the same way the browser does: the demo form posts the field
# "g-recaptcha-response" back to the page. Check your own site's request in DevTools > Network.
page = requests.post(WEBSITE_URL, data={"g-recaptcha-response": token}, timeout=30)
print("passed" if "Verification Success" in page.text else "not passed", page.status_code)
```
## Cách 2: Điền vào trình duyệt (Selenium, v.v.)
Khi dùng Selenium, Playwright hoặc công cụ tương tự để điều khiển trình duyệt thật:
1. Đọc `data-sitekey` từ trang, dùng nó để tạo tác vụ và nhận token.
2. Ghi token vào ô văn bản `g-recaptcha-response` trong trang.
3. Nếu trang có đặt hàm callback (`data-callback="..."`), hãy gọi hàm đó và truyền token vào; một số website chỉ cho nhấn nút gửi sau khi callback được gọi.
4. Gửi biểu mẫu.
```js
// Step 2: write the token (run in the page)
document.getElementById('g-recaptcha-response').value = 'TOKEN';
// Step 3: call the callback if there is one, e.g. data-callback="onSuccess"
onSuccess('TOKEN');
```
Khi trang có nhiều reCAPTCHA, id của ô văn bản có thể là `g-recaptcha-response-1` và tương tự; nếu không tìm thấy ô này, hãy tự giải captcha thủ công một lần, tìm `03A` trong Elements để xem kết quả được đặt ở đâu. Cách tìm hàm callback xem [Tìm tham số reCAPTCHA](https://docs.yescaptcha.com/vi/guides/find-recaptcha-parameters.md).
Ví dụ hoàn chỉnh (Selenium 4):
recaptcha_selenium.py
```python
"""Solve reCAPTCHA v2 on Google's demo page in a real browser with Selenium 4:
get a token from YesCaptcha, put it into the page, then submit the form.
Run: pip install requests selenium
export YESCAPTCHA_CLIENT_KEY=your_client_key
python recaptcha_selenium.py
Each run creates one NoCaptchaTaskProxyless task (charged per the price list).
"""
import os
import time
import requests
from selenium import webdriver
from selenium.webdriver.common.by import By
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
API = "https://api.yescaptcha.com"
WEBSITE_URL = "https://www.google.com/recaptcha/api2/demo"
def call(method, payload):
data = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30).json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data
def get_token(website_url, website_key):
task = {"type": "NoCaptchaTaskProxyless", "websiteURL": website_url, "websiteKey": website_key}
task_id = call("createTask", {"task": task})["taskId"]
for _ in range(36):
time.sleep(5)
result = call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]["gRecaptchaResponse"]
raise TimeoutError(task_id)
driver = webdriver.Chrome() # Selenium 4 downloads a matching chromedriver automatically
try:
driver.get(WEBSITE_URL)
site_key = driver.find_element(By.CSS_SELECTOR, "[data-sitekey]").get_attribute("data-sitekey")
token = get_token(WEBSITE_URL, site_key)
# Put the token where reCAPTCHA keeps it ...
driver.execute_script(
"document.getElementById('g-recaptcha-response').value = arguments[0];", token
)
# ... and, if the page uses a callback (data-callback="..."), call it:
callback = driver.find_element(By.CSS_SELECTOR, "[data-sitekey]").get_attribute("data-callback")
if callback:
driver.execute_script(f"window[{callback!r}](arguments[0]);", token)
driver.find_element(By.ID, "recaptcha-demo-submit").click()
time.sleep(2)
print("passed" if "Verification Success" in driver.page_source else "not passed")
finally:
driver.quit()
```
## reCAPTCHA v3
v3 không có ô đánh dấu. Khi cần token, trang web gọi `grecaptcha.execute(khóa website, {action: '...'})`, rồi đặt token vào request của chính nó (tên trường do website quyết định, thường gặp là `g-recaptcha-response`, `token`, `recaptchaToken`). Cách làm giống Cách 1: tìm request mang token trong Network rồi gửi lại tương tự; khi tạo tác vụ, `pageAction` phải khớp với `action` của trang.
## Đã gửi mà vẫn không qua
- Token hết hạn: gửi càng sớm càng tốt sau khi nhận, không quá 60 giây.
- Gửi sai trường mà website kiểm tra, hoặc thiếu các trường khác, Cookie: đối chiếu từng mục với request trong trình duyệt.
- Website đồng thời kiểm tra IP, User-Agent, v.v.: dùng loại tác vụ tự cung cấp proxy (như `NoCaptchaTask`) và gửi qua cùng proxy đó.
- Điểm v3 không đủ: kiểm tra lại `pageAction`, hoặc chuyển sang loại có điểm cao cố định, xem [reCAPTCHA v3](https://docs.yescaptcha.com/vi/tasks/recaptcha-v3.md).
- Hệ thống kiểm soát rủi ro của website còn xem các tín hiệu hành vi khác. Nếu tỷ lệ qua bằng token thấp, có thể chuyển sang [nhận dạng hình ảnh](https://docs.yescaptcha.com/vi/tasks/recaptcha-classification.md) để nhấp chuột thật trong trình duyệt, hoặc dùng [tiện ích trình duyệt](https://docs.yescaptcha.com/vi/extension.md).
---
# Mô phỏng click nhận dạng hình ảnh reCAPTCHA v2 (Selenium)
> Dùng Python Selenium 4 và ReCaptchaV2Classification để tự động click các ô ảnh của reCAPTCHA v2 trong trình duyệt: kích hoạt captcha, đọc câu hỏi và hình ảnh, gọi API nhận dạng, click các ô, gửi biểu mẫu; kèm mã ví dụ đầy đủ.
Source: https://docs.yescaptcha.com/vi/guides/recaptcha-click-selenium/ · 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/guides/recaptcha-click-selenium/
Bài hướng dẫn này dùng Selenium 4 mở trang demo reCAPTCHA của Google và hoàn thành bài kiểm tra hình ảnh trong trình duyệt thật: đọc câu hỏi và hình ảnh, giao cho [nhận dạng hình ảnh reCAPTCHA v2](https://docs.yescaptcha.com/vi/tasks/recaptcha-classification.md) (`ReCaptchaV2Classification`) xác định cần click những ô nào, rồi mô phỏng click. So với cách lấy token, cách này hoàn thành xác minh ngay trong trình duyệt, phù hợp với các website có tỷ lệ token được chấp nhận thấp.
Nếu không muốn viết mã, bạn có thể dùng trực tiếp [tiện ích trình duyệt](https://docs.yescaptcha.com/vi/extension.md), vì nó tự động click dựa trên cùng một API.
## Chuẩn bị
```bash
pip install requests selenium pillow
export YESCAPTCHA_CLIENT_KEY=your_client_key
```
Cần cài Chrome. Selenium 4 sẽ tự động tải chromedriver phù hợp.
## Quy trình
1. **Click ô checkbox.** Checkbox nằm trong iframe có `title="reCAPTCHA"`; hãy chuyển vào iframe đó rồi click `#recaptcha-anchor`.
2. **Chuyển sang iframe của câu hỏi.** Câu hỏi nằm trong một iframe khác (title chứa “challenge”).
3. **Đọc câu hỏi.** Phần chữ in đậm trong `.rc-imageselect-desc-wrapper strong` chính là đối tượng cần tìm, ví dụ “traffic lights”. API cần ID câu hỏi, vì vậy hãy dùng bảng đối chiếu để đổi tên thành ID (`/m/015qff`), xem [ID câu hỏi](https://docs.yescaptcha.com/vi/tasks/recaptcha-classification.md). Giao diện trình duyệt bằng tiếng Anh là thuận tiện nhất để đối chiếu.
4. **Lấy hình ảnh.** Các ô thực chất là các phần của cùng một ảnh lớn; hãy tải `src` của `td.rc-imageselect-tile img`. Với 9 ô (3x3), thu phóng về 300×300; với 16 ô (4x4), thu phóng về 450×450, rồi chuyển sang Base64.
5. **Nhận dạng.** Gọi `createTask` với loại `ReCaptchaV2Classification`, truyền `image` và `question`. Thêm `"confidence": 0.5` thì ảnh 3x3 sẽ trả về một lần tất cả các ô phù hợp, không cần xử lý các ảnh nhỏ xuất hiện sau khi click.
6. **Click.** `objects` trả về là số thứ tự các ô, bắt đầu từ 0, từ trái sang phải, từ trên xuống dưới; hãy lần lượt click các `td` tương ứng.
7. **Xác minh.** Click `#recaptcha-verify-button`. Nếu xuất hiện vòng câu hỏi mới, quay lại bước 3; khi cửa sổ câu hỏi đóng lại nghĩa là đã vượt qua.
8. **Gửi biểu mẫu.** Quay lại trang chính và click nút gửi.
## Mã đầy đủ
recaptcha_click_selenium.py
```python
"""Click through a reCAPTCHA v2 image challenge with Selenium 4 and ReCaptchaV2Classification.
Flow: open the page -> click the checkbox -> read the target name and the grid image ->
ask YesCaptcha which tiles to click -> click them -> press Verify. Repeat if a new challenge appears.
Run: pip install requests selenium pillow
export YESCAPTCHA_CLIENT_KEY=your_client_key
python recaptcha_click_selenium.py
Each recognized image is charged (see the price list). reCAPTCHA's page structure can change;
adjust the selectors below if a step stops working.
"""
import base64
import io
import os
import time
import requests
from PIL import Image
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.wait import WebDriverWait
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
PAGE_URL = "https://www.google.com/recaptcha/api2/demo"
# Target names shown in the challenge (English UI) -> question IDs.
# Full list: https://docs.yescaptcha.com/en/tasks/recaptcha-classification/
QUESTION_IDS = {
"taxis": "/m/0pg52", "bus": "/m/01bjv", "buses": "/m/01bjv", "motorcycles": "/m/04_sv",
"tractors": "/m/013xlm", "chimneys": "/m/01jk_4", "crosswalks": "/m/014xcs",
"traffic lights": "/m/015qff", "bicycles": "/m/0199g", "parking meters": "/m/015qbp",
"cars": "/m/0k4j", "bridges": "/m/015kr", "boats": "/m/019jd", "palm trees": "/m/0cdl1",
"mountains or hills": "/m/09d_r", "fire hydrants": "/m/01pns0", "a fire hydrant": "/m/01pns0",
"stairs": "/m/01lynh",
}
def classify(image_b64, question):
task = {"type": "ReCaptchaV2Classification", "image": image_b64, "question": question, "confidence": 0.5}
data = requests.post(
"https://api.yescaptcha.com/createTask",
json={"clientKey": CLIENT_KEY, "task": task},
timeout=30,
).json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data["solution"] # synchronous: the solution comes back right away
def grid_image_b64(url, size):
"""Download the challenge image and scale it to the standard size (300 for 3x3, 450 for 4x4)."""
img = Image.open(io.BytesIO(requests.get(url, timeout=30).content)).convert("RGB")
img = img.resize((size, size))
buf = io.BytesIO()
img.save(buf, format="JPEG")
return base64.b64encode(buf.getvalue()).decode()
driver = webdriver.Chrome()
wait = WebDriverWait(driver, 15)
try:
driver.get(PAGE_URL)
# 1. Click the checkbox (inside the "reCAPTCHA" iframe)
wait.until(EC.frame_to_be_available_and_switch_to_it((By.CSS_SELECTOR, 'iframe[title="reCAPTCHA"]')))
wait.until(EC.element_to_be_clickable((By.ID, "recaptcha-anchor"))).click()
driver.switch_to.default_content()
# 2. Switch to the challenge iframe and solve rounds until it closes
wait.until(EC.frame_to_be_available_and_switch_to_it(
(By.XPATH, '//iframe[contains(@title, "challenge")]')))
for _ in range(5):
target = wait.until(EC.presence_of_element_located(
(By.CSS_SELECTOR, ".rc-imageselect-desc-wrapper strong"))).text.strip().lower()
question = QUESTION_IDS.get(target)
if not question:
print("unsupported target, reloading:", target)
driver.find_element(By.ID, "recaptcha-reload-button").click()
time.sleep(2)
continue
tiles = driver.find_elements(By.CSS_SELECTOR, "td.rc-imageselect-tile")
size = 450 if len(tiles) == 16 else 300
url = driver.find_element(By.CSS_SELECTOR, "td.rc-imageselect-tile img").get_attribute("src")
solution = classify(grid_image_b64(url, size), question)
for index in solution.get("objects", []):
tiles[index].click()
time.sleep(0.3)
time.sleep(1)
driver.find_element(By.ID, "recaptcha-verify-button").click()
time.sleep(3)
driver.switch_to.default_content()
frame = driver.find_element(By.XPATH, '//iframe[contains(@title, "challenge")]')
if not frame.is_displayed(): # challenge closed: passed
break
driver.switch_to.frame(frame)
driver.switch_to.default_content()
driver.find_element(By.ID, "recaptcha-demo-submit").click()
time.sleep(2)
print("passed" if "Verification Success" in driver.page_source else "not passed")
finally:
driver.quit()
```
## Lưu ý
- Cấu trúc trang của reCAPTCHA thay đổi theo thời gian; khi các selector trong mã không còn hiệu lực, hãy điều chỉnh theo trang thực tế.
- Mỗi lần nhận dạng một ảnh đều bị trừ điểm (giá xem tại [nhận dạng hình ảnh reCAPTCHA v2](https://docs.yescaptcha.com/vi/tasks/recaptcha-classification.md)). Các tác vụ xác minh thất bại sau khi click có thể được [báo cáo](https://docs.yescaptcha.com/vi/api/report.md) trong vòng 1 giờ để yêu cầu hoàn điểm.
- Nếu gặp câu hỏi không có trong bảng đối chiếu, bạn có thể nhấn nút làm mới để đổi câu khác, hoặc liên hệ bộ phận hỗ trợ để bổ sung.
---
# Mô phỏng click hình ảnh hCaptcha bằng Selenium
> Dùng Python, Selenium 4 và HCaptchaClassification để tự động hoàn thành câu đố hình ảnh lưới 3×3 của hCaptcha trong trình duyệt thật: nhấp vào hộp kiểm, đọc câu hỏi và 9 hình ảnh, gọi API nhận dạng, click và gửi; kèm mã ví dụ đầy đủ.
Source: https://docs.yescaptcha.com/vi/guides/hcaptcha-click-selenium/ · 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/guides/hcaptcha-click-selenium/
Hướng dẫn này dùng Selenium 4 mở trang demo của hCaptcha và hoàn thành câu đố hình ảnh lưới 3×3 trong trình duyệt thật: đọc câu hỏi và 9 hình ảnh, gửi cho [nhận dạng hình ảnh hCaptcha](https://docs.yescaptcha.com/vi/tasks/hcaptcha-classification.md) (`HCaptchaClassification`) để xác định ô nào là mục tiêu, rồi mô phỏng click.
hCaptcha còn có các dạng câu đố như “click vào vị trí chỉ định” và “kéo thả”. Chúng trả về tọa độ thay vì ô lưới; cách xử lý xem tại [nhận dạng hình ảnh hCaptcha](https://docs.yescaptcha.com/vi/tasks/hcaptcha-classification.md). Nếu không muốn viết mã, bạn có thể dùng thẳng [tiện ích trình duyệt](https://docs.yescaptcha.com/vi/extension.md); tiện ích hỗ trợ tất cả các dạng này.
## Chuẩn bị
```bash
pip install requests selenium
export YESCAPTCHA_CLIENT_KEY=your_client_key
```
## Quy trình
1. **Nhấp vào hộp kiểm.** Hộp kiểm nằm trong iframe hCaptcha có địa chỉ chứa `frame=checkbox`; chuyển vào iframe đó rồi nhấp `#checkbox`.
2. **Chuyển sang iframe của câu hỏi.** Câu hỏi nằm trong iframe có địa chỉ chứa `frame=challenge`.
3. **Đọc câu hỏi.** Văn bản trong `.prompt-text` chính là câu hỏi, truyền nguyên văn cho API (nên chuyển ngôn ngữ giao diện của hCaptcha sang tiếng Trung giản thể hoặc tiếng Anh). Nếu cạnh câu hỏi có ảnh mẫu nhỏ, hãy đưa ảnh đó vào `anchors`.
4. **Lấy hình ảnh.** Ảnh nền của `.task-image .image` ở mỗi ô là một hình nhỏ; tải lần lượt theo thứ tự, chuyển sang Base64 và tạo danh sách `queries`.
5. **Nhận dạng.** Gọi `createTask` với loại `HCaptchaClassification`. `objects` trả về tương ứng một-một với các ô, giá trị `true` là mục tiêu.
6. **Click và gửi.** Click các ô là mục tiêu rồi nhấn nút gửi. Có thể xuất hiện nhiều vòng liên tiếp, lặp lại các bước 3 đến 6.
7. **Hoàn tất.** Sau khi vượt qua, trường `h-captcha-response` trên trang sẽ chứa token, gửi kèm cùng biểu mẫu.
## Mã đầy đủ
hcaptcha_click_selenium.py
```python
"""Click through an hCaptcha 3x3 image challenge with Selenium 4 and HCaptchaClassification.
Flow: open the page -> click the checkbox -> read the question and the 9 images ->
ask YesCaptcha which images match -> click them -> submit. Repeat while new rounds appear.
Run: pip install requests selenium
export YESCAPTCHA_CLIENT_KEY=your_client_key
python hcaptcha_click_selenium.py
Each recognized round is charged (see the price list; rounds with no target found are free).
hCaptcha changes its page structure often; adjust the selectors below if a step stops working.
Click and drag questions return coordinates instead; see the HCaptchaClassification page.
"""
import base64
import os
import re
import time
import requests
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.wait import WebDriverWait
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
PAGE_URL = "https://accounts.hcaptcha.com/demo"
def classify(question, images_b64):
task = {"type": "HCaptchaClassification", "question": question, "queries": images_b64}
data = requests.post(
"https://api.yescaptcha.com/createTask",
json={"clientKey": CLIENT_KEY, "task": task},
timeout=60,
).json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data["solution"] # synchronous
def background_image_b64(element):
"""The tiles are s with a CSS background image; download it and Base64-encode it."""
style = element.get_attribute("style") or ""
match = re.search(r'url\("?(.*?)"?\)', style)
if not match:
return None
return base64.b64encode(requests.get(match.group(1), timeout=30).content).decode()
driver = webdriver.Chrome()
wait = WebDriverWait(driver, 15)
try:
driver.get(PAGE_URL)
# 1. Click the checkbox (inside the first hCaptcha iframe)
wait.until(EC.frame_to_be_available_and_switch_to_it(
(By.CSS_SELECTOR, 'iframe[src*="hcaptcha"][src*="frame=checkbox"]')))
wait.until(EC.element_to_be_clickable((By.ID, "checkbox"))).click()
driver.switch_to.default_content()
# 2. Solve rounds in the challenge iframe
wait.until(EC.frame_to_be_available_and_switch_to_it(
(By.CSS_SELECTOR, 'iframe[src*="hcaptcha"][src*="frame=challenge"]')))
for _ in range(5):
question = wait.until(EC.presence_of_element_located((By.CSS_SELECTOR, ".prompt-text"))).text.strip()
tiles = driver.find_elements(By.CSS_SELECTOR, ".task-image")
images = [background_image_b64(t.find_element(By.CSS_SELECTOR, ".image")) for t in tiles]
if not tiles or None in images:
print("not a 3x3 image challenge; see the docs for click/drag questions")
break
solution = classify(question, images)
for tile, hit in zip(tiles, solution.get("objects", [])):
if hit:
tile.click()
time.sleep(0.3)
driver.find_element(By.CSS_SELECTOR, ".button-submit").click()
time.sleep(3)
if not driver.find_elements(By.CSS_SELECTOR, ".task-image"):
break
driver.switch_to.default_content()
token = driver.find_element(By.NAME, "h-captcha-response").get_attribute("value")
print("token received" if token else "not passed")
finally:
driver.quit()
```
## Lưu ý
- Cấu trúc trang của hCaptcha thường xuyên thay đổi; khi bộ chọn trong mã không còn hiệu lực, hãy điều chỉnh theo trang thực tế.
- Mỗi vòng nhận dạng đều bị trừ điểm; vòng không nhận dạng ra mục tiêu thì không trừ điểm. Nếu xác minh thất bại sau khi click, bạn có thể [báo cáo](https://docs.yescaptcha.com/vi/api/report.md) trong vòng 1 giờ để yêu cầu hoàn điểm.
- Khi gặp câu hỏi mới và nhận `ERROR_UNKNOWN_QUESTION`, hãy làm mới để đổi câu hỏi khác, hoặc liên hệ bộ phận hỗ trợ.
---
# Mã mẫu và SDK
> Mã mẫu có thể chạy ngay của YesCaptcha (Python, Node.js, curl, C#, Easy Language) và các SDK không chính thức do cộng đồng đóng góp (Python, Node.js, Go).
Source: https://docs.yescaptcha.com/vi/samples/ · 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/samples/
Các ví dụ ở đây là những tệp hoàn chỉnh, có thể chạy trực tiếp, đọc clientKey từ biến môi trường `YESCAPTCHA_CLIENT_KEY`. Trang của từng loại tác vụ cũng có ví dụ curl, Python và Node.js được tạo riêng cho loại đó.
[Python](https://docs.yescaptcha.com/vi/samples/python.md)Truy vấn số dư, yêu cầu đầu tiên, client có thể tái sử dụng, kiểm soát đồng thời, Selenium
[Node.js](https://docs.yescaptcha.com/vi/samples/nodejs.md)Node.js 18+, không cần thư viện bên thứ ba
[C#](https://docs.yescaptcha.com/vi/samples/csharp.md).NET 6+
[Easy Language](https://docs.yescaptcha.com/vi/samples/easy-language.md)Ví dụ mô phỏng thao tác click do người dùng đóng góp
Nếu chỉ muốn thử bằng dòng lệnh, xem ví dụ curl trong [Bắt đầu nhanh](https://docs.yescaptcha.com/vi/getting-started/quickstart.md) và [getBalance](https://docs.yescaptcha.com/vi/api/get-balance.md).
## SDK cộng đồng
Các SDK dưới đây do người dùng đóng góp và **không phải chính thức**. Chúng tôi chưa kiểm duyệt mã nguồn, vui lòng tự đánh giá trước khi dùng; nếu có vấn đề, hãy liên hệ tác giả:
| Ngôn ngữ | Dự án |
| --- | --- |
| Python | [github.com/yescaptcha/yescaptcha-python](https://github.com/yescaptcha/yescaptcha-python) |
| Node.js | [github.com/ScoLib/yescaptcha](https://github.com/ScoLib/yescaptcha) |
| Go | [github.com/FreedWu/yescaptcha](https://github.com/FreedWu/yescaptcha) |
| Go | [github.com/deanxv/yescaptcha-go](https://github.com/deanxv/yescaptcha-go) |
Với bất kỳ SDK nào, hãy kiểm tra xem nó dùng địa chỉ API `api.yescaptcha.com` hoặc `cn.yescaptcha.com`, và tên loại tác vụ khớp với tài liệu này.
---
# Python
> Ví dụ Python cho YesCaptcha: truy vấn số dư, nhận dạng captcha hình ảnh, lớp client dùng lại được (tạo tác vụ, polling mỗi 5 giây), kiểm soát đồng thời bằng asyncio, và gửi reCAPTCHA bằng requests và Selenium.
Source: https://docs.yescaptcha.com/vi/samples/python/ · 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/samples/python/
Môi trường chạy: Python 3.8 trở lên, `pip install requests`. Đặt biến môi trường trước khi chạy:
```bash
export YESCAPTCHA_CLIENT_KEY=your_client_key
```
## Truy vấn số dư
Không trừ điểm, dùng để xác nhận `clientKey` đúng:
get_balance.py
```python
"""Check the balance. getBalance is free and is a quick way to verify your clientKey."""
import os
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
r = requests.post(
"https://api.yescaptcha.com/getBalance",
json={"clientKey": CLIENT_KEY},
timeout=30,
)
data = r.json()
if data.get("errorId"):
# e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
print("error:", data.get("errorCode"), data.get("errorDescription"))
else:
print("balance (points):", data["balance"])
```
## Nhận dạng một captcha hình ảnh
Loại đồng bộ `ImageToTextTaskOcrBase`, chỉ cần một request là có kết quả. Ảnh mẫu: [captcha.jpg](https://docs.yescaptcha.com/samples/captcha.jpg).
quickstart.py
```python
"""First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase
(synchronous, 2 points per image).
Usage:
export YESCAPTCHA_CLIENT_KEY=your_client_key
python quickstart.py captcha.png
"""
import base64
import os
import sys
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
image_path = sys.argv[1] if len(sys.argv) > 1 else "captcha.png"
with open(image_path, "rb") as f:
body = base64.b64encode(f.read()).decode() # no "data:" prefix
r = requests.post(
"https://api.yescaptcha.com/createTask",
json={
"clientKey": CLIENT_KEY,
"task": {"type": "ImageToTextTaskOcrBase", "body": body},
},
timeout=30,
)
data = r.json()
if data.get("errorId"):
raise SystemExit(f"{data.get('errorCode')}: {data.get('errorDescription')}")
print("text:", data["solution"]["text"])
```
## Client dùng lại được
Sao chép tệp dưới đây vào dự án của bạn, dùng được cho cả loại đồng bộ và bất đồng bộ:
yescaptcha.py
```python
"""A small client you can copy into your project: create tasks, poll results, check the balance.
from yescaptcha import YesCaptcha
client = YesCaptcha(os.environ["YESCAPTCHA_CLIENT_KEY"])
solution = client.solve({
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})
print(solution["gRecaptchaResponse"])
"""
import os
import time
import requests
class YesCaptchaError(Exception):
def __init__(self, code, description):
super().__init__(f"{code}: {description}")
self.code = code
self.description = description
class YesCaptcha:
def __init__(self, client_key, endpoint="https://api.yescaptcha.com", poll_interval=5, timeout=180):
self.client_key = client_key
self.endpoint = endpoint.rstrip("/")
self.poll_interval = poll_interval # 5 s: polling the same taskId more often only returns "processing"
self.timeout = timeout
self.session = requests.Session()
def call(self, method, payload=None):
body = {"clientKey": self.client_key, **(payload or {})}
data = self.session.post(f"{self.endpoint}/{method}", json=body, timeout=30).json()
if data.get("errorId"):
raise YesCaptchaError(data.get("errorCode"), data.get("errorDescription"))
return data
def balance(self):
return self.call("getBalance")["balance"]
def solve(self, task):
created = self.call("createTask", {"task": task})
if created.get("status") == "ready": # synchronous types return the solution directly
return created["solution"]
task_id = created["taskId"]
deadline = time.time() + self.timeout
while time.time() < deadline:
time.sleep(self.poll_interval)
result = self.call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]
raise TimeoutError(f"task {task_id} not ready after {self.timeout}s")
if __name__ == "__main__":
client = YesCaptcha(os.environ["YESCAPTCHA_CLIENT_KEY"])
print("balance:", client.balance())
```
```python
from yescaptcha import YesCaptcha
client = YesCaptcha(os.environ["YESCAPTCHA_CLIENT_KEY"])
solution = client.solve({
"type": "HCaptchaTaskProxyless",
"websiteURL": "https://accounts.hcaptcha.com/demo",
"websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
})
print(solution["gRecaptchaResponse"])
```
Khi có lỗi, client ném `YesCaptchaError`; `e.code` là mã lỗi, ý nghĩa xem tại [Mã lỗi](https://docs.yescaptcha.com/vi/api/errors.md).
## Kiểm soát đồng thời
Khi gửi tác vụ hàng loạt, hãy giới hạn số request đang xử lý cùng lúc; nhận `ERROR_THREADS_MAXIMUM` thì chờ một lúc rồi thử lại (cần `pip install aiohttp`). Xem thêm tại [Giới hạn đồng thời và tự động tạm dừng](https://docs.yescaptcha.com/vi/api/rate-limits.md):
concurrency.py
```python
"""Limit concurrency: keep the number of requests waiting for a result below your limit, and back off
on ERROR_THREADS_MAXIMUM (rejected requests are not charged). Requires: pip install aiohttp"""
import asyncio
import os
import aiohttp
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
LIMIT = 15 # below your concurrency limit
sem = asyncio.Semaphore(LIMIT)
async def solve(session, task):
async with sem: # at most LIMIT requests in progress at a time
result = {}
for attempt in range(5):
async with session.post(
"https://api.yescaptcha.com/createTask",
json={"clientKey": CLIENT_KEY, "task": task},
) as resp:
result = await resp.json()
if result.get("errorCode") != "ERROR_THREADS_MAXIMUM":
return result
await asyncio.sleep(1 + attempt) # over the limit: wait and retry
return result
async def main(tasks):
async with aiohttp.ClientSession() as session:
return await asyncio.gather(*(solve(session, t) for t in tasks))
if __name__ == "__main__":
print(asyncio.run(main([])))
```
## Gửi token reCAPTCHA
- Gửi trực tiếp bằng requests: xem [Hoàn thành reCAPTCHA bằng token](https://docs.yescaptcha.com/vi/guides/submit-recaptcha-token.md)
- Điền vào trình duyệt bằng Selenium: xem [Hoàn thành reCAPTCHA bằng token](https://docs.yescaptcha.com/vi/guides/submit-recaptcha-token.md)
- Mô phỏng click câu hỏi hình ảnh bằng Selenium: xem [Mô phỏng click nhận dạng hình ảnh reCAPTCHA v2](https://docs.yescaptcha.com/vi/guides/recaptcha-click-selenium.md), [Mô phỏng click nhận dạng hình ảnh hCaptcha](https://docs.yescaptcha.com/vi/guides/hcaptcha-click-selenium.md)
---
# Node.js
> Ví dụ Node.js cho YesCaptcha (Node.js 18+, dùng `fetch` có sẵn, không cần thư viện bên thứ ba): truy vấn số dư, nhận dạng captcha hình ảnh và một lớp client có thể tái sử dụng (tạo tác vụ, polling mỗi 5 giây).
Source: https://docs.yescaptcha.com/vi/samples/nodejs/ · 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/samples/nodejs/
Môi trường chạy: Node.js 18 trở lên (có sẵn `fetch`). Các ví dụ là ES module (`.mjs`), không cần cài thư viện bên thứ ba. Trước khi chạy, hãy đặt biến môi trường:
```bash
export YESCAPTCHA_CLIENT_KEY=your_client_key
```
## Truy vấn số dư
Không trừ điểm, dùng để xác nhận `clientKey` đúng:
get-balance.mjs
```js
// Check the balance. getBalance is free and is a quick way to verify your clientKey. Node.js 18+
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;
const res = await fetch('https://api.yescaptcha.com/getBalance', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY }),
});
const data = await res.json();
if (data.errorId) {
// e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
console.log('error:', data.errorCode, data.errorDescription);
} else {
console.log('balance (points):', data.balance);
}
```
## Nhận dạng một captcha hình ảnh
Loại đồng bộ `ImageToTextTaskOcrBase`, chỉ cần một yêu cầu là có kết quả. Ảnh mẫu: [captcha.jpg](https://docs.yescaptcha.com/samples/captcha.jpg). Chạy `node quickstart.mjs captcha.jpg`.
quickstart.mjs
```js
// First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase (synchronous, 2 points per image).
// Usage: YESCAPTCHA_CLIENT_KEY=your_client_key node quickstart.mjs captcha.png
import { readFileSync } from 'node:fs';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;
const body = readFileSync(process.argv[2] ?? 'captcha.png').toString('base64'); // no "data:" prefix
const res = await fetch('https://api.yescaptcha.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY, task: { type: 'ImageToTextTaskOcrBase', body } }),
});
const data = await res.json();
if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
console.log('text:', data.solution.text);
```
## Client có thể tái sử dụng
yescaptcha.mjs
```js
// A small client you can copy into your project: create tasks, poll results, check the balance. Node.js 18+
//
// import { YesCaptcha } from './yescaptcha.mjs';
// const client = new YesCaptcha(process.env.YESCAPTCHA_CLIENT_KEY);
// const solution = await client.solve({ type: 'NoCaptchaTaskProxyless', websiteURL: '...', websiteKey: '...' });
export class YesCaptchaError extends Error {
constructor(code, description) {
super(`${code}: ${description}`);
this.code = code;
}
}
export class YesCaptcha {
constructor(clientKey, { endpoint = 'https://api.yescaptcha.com', pollInterval = 5000, timeout = 180000 } = {}) {
this.clientKey = clientKey;
this.endpoint = endpoint.replace(/\/$/, '');
this.pollInterval = pollInterval; // 5 s: polling the same taskId more often only returns "processing"
this.timeout = timeout;
}
async call(method, payload = {}) {
const res = await fetch(`${this.endpoint}/${method}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: this.clientKey, ...payload }),
});
const data = await res.json();
if (data.errorId) throw new YesCaptchaError(data.errorCode, data.errorDescription);
return data;
}
async balance() {
return (await this.call('getBalance')).balance;
}
async solve(task) {
const created = await this.call('createTask', { task });
if (created.status === 'ready') return created.solution; // synchronous types return the solution directly
const deadline = Date.now() + this.timeout;
while (Date.now() < deadline) {
await new Promise((r) => setTimeout(r, this.pollInterval));
const result = await this.call('getTaskResult', { taskId: created.taskId });
if (result.status === 'ready') return result.solution;
}
throw new Error(`task ${created.taskId} not ready after ${this.timeout} ms`);
}
}
if (import.meta.url === `file://${process.argv[1]}`) {
const client = new YesCaptcha(process.env.YESCAPTCHA_CLIENT_KEY);
console.log('balance:', await client.balance());
}
```
```js
import { YesCaptcha } from './yescaptcha.mjs';
const client = new YesCaptcha(process.env.YESCAPTCHA_CLIENT_KEY);
const solution = await client.solve({
type: 'TurnstileTaskProxyless',
websiteURL: 'https://example.com/login',
websiteKey: '0x4AAAAAAA_SITE_KEY',
});
console.log(solution.token);
```
Khi có lỗi, client ném `YesCaptchaError`; `err.code` là mã lỗi, ý nghĩa xem tại [Mã lỗi](https://docs.yescaptcha.com/vi/api/errors.md).
---
# C#
> Ví dụ C# của YesCaptcha (.NET 6+, HttpClient + System.Text.Json): truy vấn số dư, tạo tác vụ reCAPTCHA v2 và polling kết quả mỗi 5 giây.
Source: https://docs.yescaptcha.com/vi/samples/csharp/ · 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/samples/csharp/
Môi trường chạy: .NET 6 trở lên, chỉ dùng thư viện chuẩn (`HttpClient`, `System.Text.Json`).
```bash
dotnet new console -o YesCaptchaDemo
cd YesCaptchaDemo
# replace Program.cs with the code below
export YESCAPTCHA_CLIENT_KEY=your_client_key
dotnet run
```
Program.cs
```csharp
// YesCaptcha C# sample (.NET 6+): check the balance, then solve a reCAPTCHA v2.
// Run: dotnet new console -o YesCaptchaDemo, replace Program.cs with this file, set YESCAPTCHA_CLIENT_KEY, then dotnet run
using System;
using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json;
using System.Text.Json.Nodes;
using System.Threading.Tasks;
class Program
{
const string Api = "https://api.yescaptcha.com";
static readonly HttpClient Http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
static readonly string ClientKey = Environment.GetEnvironmentVariable("YESCAPTCHA_CLIENT_KEY") ?? "";
static async Task Call(string method, JsonObject payload)
{
payload["clientKey"] = ClientKey;
var res = await Http.PostAsJsonAsync($"{Api}/{method}", payload);
var data = JsonNode.Parse(await res.Content.ReadAsStringAsync())!;
if ((int?)data["errorId"] != 0)
throw new Exception($"{data["errorCode"]}: {data["errorDescription"]}");
return data;
}
static async Task Solve(JsonObject task)
{
var created = await Call("createTask", new JsonObject { ["task"] = task });
if ((string?)created["status"] == "ready") return created["solution"]!; // synchronous types
var taskId = (string)created["taskId"]!;
for (var i = 0; i < 36; i++) // poll every 5 seconds, for up to about 3 minutes
{
await Task.Delay(5000);
var result = await Call("getTaskResult", new JsonObject { ["taskId"] = taskId });
if ((string?)result["status"] == "ready") return result["solution"]!;
}
throw new TimeoutException(taskId);
}
static async Task Main()
{
var balance = await Call("getBalance", new JsonObject());
Console.WriteLine($"balance (points): {balance["balance"]}");
var solution = await Solve(new JsonObject
{
["type"] = "NoCaptchaTaskProxyless",
["websiteURL"] = "https://www.google.com/recaptcha/api2/demo",
["websiteKey"] = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
Console.WriteLine(solution["gRecaptchaResponse"]);
}
}
```
Khi đổi sang loại tác vụ khác, chỉ cần sửa đối tượng tác vụ trong `Solve`; các trường xem ở từng trang [loại tác vụ](https://docs.yescaptcha.com/vi/tasks.md). Các loại đồng bộ (nhận dạng hình ảnh, `ImageToTextTaskOcrBase`) trả kết quả ngay trong `createTask`, và `Solve` đã xử lý trường hợp này.
---
# Easy Language (易语言)
> Ví dụ YesCaptcha bằng Easy Language (易语言) do người dùng đóng góp: nhấp chuột mô phỏng cho reCAPTCHA và hCaptcha, nhận dạng hình ảnh FunCaptcha, gửi token reCAPTCHA; gói tải về và những điểm chính khi gọi API.
Source: https://docs.yescaptcha.com/vi/samples/easy-language/ · 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/samples/easy-language/
Easy Language (易语言) là ngôn ngữ lập trình tiếng Trung phổ biến tại Trung Quốc. Các ví dụ này do người dùng đóng góp (南方填表, 松, v.v.), chỉ mang tính tham khảo, chúng tôi chưa rà soát từng dòng. Các ví dụ gồm:
- Nhấp chuột mô phỏng cho reCAPTCHA và hCaptcha (mở trình duyệt, sau đó tự động nhận dạng và nhấp)
- Nhận dạng hình ảnh FunCaptcha
- Gửi token reCAPTCHA
> **Gói tải về:** Các gói ví dụ (gói lớn nhất khoảng 87 MB, kèm trình duyệt) đang được chuyển sang địa chỉ tải mới. Trong thời gian này, vui lòng [liên hệ hỗ trợ](https://docs.yescaptcha.com/vi/help/contact.md) để nhận.
## Gọi API bằng Easy Language
Không cần gói ví dụ, chỉ cần lệnh truy cập web (POST) của Easy Language là có thể gọi API:
1. Địa chỉ `https://api.yescaptcha.com/createTask`, phương thức `POST`, thêm header `Content-Type: application/json`.
2. Nội dung gửi là văn bản JSON, ví dụ `{"clientKey":"your_client_key","task":{"type":"ImageToTextTaskOcrBase","body":"BASE64_IMAGE"}}`.
3. Trong JSON trả về, `errorId` bằng 0 nghĩa là thành công. Với loại bất đồng bộ, lấy `taskId`, rồi cứ 5 giây gửi `{"clientKey":"…","taskId":"…"}` tới `https://api.yescaptcha.com/getTaskResult` (polling) cho đến khi `status` là `ready`.
4. Base64 của ảnh không được có tiền tố `data:image/...;base64,` và không được có ký tự xuống dòng.
Định dạng yêu cầu và phản hồi xem tại [Yêu cầu và phản hồi](https://docs.yescaptcha.com/vi/api/overview.md).
## Ví dụ không chạy được
- Báo không tạo được trình duyệt: dùng trình duyệt đi kèm trong gói ví dụ; gỡ các trình duyệt khác có thể xung đột; hoặc biên dịch thành chương trình rồi mới chạy.
- Trả về mã lỗi: đối chiếu tham số với [Mã lỗi](https://docs.yescaptcha.com/vi/api/errors.md).
---
# Nhiều clientKey: hạn mức, IP cho phép và thời gian hết hạn
> Một tài khoản YesCaptcha có tối đa 20 clientKey, cùng trừ vào một số dư tài khoản. Mỗi clientKey có thể đặt riêng hạn mức chi tiêu (theo ngày, tuần, tháng hoặc tổng một lần, đặt lại theo giờ Bắc Kinh), IP cho phép và thời gian hết hạn, có hiệu lực trong vài giây.
Source: https://docs.yescaptcha.com/vi/account/client-keys/ · Last verified: 2026-10-29
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/account/client-keys/
Một tài khoản YesCaptcha có tối đa 20 `clientKey` (gồm cả key ban đầu), quản lý tại trang “Khóa và bảo mật” trong bảng điều khiển [yescaptcha.com](https://yescaptcha.com/security). Mỗi `clientKey` đều có thể tạo tác vụ và truy vấn số dư, và đều trừ vào cùng một số dư tài khoản. Mỗi key có thể đặt riêng hạn mức chi tiêu, IP cho phép và thời gian hết hạn, có hiệu lực trong vài giây.
Phù hợp với các trường hợp: tách key cho môi trường thử nghiệm và môi trường production, hoặc cho từng dự án; cấp key cho khách hàng hạ nguồn hoặc đối tác, mỗi bên một hạn mức; khi một `clientKey` bị lộ, chỉ cần xóa đúng key đó, các chương trình khác không bị ảnh hưởng.
## Key chính và Key phụ
| | Key chính | Key phụ |
| --- | --- | --- |
| Là key nào | `clientKey` ban đầu, mỗi tài khoản có một | Key tạo thêm ngoài Key chính, tối đa 19 |
| Hạn mức, IP cho phép, thời gian hết hạn | Có thể đặt | Có thể đặt |
| Đặt lại | Có: key cũ mất hiệu lực ngay, số dư chuyển sang key mới | Không thể đặt lại, hãy xóa rồi tạo key khác |
| Xóa | Không | Có: mất hiệu lực trong vài giây, không thể khôi phục |
- Định dạng đều giống nhau: 40 ký tự đầu là khóa bí mật, phần sau là ID người dùng của bạn.
- Đặt lại Key chính không ảnh hưởng đến Key phụ.
- Dùng `clientKey` nào để tạo tác vụ hay truy vấn số dư thì giao diện API và kết quả trả về đều như nhau, chỉ thêm các bước kiểm tra hạn mức, IP cho phép và thời gian hết hạn.
## Tạo clientKey
1. Đăng nhập [yescaptcha.com](https://yescaptcha.com/), mở trang “Khóa và bảo mật” ([yescaptcha.com/security](https://yescaptcha.com/security)).
2. Trong “Tất cả Key”, bấm “Tạo Key phụ”. Tên (tối đa 40 ký tự), hạn mức, IP cho phép và thời gian hết hạn đều có thể để trống, sau này vẫn sửa được.
3. Xác minh danh tính thêm một lần theo hướng dẫn. Tạo, sửa và xóa đều cần xác minh.
4. Sau khi tạo, sao chép `clientKey` đầy đủ và cấu hình vào chương trình. Sau này cũng có thể bấm biểu tượng con mắt trong danh sách để xem lại.
> **Ghi chú:** Tạo, sửa và xóa đều có hiệu lực trong vài giây. Nếu gọi ngay sau khi vừa tạo, có thể nhận `ERROR_KEY_DOES_NOT_EXIST`, hãy đợi vài giây rồi thử lại; trong vài giây sau khi xóa hoặc siết chặt cài đặt, các yêu cầu đang được gửi đi vẫn có thể được xử lý theo cài đặt cũ.
## Hạn mức chi tiêu
Hạn mức giới hạn một `clientKey` được tiêu tối đa bao nhiêu điểm trong một chu kỳ (1,000 điểm = ¥1), có thể đặt từ 1 đến 10,000,000,000 điểm. Có bốn chu kỳ, đặt lại theo giờ Bắc Kinh (UTC+8):
| Chu kỳ | Khi nào đặt lại |
| --- | --- |
| Mỗi ngày | 0 giờ mỗi ngày |
| Mỗi tuần | 0 giờ thứ Hai hàng tuần |
| Mỗi tháng | 0 giờ ngày 1 hàng tháng |
| Tổng một lần | Không đặt lại. Dùng hết thì `clientKey` này không thể tạo tác vụ nữa, muốn tiếp tục dùng hãy tăng hạn mức |
- Tính theo số điểm thực tế đã trừ: điểm được hoàn lại do nhận dạng thất bại hoặc hết thời gian chờ cũng được hoàn lại vào hạn mức.
- Khi hạn mức còn lại của chu kỳ hiện tại không đủ để trừ điểm cho tác vụ này, `createTask` trả về [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED), không trừ điểm và không tính vào [tự động tạm dừng](https://docs.yescaptcha.com/vi/api/rate-limits.md).
- Trong danh sách ở bảng điều khiển có thể xem mỗi `clientKey` đã dùng bao nhiêu trong chu kỳ hiện tại và khi nào đặt lại tiếp theo.
- Hạn mức không phải số dư riêng: mọi `clientKey` đều trừ vào cùng một số dư tài khoản, khi số dư tài khoản không đủ vẫn trả về `ERROR_ZERO_BALANCE` như bình thường.
Khi gọi [`getBalance`](https://docs.yescaptcha.com/vi/api/get-balance.md) bằng `clientKey` có đặt hạn mức, `balance` là giá trị nhỏ hơn giữa số dư tài khoản và hạn mức còn lại của chu kỳ hiện tại, ngoài ra có thêm trường `keyQuotaRemaining` (hạn mức còn lại, tính bằng điểm). `clientKey` không đặt hạn mức không có trường này, kết quả trả về giống như trước.
```json
{
"errorId": 0,
"balance": 20000,
"softBalance": 0,
"inviteBalance": 0,
"inviteBy": 0,
"keyQuotaRemaining": 20000
}
```
## IP cho phép
`clientKey` có đặt IP cho phép chỉ dùng được với các yêu cầu gửi từ IP trong danh sách. Để trống nghĩa là không giới hạn.
- Điền **IP công khai của máy gọi API YesCaptcha** (IP đầu ra), không phải proxy trong tham số tác vụ. Nếu gọi từ nhiều máy, phải thêm IP công khai của từng máy.
- Mỗi dòng một địa chỉ IPv4 hoặc IPv6, hoặc dải CIDR, tối đa 50 mục. Một địa chỉ đơn nghĩa là chỉ cho phép đúng IP đó.
- Dải mạng phải viết ở dạng địa chỉ mạng: `203.0.113.0/24` được, `203.0.113.5/24` không được (các bit máy chủ không bằng 0).
```text
203.0.113.10
198.51.100.0/24
2001:db8::/32
```
- Khi IP của yêu cầu không có trong danh sách, `createTask` và `getBalance` trả về [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED), không trừ điểm và không tính vào tự động tạm dừng.
- Nếu IP đầu ra thay đổi (mạng gia đình, cloud function, đầu ra luân phiên) thì đừng đặt, hoặc đặt thành cả dải mạng.
## Thời gian hết hạn
- Mọi `clientKey` (kể cả Key chính) đều có thể đặt thời gian hết hạn, trong vòng mười năm; sau đó có thể sửa hoặc bỏ bất cứ lúc nào.
- Sau khi hết hạn, gọi `createTask` và `getBalance` bằng key đó sẽ trả về [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_KEY_EXPIRED), không trừ điểm. Các tác vụ đã tạo vẫn lấy được kết quả bằng `getTaskResult` như bình thường.
- Với `clientKey` lâu không sử dụng, hệ thống sẽ đặt thời gian hết hạn để bảo vệ an toàn tài khoản và gửi email nhắc trước khi hết hạn. Thời gian hết hạn này không thể sửa: hãy tạo lại Key chính (số dư tự động chuyển sang key mới) hoặc tạo một `clientKey` mới, rồi cập nhật vào chương trình.
## Số dư, giới hạn đồng thời và tự động tạm dừng
- **Số dư**: mọi `clientKey` đều trừ vào cùng một số dư tài khoản. Nạp tiền, điểm thưởng khi nạp của VIP, thưởng giới thiệu và chia sẻ doanh thu cho nhà phát triển đều tính theo tài khoản, không phụ thuộc vào việc dùng `clientKey` nào.
- **Giới hạn đồng thời**: tính theo tài khoản, tất cả `clientKey` cộng lại chịu chung một mức trần, xem [Giới hạn đồng thời và tự động tạm dừng](https://docs.yescaptcha.com/vi/api/rate-limits.md).
- **Tự động tạm dừng**: tính riêng cho từng `clientKey`, một `clientKey` gặp quá nhiều lỗi bị tạm dừng thì không ảnh hưởng đến các key khác.
## Mã lỗi liên quan
| Mã lỗi | Khi nào trả về |
| --- | --- |
| [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED) | Hạn mức còn lại của chu kỳ hiện tại không đủ cho tác vụ này (`createTask`) |
| [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) | IP của yêu cầu không có trong danh sách IP cho phép của `clientKey` này (`createTask`, `getBalance`) |
| [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_KEY_EXPIRED) | `clientKey` đã hết hạn (`createTask`, `getBalance`) |
Cả ba mã này đều không trừ điểm. Cách xử lý xem [Mã lỗi](https://docs.yescaptcha.com/vi/api/errors.md).
---
# Nạp tiền và VIP
> Cách nạp tiền vào YesCaptcha (WeChat Pay, Alipay, PayPal, tiền mã hóa), 1,000 điểm = ¥1. Tổng số tiền đã nạp tự động nâng cấp bạn từ VIP 1 lên VIP 10, và mỗi lần nạp sau đó được tặng thêm điểm theo tỷ lệ.
Source: https://docs.yescaptcha.com/vi/account/recharge/ · 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/account/recharge/
Nạp tiền tại trang nạp tiền trong bảng điều khiển [yescaptcha.com](https://yescaptcha.com/) ([yescaptcha.com/payment.html](https://yescaptcha.com/payment.html)). 1,000 điểm = ¥1, điểm vào tài khoản là dùng được ngay. Khi tổng số tiền đã nạp đạt một mức nhất định, bạn được tự động nâng cấp lên VIP, và mỗi lần nạp sau đó được tặng thêm điểm thưởng khi nạp theo tỷ lệ của cấp VIP.
## Phương thức nạp tiền
| Phương thức | Mô tả |
| --- | --- |
| WeChat Pay | Quét mã để thanh toán |
| Alipay | Quét mã hoặc chuyển hướng để thanh toán |
| PayPal | Phù hợp với người dùng ở nước ngoài |
| Tiền mã hóa | Thanh toán qua Cryptomus, hỗ trợ BTC, ETH, USDT, v.v. |
| Chuyển khoản doanh nghiệp | Liên hệ bộ phận hỗ trợ, bộ phận tài chính xác nhận rồi cộng tiền thủ công |
Lịch sử nạp tiền xem được tại trang nạp tiền. Nếu gặp sự cố khi nạp tiền, hãy [liên hệ bộ phận hỗ trợ](https://docs.yescaptcha.com/vi/help/contact.md) và cung cấp thông tin đơn hàng.
## Cấp VIP
Khi tổng số tiền đã nạp đạt mức ngưỡng trong bảng dưới đây, bạn được tự động nâng cấp lên cấp tương ứng; từ đó, mỗi lần nạp sau đều được cộng thêm điểm theo tỷ lệ thưởng.
| Cấp độ | Tổng số tiền đã nạp | Điểm thưởng mỗi lần nạp |
| --- | --- | --- |
| VIP 1 | ¥10 | 2% |
| VIP 2 | ¥100 | 5% |
| VIP 3 | ¥500 | 8% |
| VIP 4 | ¥1.000 | 10% |
| VIP 5 | ¥2.000 | 15% |
| VIP 6 | ¥3.000 | 20% |
| VIP 7 | ¥6.000 | 25% |
| VIP 8 | ¥12.000 | 30% |
| VIP 9 | ¥24.000 | 35% |
| VIP 10 | ¥48.000 | 40% |
- **Tính tích lũy**: dù nạp bao nhiêu lần, chỉ cần tổng số tiền đạt ngưỡng là được nâng cấp.
- **Tính theo tổng sau khi nạp**: ví dụ, nếu lần nạp đầu tiên là 1000 NDT, tổng số tiền đạt ngưỡng VIP 4 thì lần nạp này đã được tặng điểm theo tỷ lệ của VIP 4.
- Đăng ký qua liên kết giới thiệu của bạn bè sẽ được cấp VIP ngay, xem [Thưởng giới thiệu](https://docs.yescaptcha.com/vi/account/referral.md).
- Cấp hiện tại và tỷ lệ thưởng hiển thị tại trang nạp tiền trong bảng điều khiển.
---
# Thưởng giới thiệu
> Chương trình giới thiệu của YesCaptcha. Người được mời nhận VIP ngay khi đăng ký (cấp của bạn trừ 1, từ VIP 1 đến VIP 6), bạn nhận 20% số tiền họ chi tiêu (khi có chia sẻ doanh thu cho nhà phát triển thì mỗi bên 10%), có thể chuyển thành số dư hoặc rút khi đạt 100 ¥ trong bảng điều khiển.
Source: https://docs.yescaptcha.com/vi/account/referral/ · 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/account/referral/
Mời bạn bè đăng ký YesCaptcha: bạn bè đăng ký xong là có cấp VIP ngay, còn bạn nhận 20% số tiền họ chi tiêu. Phần thưởng có thể chuyển thành số dư tài khoản, hoặc rút trong bảng điều khiển khi đạt 100 ¥.
## Cách mời
Đăng nhập bảng điều khiển [yescaptcha.com](https://yescaptcha.com/). Trong bảng Chương trình giới thiệu, bạn sẽ thấy liên kết giới thiệu, số người đã mời và tổng phần thưởng tích lũy. Gửi liên kết cho bạn bè, họ đăng ký qua liên kết đó là được.
## Quy tắc
1. **VIP của bạn bè**: sau khi đăng ký, bạn bè nhận ngay cấp VIP bằng cấp của bạn trừ 1, thấp nhất VIP 1, cao nhất VIP 6. Ví dụ bạn là VIP 6 thì bạn bè đăng ký xong là VIP 5. Tỷ lệ điểm thưởng của từng cấp xem tại [Nạp tiền và VIP](https://docs.yescaptcha.com/vi/account/recharge.md).
2. **Phần thưởng của bạn**: mỗi lần bạn bè chi tiêu (trừ điểm khi nhận dạng), bạn nhận **20%** số tiền đó.
3. **Khi có chia sẻ doanh thu cho nhà phát triển**: nếu tác vụ của bạn bè còn mang ID của một nhà phát triển (xem [Chia sẻ doanh thu cho nhà phát triển](https://docs.yescaptcha.com/vi/account/developer.md)), người mời và nhà phát triển **mỗi bên nhận 10%**.
4. Với tác vụ mà bạn bè báo cáo kết quả nhận dạng sai và được hoàn điểm, phần thưởng tương ứng sẽ bị thu hồi.
5. Số dư phần thưởng có thể truy vấn bằng `inviteBalance` của [getBalance](https://docs.yescaptcha.com/vi/api/get-balance.md) (đơn vị: nhân dân tệ).
## Sử dụng phần thưởng
- **Chuyển thành số dư**: chuyển phần thưởng vào số dư tài khoản trong bảng điều khiển, dùng để nhận dạng theo tỷ lệ 1 ¥ = 1,000 điểm.
- **Rút tiền**: khi phần thưởng đạt **100 ¥**, gửi yêu cầu rút tiền trong bảng điều khiển, sau khi duyệt sẽ được chuyển khoản.
- Bạn tự kê khai thuế thu nhập cá nhân cho khoản tiền rút.
## Viết bài giới thiệu
Nếu bạn viết bài giới thiệu, hướng dẫn, chia sẻ kinh nghiệm, tiện ích hoặc thư viện mã liên quan đến YesCaptcha trên diễn đàn, blog hoặc mạng xã hội, hãy gửi liên kết cho bộ phận hỗ trợ. Chúng tôi sẽ đánh giá và có thể tặng điểm hoặc nâng cấp VIP (tùy chất lượng nội dung).
Nếu quy tắc thưởng có thay đổi, nội dung trên trang này và [Nhật ký cập nhật dịch vụ](https://docs.yescaptcha.com/vi/changelog.md) là căn cứ chính thức.
---
# Chia sẻ doanh thu cho nhà phát triển
> Chia sẻ doanh thu cho nhà phát triển của YesCaptcha: đưa softID của bạn vào các yêu cầu mà phần mềm hoặc tiện ích bạn phát triển gửi đi cho người dùng, bạn nhận 20% số tiền họ chi tiêu (10% mỗi bên khi người dùng còn có người giới thiệu); có thể chuyển thành số dư hoặc rút khi đủ 100 ¥ trong bảng điều khiển.
Source: https://docs.yescaptcha.com/vi/account/developer/ · 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/account/developer/
Nếu phần mềm, script hoặc tiện ích bạn phát triển có tích hợp YesCaptcha, hãy đưa ID nhà phát triển của bạn (`softID`) vào các yêu cầu mà nó gửi đi khi người khác sử dụng, bạn sẽ được chia một phần theo số tiền họ chi tiêu. Người dùng vẫn dùng `clientKey` của chính họ và bị trừ điểm của chính họ; khoản chia sẻ này không làm họ phải trả thêm.
## Cách tích hợp
1. Gọi [getSoftID](https://docs.yescaptcha.com/vi/api/get-soft-id.md) bằng `clientKey` của chính bạn để nhận ID nhà phát triển:
```json
{
"errorId": 0,
"softID": 3,
"balance": 0.004
}
```
2. Trong mỗi yêu cầu `createTask` mà phần mềm của bạn gửi đi, thêm trường cấp cao nhất `softID` (cùng cấp với `clientKey` và `task`, lưu ý phân biệt chữ hoa chữ thường):
```json
{
"clientKey": "THE_USERS_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
},
"softID": 3
}
```
`clientKey` là khóa của chính người dùng.
## Quy tắc chia sẻ
- Với các tác vụ có `softID` của bạn, **20%** số tiền người dùng thực tế chi tiêu được tính vào khoản chia sẻ doanh thu của bạn.
- Nếu người dùng này đồng thời được người khác giới thiệu (xem [Thưởng giới thiệu](https://docs.yescaptcha.com/vi/account/referral.md)), nhà phát triển và người giới thiệu **mỗi bên nhận 10%**.
- Chỉ các tác vụ đã trừ điểm thành công mới có chia sẻ; các tác vụ thất bại hoặc hết thời gian chờ và được hoàn điểm thì không có. Với tác vụ mà người dùng báo cáo kết quả nhận dạng sai và được hoàn điểm, khoản chia sẻ tương ứng sẽ bị thu hồi.
- Tra cứu số dư chia sẻ bằng `balance` của [getSoftID](https://docs.yescaptcha.com/vi/api/get-soft-id.md) hoặc `softBalance` của [getBalance](https://docs.yescaptcha.com/vi/api/get-balance.md); đơn vị là nhân dân tệ (¥).
## Sử dụng khoản chia sẻ
- **Chuyển thành số dư**: trong bảng điều khiển, chuyển khoản chia sẻ vào số dư tài khoản, quy đổi 1 ¥ = 1,000 điểm để dùng cho nhận dạng.
- **Rút tiền**: khi khoản chia sẻ đạt **100 ¥**, gửi yêu cầu rút tiền trong bảng điều khiển; sau khi duyệt sẽ được thanh toán.
- Bạn tự chịu trách nhiệm kê khai thuế thu nhập cá nhân đối với thu nhập từ việc rút tiền.
---
# Câu hỏi thường gặp
> Câu hỏi thường gặp về YesCaptcha: nhận dạng thất bại có bị trừ điểm không, token có hiệu lực bao lâu, tỷ lệ vượt qua, người hay máy nhận dạng, có bị khóa tài khoản không, dùng một clientKey ở nhiều nơi, chọn endpoint nào, khác biệt giữa tiện ích và API.
Source: https://docs.yescaptcha.com/vi/help/faq/ · 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/help/faq/
## YesCaptcha nhận dạng thất bại có bị trừ điểm không?
Không. Tác vụ nhận dạng thất bại (`ERROR_CAPTCHA_UNSOLVABLE`) và hết thời gian chờ (`ERROR_TASK_TIMEOUT`) được tự động hoàn điểm; các yêu cầu trả về mã lỗi, chẳng hạn do sai tham số, không bị trừ điểm. Nếu bạn đã nhận được token nhưng trang web đích không chấp nhận, tác vụ vẫn tính là thành công vì chúng tôi không biết kết quả đánh giá của trang web; với các loại nhận dạng hình ảnh, nếu vị trí nhấp sai, bạn có thể báo cáo để được hoàn điểm. Xem chi tiết tại [Tính phí và hoàn điểm](https://docs.yescaptcha.com/vi/getting-started/billing.md).
## Mỗi lần nhận dạng tốn bao nhiêu?
Mỗi loại tác vụ bị trừ một số điểm cố định, 1 nhân dân tệ = 1,000 điểm, và giá khác nhau tùy loại. Toàn bộ giá có tại [Loại tác vụ và giá](https://docs.yescaptcha.com/vi/tasks.md); bản đọc được bằng máy là [/data/task-types.json](https://docs.yescaptcha.com/data/task-types.json).
## Token có hiệu lực trong bao lâu?
Token của reCAPTCHA, hCaptcha và Turnstile đều chỉ dùng được một lần. Token reCAPTCHA có hiệu lực khoảng 120 giây, nên gửi trong vòng 60 giây sau khi nhận; thời hạn do nhà cung cấp captcha quy định.
## Vì sao đôi khi token không vượt qua được?
Việc token có được chấp nhận hay không do trang web đích quyết định. Trang web sẽ xem xét điểm số, IP, môi trường trình duyệt và nhiều yếu tố khác, ngưỡng có thể thay đổi bất cứ lúc nào, nên tỷ lệ vượt qua khác nhau theo từng trang web. Bạn có thể thử các loại tác vụ khác cho cùng loại captcha để so sánh, dùng loại có proxy riêng và gửi token qua cùng proxy đó, hoặc chuyển sang nhận dạng hình ảnh rồi nhấp thật trong trình duyệt.
## Nhận dạng mất bao lâu?
Tác vụ bất đồng bộ thường mất từ vài giây đến vài chục giây, tối đa khoảng 110 giây (một số ít loại là 180 đến 220 giây); quá thời gian sẽ tự động hoàn điểm. Nhận dạng hình ảnh và nhận dạng chữ-số trong ảnh là đồng bộ, trả kết quả ngay trong một yêu cầu.
## Nhận dạng bằng người hay bằng máy?
Bằng máy, dựa trên các mô hình học máy.
## Dùng YesCaptcha có làm tài khoản bị khóa không?
Chúng tôi chỉ trả về kết quả nhận dạng và không động đến tài khoản của bạn trên trang web đích. Trang web đích đánh giá thế nào và có khóa tài khoản hay không là do trang đó quyết định, vì vậy hãy tuân thủ quy định của họ. YesCaptcha chỉ được dùng cho mục đích hợp pháp, nghiêm cấm dùng cho mục đích bất hợp pháp.
## Một clientKey có dùng đồng thời trong nhiều chương trình, nhiều trình duyệt được không?
Được. Các yêu cầu cùng tài khoản được tính chung [giới hạn đồng thời](https://docs.yescaptcha.com/vi/api/rate-limits.md) và dùng chung một số dư.
## Nên dùng endpoint quốc tế hay endpoint Trung Quốc?
Máy chủ đặt tại Trung Quốc đại lục dùng `cn.yescaptcha.com`, các khu vực khác dùng `api.yescaptcha.com`. Tác vụ được tạo ở endpoint nào thì truy vấn kết quả ở endpoint đó. Xem [Địa chỉ truy cập](https://docs.yescaptcha.com/vi/getting-started/endpoints.md).
## Tiện ích trình duyệt và API khác nhau thế nào?
Tiện ích cũng gọi cùng bộ API để nhận dạng, cài đặt miễn phí, trừ điểm theo các API đã dùng, phù hợp khi bạn muốn dùng ngay trong trình duyệt mà không viết code; API phù hợp để xử lý hàng loạt trong chương trình. Xem [Tiện ích trình duyệt](https://docs.yescaptcha.com/vi/extension.md).
## Vì sao tôi bị tạm dừng và nhận ERROR\_IP\_BLOCKED\_5MIN?
Cùng một clientKey đã gửi quá nhiều yêu cầu lỗi trong một phút nên bị tự động tạm dừng vài phút, hết thời gian sẽ tự khôi phục. `blockReason` trong phản hồi là mã lỗi gây ra việc tạm dừng, hãy sửa chương trình theo mã lỗi đó. Xem [Giới hạn đồng thời và tự động tạm dừng](https://docs.yescaptcha.com/vi/api/rate-limits.md).
## Hỗ trợ những trang web nào?
Chúng tôi cung cấp nhận dạng theo loại captcha, không nhắm vào từng trang web cụ thể. Có vượt qua được hay không phụ thuộc vào cấu hình của trang web đích, nên hãy thử với một lô nhỏ trước. Với một số trang web chưa được hỗ trợ, hệ thống sẽ trả về `ERROR_DOMAIN_NOT_ALLOWED`.
---
# Sự cố kết nối và mạng
> Cách xử lý khi không kết nối được API YesCaptcha. Các bước kiểm tra lỗi Failed to establish a new connection, lỗi phân giải DNS, phần mềm proxy gây nhiễu và lỗi chứng chỉ SSL (Certificate has expired, SSLEOFError).
Source: https://docs.yescaptcha.com/vi/help/troubleshooting/ · 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/help/troubleshooting/
Khi gọi API mà gặp lỗi kết nối (ví dụ `Failed to establish a new connection`, `getaddrinfo failed`, hết thời gian chờ, lỗi SSL), nguyên nhân thường nằm ở mạng, DNS hoặc phần mềm proxy trên máy của bạn. Hãy kiểm tra theo thứ tự dưới đây.
## 1\. Thử đổi endpoint
YesCaptcha có hai endpoint: `https://api.yescaptcha.com` (quốc tế) và `https://cn.yescaptcha.com` (Trung Quốc). Máy chủ ở Trung Quốc đại lục dùng endpoint Trung Quốc, các khu vực khác dùng endpoint quốc tế. Sau khi đổi endpoint, hãy truy vấn kết quả bằng cùng endpoint đó.
```bash
curl -s https://api.yescaptcha.com/getBalance -H 'Content-Type: application/json' -d '{"clientKey": "YOUR_CLIENT_KEY"}'
curl -s https://cn.yescaptcha.com/getBalance -H 'Content-Type: application/json' -d '{"clientKey": "YOUR_CLIENT_KEY"}'
```
Nếu một trong hai lệnh trả về JSON, mạng của bạn vẫn hoạt động và sự cố nằm ở đường truyền tới endpoint còn lại.
## 2\. Kiểm tra phần mềm proxy
Truy cập YesCaptcha không cần proxy. Nếu máy đang bật proxy hoặc VPN:
- Hãy tắt đi rồi thử lại;
- Nếu bắt buộc phải bật, hãy chuyển sang chế độ chia luồng theo quy tắc (chế độ PAC) thay vì chế độ toàn cục, hoặc thêm `api.yescaptcha.com` và `cn.yescaptcha.com` vào danh sách kết nối trực tiếp;
- Nếu Python báo `SSLEOFError(8, 'EOF occurred in violation of protocol')` khi đang bật proxy, nguyên nhân thường cũng là proxy. Hãy tắt proxy hoặc cho hai tên miền này kết nối trực tiếp.
## 3\. Kiểm tra mạng và DNS
```bash
ping api.yescaptcha.com
```
- Báo không tìm thấy máy chủ: phân giải DNS thất bại. Hãy xóa bộ nhớ đệm DNS (Windows: `ipconfig /flushdns`; macOS: `sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder`), hoặc đổi DNS của máy sang DNS công cộng (ví dụ `223.5.5.5`, `119.29.29.29`, `8.8.8.8`) rồi thử lại.
- Ping không thông nhưng vẫn phân giải được địa chỉ: có thể mạng chặn ICMP, điều này không có nghĩa là API không truy cập được. Hãy lấy kết quả curl ở bước 1 làm chuẩn.
## 4\. Lỗi chứng chỉ SSL
- Báo `Certificate has expired` hoặc `certificate verify failed`: trước hết kiểm tra **giờ hệ thống** của máy đã đúng chưa; sau đó cập nhật hệ điều hành, `certifi` của Python, Postman hoặc các công cụ khác lên phiên bản mới nhất để chúng có chứng chỉ gốc mới nhất.
- Luôn dùng `https://`. Đừng chuyển sang `http://` hoặc tắt kiểm tra chứng chỉ để bỏ qua lỗi.
## 5\. Vẫn không được?
[Liên hệ bộ phận hỗ trợ](https://docs.yescaptcha.com/vi/help/contact.md) và gửi kèm: thông báo lỗi đầy đủ, endpoint bạn đang dùng, khu vực đặt máy chủ, và kết quả lệnh curl ở bước 1.
---
# Liên hệ chúng tôi
> Liên hệ bộ phận hỗ trợ YesCaptcha qua WeChat, QQ, WhatsApp, LINE, Telegram @yescaptcha_official hoặc email yescaptcha@gmail.com, 9:00–21:00 UTC+8.
Source: https://docs.yescaptcha.com/vi/help/contact/ · 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/help/contact/
Bộ phận hỗ trợ YesCaptcha làm việc **9:00–21:00 UTC+8** (giờ Bắc Kinh). Nếu phản hồi chậm, vui lòng để lại tin nhắn, chúng tôi sẽ xử lý sớm nhất có thể.
- Email: [yescaptcha@gmail.com](mailto:yescaptcha@gmail.com)
- Telegram: [@yescaptcha\_official](https://t.me/yescaptcha_official)
Quét mã để thêm liên hệ:
**WeChat**Quét mã bằng WeChat để kết bạn, chúng tôi có thể thêm bạn vào nhóm người dùng
**QQ**Quét mã bằng QQ để kết bạn
**WhatsApp**Quét mã bằng camera của WhatsApp để thêm
**LINE**Quét mã trong mục "Thêm bạn" của LINE
**[Telegram](https://t.me/yescaptcha_official)**@yescaptcha\_official
Khi liên hệ, vui lòng gửi kèm:
- Email tài khoản hoặc ID người dùng của bạn (**không** gửi `clientKey`);
- `taskId`, mã lỗi liên quan và thời điểm xảy ra;
- Loại tác vụ bạn dùng và endpoint nào (`api.yescaptcha.com` hoặc `cn.yescaptcha.com`).
Nhiều câu hỏi có thể tìm thấy câu trả lời trong [Câu hỏi thường gặp](https://docs.yescaptcha.com/vi/help/faq.md), [Mã lỗi](https://docs.yescaptcha.com/vi/api/errors.md) và [Sự cố kết nối và mạng](https://docs.yescaptcha.com/vi/help/troubleshooting.md).
---
# Nhật ký cập nhật dịch vụ
> Những thay đổi ảnh hưởng đến người dùng YesCaptcha, ghi theo ngày: loại tác vụ mới và đã ngừng, quy tắc tính phí và hoàn điểm, giới hạn đồng thời, việc chuyển tài liệu. Bắt đầu ghi từ 2026-10.
Source: https://docs.yescaptcha.com/vi/changelog/ · Last verified: 2026-10-19
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/changelog/
Trang này ghi lại theo ngày những thay đổi ảnh hưởng đến người dùng: loại tác vụ được mở và ngừng, quy tắc tính phí, quy tắc giới hạn tốc độ, v.v. Mới nhất ở trên cùng.
## 2026-10-19
- **Trang thử thách Cloudflare không còn bị đánh dấu “không khuyến nghị”**: dịch vụ phía sau `CloudFlareTaskS2` và `CloudFlareTaskS3` đã được xây dựng lại, mỗi tác vụ thường mất từ 6 đến 35 giây. Tham số, kết quả trả về và hiệu quả của hai loại này như nhau, giá không đổi (25 điểm và 20 điểm). Proxy chỉ hỗ trợ `http://` (có thể kèm tài khoản và mật khẩu) và `socks5://` không kèm tài khoản và mật khẩu; proxy `https://`, địa chỉ máy cục bộ và địa chỉ mạng nội bộ sẽ bị từ chối ngay khi tạo tác vụ (không trừ điểm). `userAgent` chỉ được dùng nếu là Chrome bản desktop trên Linux, các request tiếp theo hãy dùng `user_agent` trong kết quả trả về. Nếu truyền `requiredCookies`, tác vụ chỉ thành công khi lấy được tất cả các cookie đó. Xem [Trang thử thách Cloudflare](https://docs.yescaptcha.com/vi/tasks/cloudflare-challenge.md).
## 2026-10-16
- **Các loại FunCaptcha trả về token tạm thời không khuyến nghị sử dụng**: chi phí cao và chưa có giải pháp ổn định. `FunCaptchaTask` đổi thành 30 điểm mỗi tác vụ (trước đây là 15 điểm). `FunCaptchaTaskProxyless` vẫn không thể nhận dạng thành công, các tác vụ thất bại sẽ tự động hoàn điểm. Nếu cần vượt FunCaptcha, nên dùng [nhận dạng hình ảnh FunCaptcha](https://docs.yescaptcha.com/vi/tasks/funcaptcha-classification.md) hoặc tiện ích trình duyệt.
## 2026-10-15
- **Chuyển tài liệu**: tài liệu được chuyển từ Confluence sang trang này (docs.yescaptcha.com), có tiếng Trung, tiếng Anh và tiếng Việt, bản tiếng Trung là bản chuẩn. Có [llms.txt](https://docs.yescaptcha.com/llms.txt), [OpenAPI](https://docs.yescaptcha.com/openapi.json) và bản Markdown của từng trang để AI và chương trình đọc.
- **Hoàn điểm sau khi báo cáo được quyết toán sau khoảng 24 giờ**: với các loại nhận dạng hình ảnh, sau khi báo cáo nhận dạng sai sẽ không hoàn điểm ngay mà được quyết toán chung sau khoảng 24 giờ; nếu tỷ lệ thất bại cao hơn rõ rệt so với cùng kỳ, sẽ hoàn điểm theo tỷ lệ thất bại của cùng kỳ. Xem [Tính phí và hoàn điểm](https://docs.yescaptcha.com/vi/getting-started/billing.md).
- **Giới hạn đồng thời**: bắt đầu thống kê số tác vụ đang xử lý đồng thời theo tài khoản và theo loại tác vụ; khi vượt hạn mức sẽ trả về `ERROR_THREADS_MAXIMUM`, không trừ điểm và không tính vào tự động tạm dừng. Hạn mức của từng loại sẽ được công bố tại [Giới hạn đồng thời và tự động tạm dừng](https://docs.yescaptcha.com/vi/api/rate-limits.md) sau khi chốt.
- **Bổ sung các loại tác vụ công khai**: `HCaptchaTask`, `NoCaptchaTask`, `TurnstileTask`, `RecaptchaV2EnterpriseTask` (dùng proxy riêng của bạn), `FunCaptchaTaskProxylessM1`, `FunCaptchaTask`, `HCaptchaTaskProxylessM1` đã được đưa vào tài liệu.
- **Các loại FunCaptcha trả về token**: `FunCaptchaTaskProxylessM1`, `FunCaptchaTask` dùng được; tuyến của `FunCaptchaTaskProxyless` không thể nhận dạng thành công từ khoảng 2026-09-10, các tác vụ thất bại sẽ tự động hoàn điểm.
- **Ngừng dịch vụ**: dòng reCAPTCHA K1 vân tay tùy chỉnh, `FunCaptchaTaskS1`, `CloudFlareTaskS1`, `TurnstileTaskS2`, `TurnstileTaskProxylessS2`, `bCaptcha2Classification`, `GeneralClassification` đã ngừng phục vụ.
## Trước 2026-10-15
- Dịch vụ tự thuê **máy chủ riêng** đã ngừng.