Di chuyển từ EndCaptcha sang CaptchaAI: Hướng dẫn ánh xạ API

Chuyển từ EndCaptcha sang CaptchaAI về bản chất là đổi cách gọi API: bỏ giao thức SOAP/XML với cặp username/password, chuyển sang REST với hai endpoint in.php (gửi task) và res.php (lấy kết quả), xác thực bằng một API key duy nhất. Logic bốn bước quen thuộc — gửi task, nhận ID, polling, dùng kết quả — vẫn giữ nguyên; bạn chỉ đổi URL, tham số và cách đọc phản hồi. Với các team QA và scraping ở Việt Nam, phần lớn công việc nằm ở lớp hàm gọi API; thay đúng lớp đó là xong.

Khác biệt kiến trúc API: SOAP/XML so với REST

EndCaptcha dùng SOAP/XML; CaptchaAI dùng REST tối giản với hai endpoint và phản hồi JSON.

Ánh xạ tham số EndCaptcha sang CaptchaAI

Dễ vấp nhất: username/password gộp thành một key.

Ánh xạ loại CAPTCHA sang method

EndCaptcha đánh số loại CAPTCHA; CaptchaAI dùng chuỗi method có nghĩa:

Lưu ý: CaptchaAI hiện không hỗ trợ hCaptcha và FunCaptcha (Arkose Labs) — luồng cũ gọi hai loại này cần xử lý riêng. CaptchaAI hỗ trợ reCAPTCHA v3, Cloudflare Challenge, GeeTest v3, CAPTCHA ảnh/lưới.

Chuyển đổi code: bản cũ và bản mới

Python — bản EndCaptcha cũ

Hàm gốc gửi ảnh base64 lên /Captcha/Upload rồi polling /Captcha/GetText:

import requests

USERNAME = "your_endcaptcha_user"
PASSWORD = "your_endcaptcha_pass"

def solve_image_endcaptcha(image_base64):
    # EndCaptcha image solve
    resp = requests.post("https://api.endcaptcha.com/Captcha/Upload", data={
        "username": USERNAME,
        "password": PASSWORD,
        "captchaData": image_base64,
        "captchaType": "1"
    })
    result = resp.json()
    captcha_id = result.get("captchaId")

    import time
    for _ in range(30):
        time.sleep(5)
        poll = requests.post("https://api.endcaptcha.com/Captcha/GetText", data={
            "username": USERNAME,
            "password": PASSWORD,
            "captchaId": captcha_id
        })
        poll_result = poll.json()
        if poll_result.get("text"):
            return {"solution": poll_result["text"]}
        if poll_result.get("error"):
            return {"error": poll_result["error"]}

    return {"error": "TIMEOUT"}

Python — bản CaptchaAI mới

Cùng luồng với CaptchaAI: gửi lên in.php, kiểm tra status, polling res.php.

import os
import time
import requests

API_KEY = os.environ["CAPTCHAAI_API_KEY"]

def solve_image_captchaai(image_base64):
    resp = requests.post("https://ocr.captchaai.com/in.php", data={
        "key": API_KEY,
        "method": "base64",
        "body": image_base64,
        "json": 1
    })
    data = resp.json()
    if data.get("status") != 1:
        return {"error": data.get("request")}

    captcha_id = data["request"]

    for _ in range(30):
        time.sleep(5)
        result = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": API_KEY,
            "action": "get",
            "id": captcha_id,
            "json": 1
        }).json()
        if result.get("status") == 1:
            return {"solution": result["request"]}
        if result.get("request") != "CAPCHA_NOT_READY":
            return {"error": result.get("request")}

    return {"error": "TIMEOUT"}

Python — giải reCAPTCHA v2 với CaptchaAI

Với reCAPTCHA v2, đổi method thành userrecaptcha, truyền googlekey và pageurl; nới polling lên 60 lần vì CAPTCHA token lâu hơn:

def solve_recaptcha_v2(sitekey, pageurl):
    resp = requests.post("https://ocr.captchaai.com/in.php", data={
        "key": API_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": pageurl,
        "json": 1
    })
    data = resp.json()
    if data.get("status") != 1:
        return {"error": data.get("request")}

    captcha_id = data["request"]

    for _ in range(60):
        time.sleep(5)
        result = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": API_KEY, "action": "get",
            "id": captcha_id, "json": 1
        }).json()
        if result.get("status") == 1:
            return {"solution": result["request"]}
        if result.get("request") != "CAPCHA_NOT_READY":
            return {"error": result.get("request")}

    return {"error": "TIMEOUT"}

JavaScript — bản EndCaptcha cũ

Phía Node.js, EndCaptcha gửi username/password qua axios:

const axios = require("axios");

const USERNAME = "your_endcaptcha_user";
const PASSWORD = "your_endcaptcha_pass";

async function solveImageEndCaptcha(imageBase64) {
  const submit = await axios.post("https://api.endcaptcha.com/Captcha/Upload", {
    username: USERNAME,
    password: PASSWORD,
    captchaData: imageBase64,
    captchaType: "1",
  });
  const captchaId = submit.data.captchaId;

  for (let i = 0; i < 30; i++) {
    await new Promise((r) => setTimeout(r, 5000));
    const poll = await axios.post("https://api.endcaptcha.com/Captcha/GetText", {
      username: USERNAME,
      password: PASSWORD,
      captchaId,
    });
    if (poll.data.text) return { solution: poll.data.text };
    if (poll.data.error) return { error: poll.data.error };
  }
  return { error: "TIMEOUT" };
}

JavaScript — bản CaptchaAI mới

Bản CaptchaAI truyền tham số qua params và đọc trường request thay cho text:

const axios = require("axios");
const API_KEY = process.env.CAPTCHAAI_API_KEY;

async function solveImageCaptchaAI(imageBase64) {
  const submit = await axios.post("https://ocr.captchaai.com/in.php", null, {
    params: { key: API_KEY, method: "base64", body: imageBase64, json: 1 },
  });
  if (submit.data.status !== 1) return { error: submit.data.request };

  const captchaId = submit.data.request;

  for (let i = 0; i < 30; i++) {
    await new Promise((r) => setTimeout(r, 5000));
    const poll = await axios.get("https://ocr.captchaai.com/res.php", {
      params: { key: API_KEY, action: "get", id: captchaId, json: 1 },
    });
    if (poll.data.status === 1) return { solution: poll.data.request };
    if (poll.data.request !== "CAPCHA_NOT_READY") return { error: poll.data.request };
  }
  return { error: "TIMEOUT" };
}

Những khác biệt cần lưu ý khi chuyển

Vài điểm sau dễ khiến migration hỏng lặng lẽ:

Checklist chuyển đổi

Chạy tuần tự khi migration production:

Khắc phục sự cố thường gặp

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

CaptchaAI tính phí theo lượt giải hay theo thread?

Theo thread. CaptchaAI dùng giá theo thread (luồng giải đồng thời), số lượt giải không giới hạn trong mỗi gói. Gói nhỏ nhất là BASIC ($15/tháng, 5 thread); cần nhiều luồng hơn thì lên STANDARD ($30/tháng, 15 thread).

CaptchaAI có giải hCaptcha giống EndCaptcha không?

Không. CaptchaAI chưa hỗ trợ hCaptcha và FunCaptcha (Arkose Labs); phần code cũ xử lý hCaptcha cần thay bằng giải pháp khác. Các loại như reCAPTCHA v2/v3, Turnstile, GeeTest v3 và CAPTCHA ảnh thì ánh xạ trực tiếp được.

Có nên chạy song song hai nhà cung cấp trước khi chuyển hẳn không?

Nên. Cho CaptchaAI chạy song song trên một phần lưu lượng, đối chiếu tỷ lệ giải thành công và thời gian giải vài ngày rồi mới chuyển hẳn — cách này phát hiện sớm khác biệt về phân tích phản hồi trước khi ảnh hưởng người dùng thật.

Bài viết liên quan

• Ánh xạ endpoint API giữa các nhà cung cấp
• Hướng dẫn di chuyển thủ công sang API CaptchaAI

Bước tiếp theo

Đơn giản hóa việc giải CAPTCHA bằng REST API của CaptchaAI — lấy API key và bắt đầu chuyển đổi ngay hôm nay.

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

• Tham chiếu ánh xạ endpoint API
• Chuyển từ AZCaptcha sang CaptchaAI
• Kiểm thử chạy song song khi migration