Chuyển đến nội dung

Tài liệu API

Ba endpoint, ví dụ code đầy đủ bằng sáu ngôn ngữ. Tích hợp trong chưa đầy 60 giây với cụm solver hiệu năng cao của Capzy.

Bắt đầu nhanh

bước 1
POST /createTask

Gửi loại captcha + tham số trang web. Nhận lại taskId ngay lập tức.

bước 2
POST /getTaskResult

Poll khoảng mỗi 1 giây cho đến khi trạng thái là ready. Token nằm trong đối tượng solution.

bước 3
POST /getBalance

Kiểm tra tín dụng còn lại. Lượt giải thất bại được tự động hoàn tiền tại đây.

base urlhttps://api.capzy.aixác thực qua clientKey trong body của request

Endpoint

POST/createTaskTạo tác vụ giải captcha mới
request
{
  "clientKey": "capzy_...",
  "task": {
    "type": "AntiTurnstileTaskProxyLess",
    "websiteURL": "https://example.com",
    "websiteKey": "0x4AAA..."
  }
}
response
{
  "errorId": 0,
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "status": "processing"
}
POST/getTaskResultPoll kết quả tác vụ
request
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
response
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "0.eyJhbGci..."
  }
}
POST/getBalanceKiểm tra số dư tài khoản
request
{ "clientKey": "capzy_..." }
response
{ "errorId": 0, "balance": 9.50 }
POST/reportScoreKhông bắt buộc: gửi lại điểm đã xác minh của Google cho các tác vụ V3. Dùng cho chế độ xem chất lượng V3 trên bảng điều khiển. Một báo cáo cho mỗi tác vụ; báo cáo phải đến trong vòng 24 giờ sau khi giải xong.
request
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "score": 0.9,
  "action": "login",
  "hostname": "example.com"
}
response
{ "errorId": 0 }
POST/reportCorrectCaptchaKhông bắt buộc: cho chúng tôi biết lượt giải đã được trang mục tiêu CHẤP NHẬN. Đặc biệt hữu ích với các loại trả về tọa độ (ví dụ slider Shopee), khi chúng tôi trả về vị trí và trình duyệt của bạn thực hiện thao tác kéo. Báo cáo này là tín hiệu độ chính xác thực tế duy nhất của chúng tôi. Một báo cáo cho mỗi tác vụ, trong vòng 24 giờ; không bao giờ ảnh hưởng đến giá.
request
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
response
{ "errorId": 0 }
POST/reportIncorrectCaptchaKhông bắt buộc: cho chúng tôi biết lượt giải đã bị trang mục tiêu TỪ CHỐI. Dùng cho cùng hệ thống theo dõi độ chính xác thực tế như /reportCorrectCaptcha. Một báo cáo cho mỗi tác vụ, trong vòng 24 giờ; không bao giờ ảnh hưởng đến giá.
request
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
response
{ "errorId": 0 }

Các loại tác vụ được hỗ trợ

Đang tải…

Danh sách trực tiếp các loại tác vụ đang được bật, nhóm theo nhà cung cấp captcha. Giá và thời gian giải trung bình tự động cập nhật từ dữ liệu đo của cụm.

Đang tải loại tác vụ…

Rate limit

Giới hạn được áp dụng theo tài khoản, cộng dồn trên tất cả API key bạn sở hữu. Vượt giới hạn sẽ trả về mã lỗi mà không tiêu tốn tín dụng.

Mặc định
30 đồng thời · 30 req/giây

Mọi tài khoản mới đều bắt đầu ở đây

Đồng thời cao hơn
300+ đồng thời · 100+ req/giây

Mở ticket hỗ trợ kèm khối lượng dự kiến (không có bậc giá riêng, cùng đơn giá mỗi lượt giải)

tác vụ đồng thời

Số tác vụ bạn có thể có trong hàng đợi giải cùng lúc. Một tác vụ được tính vào giới hạn từ lúc createTask cho đến khi kết thúc (thành công, thất bại hoặc timeout).

rate limit

Số lệnh gọi createTask bạn có thể thực hiện mỗi giây. Cửa sổ trượt, áp dụng theo tài khoản. Vượt giới hạn sẽ trả về ERROR_RATE_LIMITED và không trừ tín dụng.

Mã lỗi

Mọi lỗi do /createTask / /getTaskResult trả về kèm cách khắc phục. Lượt giải thất bại được tự động hoàn tiền: tín dụng được trả lại số dư của bạn ngay lập tức.

Xác thực

Vấn đề với API key hoặc IP của bạn.
  • ERROR_KEY_DOES_NOT_EXIST

    API key của bạn không được nhận diện.

    cách khắc phụcKiểm tra lại giá trị trong Bảng điều khiển → API Key. Key bắt đầu bằng `capzy_`. Key đã xoay vòng bị vô hiệu hóa ngay lập tức.

    #
  • ERROR_IP_NOT_ALLOWED

    IP gửi request của bạn không nằm trong danh sách cho phép của API key.

    cách khắc phụcThêm IP của bạn vào danh sách cho phép của key trong Bảng điều khiển → API Key, hoặc xóa hoàn toàn danh sách cho phép nếu bạn không cần ghim IP.

    #
  • ERROR_IP_BLOCKED

    IP của bạn tạm thời bị chặn do gửi quá nhiều request không hợp lệ.

    cách khắc phụcChúng tôi chặn các IP gửi hơn 100 request không hợp lệ trong 10 phút (tăng dần). Hãy sửa lỗi gây ra request không hợp lệ, sau đó chờ. Lệnh chặn tự hết hạn sau 1 phút đến 24 giờ tùy theo cấp.

    #

Kiểm tra hợp lệ

Tham số tác vụ sai hoặc sai loại cho sitekey.
  • ERROR_INVALID_PARAMS

    Body của request bị sai định dạng hoặc thiếu trường bắt buộc.

    cách khắc phụcKiểm tra rằng `clientKey` nằm ở cấp cao nhất và `task` chứa `type` cùng định danh bắt buộc (websiteURL/websiteKey/captchaId/v.v.). Xem phần Loại tác vụ để biết các tham số bắt buộc theo từng loại.

    #
  • ERROR_BAD_SITEKEY

    `websiteKey` không được đăng ký với bất kỳ nhà cung cấp captcha nào mà chúng tôi nhận diện được.

    cách khắc phụcHãy chắc chắn rằng bạn sao chép đầy đủ sitekey từ trang mục tiêu (tìm `data-sitekey`, `sitekey:`, hoặc tham số trong `grecaptcha.render` / `hcaptcha.render`).

    #
  • ERROR_TASK_NOT_SUPPORTED

    `type` tác vụ bạn gửi không phải là loại captcha mà Capzy hiện hỗ trợ.

    cách khắc phụcXem phần Loại tác vụ bên dưới để biết danh sách đầy đủ đang được bật. Nếu bạn cần một captcha không có trong danh sách, hãy mở ticket và chúng tôi sẽ ưu tiên xử lý.

    #
  • ERROR_WRONG_TASK_TYPE

    Loại tác vụ không khớp với nhà cung cấp thực tế của sitekey.

    cách khắc phụcChúng tôi kiểm tra trước sitekey với nhà cung cấp thực tế. Phản hồi lỗi có trường `recommended`: hãy chuyển sang loại tác vụ đó. (Không tính phí.)

    #
  • ERROR_PROXY_REQUIRED

    Captcha này gắn với IP: token của nó gắn với IP đã giải.

    cách khắc phụcChuyển sang biến thể `*Task` (thay vì `*TaskProxyLess`) và truyền `proxyAddress` khớp với IP bạn sẽ dùng để gửi token. Áp dụng cho: Cloudflare Challenge, CaptchaFox, AWS WAF, DataDome, PerimeterX, Kasada, Akamai, Imperva.

    #
  • ERROR_NO_PROXY

    Loại tác vụ này bắt buộc các trường proxy nhưng chúng bị thiếu.

    cách khắc phụcThêm `proxyType`, `proxyAddress`, `proxyPort` (và tùy chọn `proxyLogin`/`proxyPassword`/`userAgent`) vào body tác vụ.

    #
  • ERROR_PROXY_CONNECT_REFUSED

    Proxy bạn cung cấp đã từ chối kết nối.

    cách khắc phụcKiểm tra thông tin xác thực proxy, khả năng kết nối tới host, và IP còn hoạt động. Hãy thử cùng proxy đó từ máy của bạn trước để khoanh vùng vấn đề của nhà cung cấp.

    #

Rate limit

Giới hạn đồng thời / mỗi giây / tỷ lệ hoàn tiền.
  • ERROR_MAX_TASKS_REACHED

    Bạn đã đạt giới hạn tác vụ đồng thời cho cấp tài khoản của mình.

    cách khắc phụcChờ các tác vụ đang chạy hoàn tất trước khi gửi thêm. Cấp Regular mặc định là 30 tác vụ đồng thời; liên hệ bộ phận hỗ trợ để nâng cấp.

    #
  • ERROR_RATE_LIMITED

    Bạn đang gửi /createTask nhanh hơn rate limit cho phép.

    cách khắc phụcGiảm tốc độ và thử lại. Cấp Regular mặc định là 30 req/giây theo cửa sổ trượt. Vượt rate limit không tiêu tốn tín dụng.

    #
  • ERROR_NO_SLOT_AVAILABLE

    Năng lực của cụm tạm thời bị quá tải.

    cách khắc phụcThử lại sau vài giây (đây là lỗi tạm thời). Nếu kéo dài nhiều phút, hãy kiểm tra status.capzy.ai.

    #
  • ERROR_SYSTEM_MAINTENANCE

    Capzy đang bảo trì theo lịch.

    cách khắc phụcThử lại sau thời gian bảo trì. Chúng tôi đăng thông báo trước trên trang trạng thái.

    #

Kết quả giải

Những gì solver trả về. Lượt giải thất bại được tự động hoàn tiền.
  • ERROR_TIMEOUT

    Tác vụ không hoàn tất trong giới hạn thời gian của loại tác vụ.

    cách khắc phụcĐã tự động hoàn tiền, không tính phí. Hầu hết các lỗi timeout là tạm thời. Nếu một captcha cụ thể liên tục timeout, hãy mở ticket kèm UUID của tác vụ.

    #
  • ERROR_CAPTCHA_UNSOLVABLE

    Solver đã dùng hết số lần thử lại cho challenge này.

    cách khắc phụcĐã tự động hoàn tiền, không tính phí. Nguyên nhân thường gặp: sitekey đã cũ, websiteURL không khớp với tên miền nhúng, hoặc trang mục tiêu đã tắt captcha.

    #
  • ERROR_NULL_RESULT

    Solver đã hoàn tất nhưng không trả về token.

    cách khắc phụcĐã tự động hoàn tiền. Thường cho thấy trang mục tiêu đã gỡ captcha trong lúc đang giải. Hãy thử lại; nếu vẫn tiếp diễn, hãy mở ticket.

    #
  • ERROR_INTERNAL

    Lỗi không mong muốn trong pipeline giải.

    cách khắc phụcĐã tự động hoàn tiền. Hãy thử lại (lỗi này hiếm gặp). Nếu bạn thấy lỗi lặp lại liên tục, hãy mở ticket kèm UUID của tác vụ.

    #
  • ERROR_ZERO_BALANCE

    Số dư tài khoản quá thấp để trả chi phí tác vụ.

    cách khắc phụcNạp tín dụng trong Bảng điều khiển → Thanh toán. Lượt giải thất bại được tự động hoàn tiền nên bạn chỉ trả tiền cho token thành công.

    #

Báo cáo điểm

Lỗi riêng của /reportScore (phản hồi chất lượng V3).
  • ERROR_TASK_NOT_FOUND

    /reportScore: taskId không thuộc tài khoản của bạn hoặc đã bị xóa.

    cách khắc phụcBáo cáo điểm phải tham chiếu đến tác vụ thuộc về bạn và phải được gửi trong vòng 24 giờ sau khi giải xong.

    #
  • ERROR_TASK_NOT_READY

    /reportScore: tác vụ vẫn đang xử lý hoặc đã thất bại.

    cách khắc phụcChỉ tác vụ ở trạng thái `ready` mới được chấm điểm. Hãy chờ /getTaskResult trả về ready trước khi báo cáo.

    #
  • ERROR_REPORT_TOO_LATE

    /reportScore: đã quá 24 giờ kể từ khi giải xong.

    cách khắc phụcHãy báo cáo điểm trong vài phút sau lệnh gọi siteverify. Đó là lúc dữ liệu hữu ích nhất cho bảng điều khiển chất lượng V3 của chúng tôi.

    #
06

Code Playground

Ví dụ hoạt động hoàn chỉnh bằng mọi ngôn ngữ phổ biến. Sao chép, dán API key, chạy.

solve.py
import requests, time

API = "https://api.capzy.ai"
KEY = "capzy_your_key_here"

# Create task
task = requests.post(f"{API}/createTask", json={
    "clientKey": KEY,
    "task": {
        "type": "AntiTurnstileTaskProxyLess",
        "websiteURL": "https://example.com",
        "websiteKey": "0x4AAA..."
    }
}).json()

task_id = task["taskId"]

# Poll for result
while True:
    result = requests.post(f"{API}/getTaskResult", json={
        "clientKey": KEY,
        "taskId": task_id
    }).json()

    if result["status"] == "ready":
        token = result["solution"]["token"]
        print(f"Solved: {token[:50]}...")
        break
    elif result["status"] == "failed":
        print(f"Failed: {result.get('errorDescription')}")
        break

    time.sleep(1)
Xem trước đầu raThành công (200 OK)
{ "errorId": 0, "status": "ready", "solution": { "token": "0.eyJhbGci..." } }

Tích hợp trong chưa đầy 60 giây.

Tặng $0.10 tín dụng miễn phí khi đăng ký. Không cần thẻ tín dụng.

Nhận API key miễn phí →