CaptchaAI Quickstart: giải CAPTCHA đầu tiên trong 5 phút

Bạn vừa tạo tài khoản CaptchaAI và muốn thấy token đầu tiên trả về ngay, chưa cần đọc hết tài liệu API? Bài viết này đi thẳng con đường ngắn nhất: từ API key đến một CAPTCHA đã giải trong khoảng năm phút, với code dán vào là chạy.

Điểm cần nắm trước tiên: dù bạn giải Cloudflare Turnstile cho một luồng đăng nhập nội bộ, hay một team QA ở TP.HCM đang dựng bộ regression test tự động, mọi loại CAPTCHA mà CaptchaAI hỗ trợ đều chạy theo đúng một vòng bốn bước giống nhau:

1. Gửi — đẩy thông tin CAPTCHA tới in.php
2. Lấy task ID từ response trả về
3. Polling — gọi res.php mỗi 5 giây cho đến khi có kết quả
4. Dùng token — chèn token đã giải vào trang hoặc request đích

Nắm được vòng này rồi thì đổi sang reCAPTCHA v2, GeeTest v3 hay OCR ảnh chỉ là đổi vài tham số, phần khung code giữ nguyên.

Bước 0: lấy API key và kiểm tra thread

1. Đăng ký tại captchaai.com
2. Mở dashboard
3. Sao chép API key 32 ký tự

CaptchaAI tính phí theo thread (luồng giải đồng thời), không tính theo mỗi lần giải. Gói vào cửa là BASIC ($15/tháng, 5 thread) với số lần giải không giới hạn trong tháng, nên chi phí phụ thuộc vào số request chạy song song chứ không phải tổng số CAPTCHA bạn giải.

Tài khoản cần có ít nhất một thread đang hoạt động thì mới gửi được task. Nếu bạn đang đánh giá dịch vụ, liên hệ support để xin thread dùng thử trước khi nạp gói.

Bước 1: gửi CAPTCHA Turnstile đầu tiên

Ví dụ dưới đây giải Cloudflare Turnstile — một trong những loại phổ biến nhất hiện nay. Bạn cần lấy hai giá trị từ trang đích:

• sitekey — khóa công khai của widget Turnstile, nằm trong thuộc tính data-sitekey hoặc tham số của script Turnstile, luôn bắt đầu bằng 0x
• pageurl — URL đầy đủ của trang nơi widget được nạp

Gửi cả hai tới in.php bằng ngôn ngữ bạn đang dùng:

cURL

curl -X POST "https://ocr.captchaai.com/in.php" \
  -d "key=YOUR_API_KEY" \
  -d "method=turnstile" \
  -d "sitekey=0x4AAAAAAAC3DHQFLr1GavNl" \
  -d "pageurl=https://staging.example.com/qa-login" \
  -d "json=1"

Python

import requests

response = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "turnstile",
    "sitekey": "0x4AAAAAAAC3DHQFLr1GavNl",
    "pageurl": "https://staging.example.com/qa-login",
    "json": 1,
})
print(response.json())

Node.js

const response = await fetch("https://ocr.captchaai.com/in.php", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    key: "YOUR_API_KEY",
    method: "turnstile",
    sitekey: "0x4AAAAAAAC3DHQFLr1GavNl",
    pageurl: "https://staging.example.com/qa-login",
    json: "1",
  }),
});
console.log(await response.json());

PHP

<?php
$response = file_get_contents("https://ocr.captchaai.com/in.php?" . http_build_query([
    "key"       => "YOUR_API_KEY",
    "method"    => "turnstile",
    "sitekey"   => "0x4AAAAAAAC3DHQFLr1GavNl",
    "pageurl"   => "https://staging.example.com/qa-login",
    "json"      => 1,
]));
echo $response;

Bước 2: lưu lại task ID

Nếu gửi thành công, response trả về dạng:

{
  "status": 1,
  "request": "71823469"
}

Trường request chính là ID task của bạn — giữ lại để bước sau lấy kết quả.

Nếu status bằng 0, đã có gì đó sai; mã lỗi cụ thể nằm ngay trong request:

Đọc đúng mã lỗi ở đây sẽ tiết kiệm cho bạn rất nhiều thời gian đoán mò.

Bước 3: polling để lấy kết quả

Turnstile cần vài giây để giải xong, nên đừng hỏi kết quả ngay lập tức. Đợi 15 giây cho lần polling đầu tiên, sau đó gọi res.php mỗi 5 giây cho đến khi có token. (Polling nghĩa là chủ động hỏi kết quả định kỳ.)

Python

import time

time.sleep(15)

while True:
    result = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": "YOUR_API_KEY",
        "action": "get",
        "id": "71823469",
        "json": 1,
    }).json()

    if result.get("request") == "CAPCHA_NOT_READY":
        time.sleep(5)
        continue

    if result.get("status") == 1:
        token = result["request"]
        print(f"Solved! Token: {token[:60]}...")
        break

    raise RuntimeError(result)

Node.js

await new Promise((r) => setTimeout(r, 15000));

while (true) {
  const r = await fetch(
    `https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=get&id=71823469&json=1`,
  );
  const data = await r.json();
  if (data.request === "CAPCHA_NOT_READY") {
    await new Promise((r) => setTimeout(r, 5000));
    continue;
  }
  if (data.status === 1) {
    console.log("Solved:", data.request.slice(0, 60));
    break;
  }
  throw new Error(JSON.stringify(data));
}

Khi trạng thái trả về 1, trường request chính là token đã giải. Một lần giải Turnstile thông thường mất khoảng 15–30 giây tính từ lúc gửi task.

Bước 4: dùng token đã giải

Cách chèn token tùy theo loại CAPTCHA:

• Turnstile / reCAPTCHA: ghi token vào trường cf-turnstile-response hoặc g-recaptcha-response, hoặc gọi callback của trang.
• OCR ảnh: đặt đoạn văn bản nhận diện được vào ô nhập đáp án.
• GeeTest v3: ghép các trường trả về theo đúng yêu cầu của site.

Cách chèn nhanh nhất ngay trong trình duyệt:

document.querySelector('[name="cf-turnstile-response"]').value = token;
document.querySelector("form").submit();

Lưu ý token Turnstile và reCAPTCHA chỉ dùng một lần và hết hạn sau khoảng 120 giây, nên hãy theo nguyên tắc gửi — dùng — bỏ, đừng cache lại.

Những lỗi hay gặp trong lần chạy đầu

Phần lớn sự cố ngày đầu đều rơi vào vài trường hợp quen thuộc:

• API key dính khoảng trắng — xóa sạch trước khi gửi.
• Thiếu giao thức trong pageurl — phải là https://... đầy đủ.
• Polling quá sớm — chờ đủ 15 giây rồi mới hỏi lần đầu.
• Polling quá dồn dập — 5 giây một lần là đủ, gọi dày hơn chỉ phí request.
• Dùng sai sitekey của trang — sitekey gắn với từng trang; lấy nhầm sẽ nhận token bị đích từ chối (HTTP 403).
• Hết thread — kiểm tra định dạng response API và số thread trong gói của bạn.

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

Giải một CAPTCHA mất bao lâu? Với Turnstile, một lần giải thông thường mất khoảng 15–30 giây. Vì vậy lần polling đầu tiên nên chờ 15 giây rồi mới hỏi res.php, tránh nhận CAPCHA_NOT_READY liên tục và phí một slot đang chạy.

Tôi cần gói nào để bắt đầu? Gói nhỏ nhất là BASIC ($15/tháng, 5 thread) với số lần giải không giới hạn. Vì tính phí theo thread, bạn chỉ cần thêm thread khi muốn chạy nhiều request song song hơn, chứ không trả tiền theo từng CAPTCHA.

CaptchaAI có giải được hCaptcha không? Không. CaptchaAI hiện chưa hỗ trợ hCaptcha và FunCaptcha. Các loại đang hỗ trợ gồm reCAPTCHA v2/v3, Cloudflare Turnstile và Challenge, GeeTest v3, OCR ảnh, grid và BLS.

Nên dùng polling hay callback? Để bắt đầu, cứ dùng polling như trong bài — đơn giản và dễ debug. Khi lên production và muốn giảm số request thừa, chuyển sang callback/webhook để CaptchaAI tự gửi kết quả về URL của bạn.

Bước tiếp theo

• Cách giải reCAPTCHA v2 bằng API
• Cách giải Cloudflare Turnstile bằng API
• Cách giải GeeTest v3 bằng API
• Giải CAPTCHA ảnh (OCR) bằng API