Loại tác vụ

hCaptcha

Trang này được dịch máy từ bản tiếng Trung và có thể có sai sót. Nội dung theo bản tiếng Trung.

Tôi là con ngườihCaptchaQuyền riêng tư - Điều khoản

Hình minh họahCaptcha: ô đánh dấu "Tôi là con người". Khi nhấp vào, ô được đánh dấu ngay hoặc hiện ra một câu hỏi bằng hình ảnh.

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.

POSThttps://api.yescaptcha.com/createTaskEndpoint quốc tế

POSThttps://cn.yescaptcha.com/createTaskEndpoint 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.

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

Ví dụ request

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

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"}'

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"])

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:

{
  "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ề

{
  "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:

Đ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.
Khi gửi request, dùng userAgent được trả về làm User-Agent.
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.

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.