Giải thích về định dạng phản hồi API CaptchaAI

CaptchaAI sử dụng phản hồi dựa trên văn bản đơn giản. Tài liệu tham khảo này bao gồm mọi định dạng phản hồi mà bạn sẽ gặp, kèm theo các ví dụ về phân tích cú pháp.

Gửi điểm cuối (in.php)

Phản hồi thành công

OK|TASK_ID

Ví dụ: OK|73548291

Phản hồi lỗi

ERROR_CODE

Ví dụ: ERROR_WRONG_USER_KEY

Phân tích cú pháp

resp = requests.get("https://ocr.captchaai.com/in.php", params={...})

if resp.text.startswith("OK|"):
    task_id = resp.text.split("|")[1]
else:
    error = resp.text
    raise Exception(f"Submit failed: {error}")

const resp = await axios.get("https://ocr.captchaai.com/in.php", { params });

if (resp.data.startsWith("OK|")) {
  const taskId = resp.data.split("|")[1];
} else {
  throw new Error(`Submit failed: ${resp.data}`);
}

Điểm cuối cuộc thăm dò (res.php)

Phản hồi chưa sẵn sàng

CAPCHA_NOT_READY

Nhiệm vụ vẫn đang được xử lý. Đợi 5 giây và thăm dò lại.

Thành công — CAPTCHA dựa trên mã thông báo

Đối với reCAPTCHA, Turnstile, hCaptcha, v.v.:

OK|03AGdBq24PBCbw...long_token_string

Thành công — Image/OCR CAPTCHA

OK|abc123

Văn bản sau OK| là văn bản được nhận dạng từ hình ảnh.

Thành công — GeeTest

OK|challenge:abc123,validate:def456,seccode:ghi789

Phân tích từng trường:

if result.text.startswith("OK|"):
    data = result.text.split("|")[1]
    parts = dict(item.split(":") for item in data.split(","))
    challenge = parts["challenge"]
    validate = parts["validate"]
    seccode = parts["seccode"]

Thành công — Cloudflare Challenge

Trả về giá trị cookie <staging-session-cookie> và tác nhân người dùng:

OK|<staging-session-cookie>=abc123;user_agent=Mozilla/5.0...

Phản hồi lỗi

ERROR_CODE

Mẫu phân tích cú pháp

def parse_result(response_text):
    if response_text == "CAPCHA_NOT_READY":
        return {"status": "pending"}

    if response_text.startswith("OK|"):
        return {"status": "solved", "result": response_text.split("|", 1)[1]}

    return {"status": "error", "error": response_text}

Điểm cuối cân bằng

GET https://ocr.captchaai.com/res.php?key=API_KEY&action=getbalance

Phản hồi:

1.234

Số thập phân biểu thị số dư của bạn bằng USD.

balance = float(requests.get("https://ocr.captchaai.com/res.php", params={
    "key": API_KEY, "action": "getbalance"
}).text)
print(f"Balance: ${balance:.2f}")

Điểm cuối báo cáo

Báo cáo Tốt (giải đúng)

GET https://ocr.captchaai.com/res.php?key=API_KEY&action=reportgood&id=TASK_ID

Phản hồi: OK_REPORT_RECORDED

Báo cáo Xấu (giải quyết sai)

GET https://ocr.captchaai.com/res.php?key=API_KEY&action=reportbad&id=TASK_ID

Phản hồi: OK_REPORT_RECORDED

Báo cáo các giải pháp xấu giúp cải thiện độ chính xác và có thể ghi có vào số dư của bạn.

Mã lỗi phổ biến

Hoàn thành ví dụ bỏ phiếu

import requests
import time

API_KEY = "YOUR_API_KEY"

def solve_captcha(submit_params, timeout=300):
    """Generic solver with proper response handling."""
    submit_params["key"] = API_KEY

    # Submit
    resp = requests.get("https://ocr.captchaai.com/in.php", params=submit_params)
    if not resp.text.startswith("OK|"):
        raise Exception(f"Submit error: {resp.text}")

    task_id = resp.text.split("|")[1]

    # Poll
    deadline = time.time() + timeout
    while time.time() < deadline:
        time.sleep(5)
        result = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": API_KEY,
            "action": "get",
            "id": task_id
        })

        parsed = parse_result(result.text)

        if parsed["status"] == "pending":
            continue
        elif parsed["status"] == "solved":
            return parsed["result"]
        else:
            raise Exception(f"Solve error: {parsed['error']}")

    raise TimeoutError(f"Task {task_id} timed out after {timeout}s")

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

Tại sao phản hồi sử dụng dấu phân cách dạng ống (|) thay vì JSON?

Định dạng của CaptchaAI được tối ưu hóa để đơn giản. Các phản hồi được phân tách bằng dấu gạch ngang nhỏ hơn và phân tích cú pháp nhanh hơn JSON. Đối với dữ liệu có cấu trúc (kết quả GeeTest), dữ liệu sau OK| chứa các cặp khóa-giá trị.

Làm cách nào để xử lý lỗi mạng?

Gói lệnh gọi API trong try/except và thử lại trên ConnectionError hoặc Timeout. Sự cố mạng tách biệt với lỗi API; bản thân API duy trì hơn 99,9% thời gian hoạt động.

Độ dài mã thông báo tối đa là bao nhiêu?

Mã thông báo reCAPTCHA có thể có tối đa ~500 ký tự. Luôn sử dụng split("|", 1) (chia tối đa 1) để tránh tự chia mã thông báo.

Hướng dẫn liên quan

• Thiết lập và xác thực khóa API
• Gọi lại và bỏ phiếu
• Tham khảo mã lỗi CaptchaAI