Giới thiệu & Bắt đầu nhanh

1. Giới thiệu SDK CapSolver Python

SDK được cung cấp dưới dạng ba gói độc lập — mỗi gói có thể tự cài đặt thông qua pip install — cùng với kho lưu trữ ví dụ đi kèm. Chúng cùng nhau đưa bạn đi từ “có CAPTCHA trên trang” đến “Tôi có mã thông báo hợp lệ” chỉ trong vài dòng Python — cho dù bạn đang viết một tập lệnh dùng một lần, điều khiển một trình duyệt thực sự với Playwright hay khả năng giải quyết vấn đề nối dây thành một tác nhân AI tự trị.

Nó được hỗ trợ bởi dịch vụ giải quyết AI của CapSolver. SDK xử lý mọi thứ về phía bạn — phát hiện CAPTCHA, tập hợp các tham số, gọi dịch vụ và điền lại kết quả — trong khi quá trình nhận dạng và giải quyết thực tế diễn ra trên đám mây. Ý tưởng cốt lõi nằm ở một câu duy nhất: mã của bạn (hoặc mô hình của bạn) quyết định what cần làm và CapSolver xử lý giải quyết nó.

1.1 Tính năng cốt lõi

✅ Giải quyết mã thông báo được hỗ trợ bởi AI — CapSolver trả về mã thông báo mà bạn gửi đến trang web mục tiêu.
✅ Hai chế độ sử dụng — API thuần túy (Chế độ mã thông báo, dành cho các khóa trang web đã biết, không cần trình duyệt) và chế độ Trình duyệt dựa trên Playwright.
✅ Phạm vi bao gồm các CAPTCHA chính — reCAPTCHA v2 / v3 (bao gồm Enterprise) và Cloudflare Turnstile.
✅ API hoàn toàn không đồng bộ — được xây dựng trên async / await, một sự phù hợp tự nhiên cho các trình thu thập thông tin và tác nhân hiện đại.
✅ Gói ba lớp — từ công cụ cấp thấp đến công cụ đại lý đến dịch vụ MCP; chọn những gì bạn cần (xem 1.2).
✅ CLI đi kèm — capsolver , capsolver-agent và capsolver-mcp cho phép bạn chạy chẩn đoán mà không cần viết bất kỳ mã nào.

1.2 CAPTCHA và thông số được hỗ trợ

SDK hiện giải quyết các loại CAPTCHA sau:

Loại	Enum ( `CaptchaType` )	Giá trị dụng cụ ( `captcha_type` )	Ghi chú
reCAPTCHA v2	`RECAPTCHA_V2`	`reCaptchaV2`	Bao gồm vô hình
reCAPTCHA v3	`RECAPTCHA_V3`	`reCaptchaV3`	Bao gồm Doanh nghiệp
Cửa quay Cloudflare	(đám mây)	`cloudflare`	Tiện ích cửa quay

Các tham số cốt lõi mà mọi loại yêu cầu là website_url + website_key . reCAPTCHA v3 cũng có thể nhận page_action , min_score và gợi ý enterprise, trong khi Cloudflare có thể nhận cdata . Bạn có thể kiểm tra các loại được bản dựng hiện tại của bạn hỗ trợ bất kỳ lúc nào:

cap = create_capsolver(api_key="YOUR_API_KEY")
print(cap.get_supported_captchas())

Lưu ý: Trong chế độ Trình duyệt, bạn không cần phải cung cấp các tham số này bằng tay — get_captcha_info(page) đọc loại và khóa trang web trực tiếp trên trang trực tiếp cho bạn.

2. Khả năng cốt lõi (SDK)

2.1 Ba Gói

Bộ tính năng đầy đủ cộng với một kho lưu trữ ví dụ. Đây không phải là ba ứng dụng ngang hàng để lựa chọn — hai ứng dụng sau đều được xây dựng dựa trên capsolver-core , chỉ đơn giản là cung cấp khả năng giải quyết tương tự thông qua một giao diện khác. Chọn một trong những phù hợp nhất với cách bạn làm việc.

** capsolver-core — SDK lõi (Công cụ)**

Gói cấp thấp nhất và hai công cụ dùng chung còn lại phụ thuộc vào. Nó chia việc giải CAPTCHA thành bốn bước — phát hiện → đọc tham số → giải quyết → điền lại — và cung cấp hai cấp độ chi tiết: khi biết khóa trang web, hãy chuyển sang API thuần túy (Chế độ mã thông báo, không có trình duyệt); khi bạn chỉ có trang đó, hãy để Playwright tự động phát hiện và điền lại kết quả. Hoàn toàn không đồng bộ, với sổ đăng ký trình xử lý có thể cắm được.

Tốt nhất cho: tập lệnh, trình thu thập thông tin và tự động hóa nơi bạn kiểm soát mã và không cần LLM.
Điểm vào: create_capsolver() → solve() / solve_on_page() .
Cài đặt: pip install capsolver-core (thêm [playwright] cho chế độ Trình duyệt).

** capsolver-agent — Công cụ đại lý**

Bao bọc phần lõi dưới dạng các công cụ mà LLM có thể gọi: nó cung cấp các lược đồ công cụ không xác định khung cộng với trình thực thi không đồng bộ, cũng như các triển khai LangChain BaseTool được tạo sẵn. Trong vòng lặp của nó, mô hình gọi “giải quyết” giống như cách nó gọi “nhấp chuột” hoặc “gõ” và người thực thi sẽ chuyển tiếp lệnh gọi đến các phương thức của lõi và trả về kết quả có cấu trúc.

Tốt nhất cho: để mô hình quyết định thời điểm giải quyết — Gọi hàm OpenAI, SDK đại lý OpenAI, LangChain, Sử dụng trình duyệt hoặc bất kỳ vòng lặp tác nhân tùy chỉnh nào.
Điểm vào: get_all_tools() + create_executor() , hoặc get_langchain_tools() .
Cài đặt: pip install capsolver-agent (thêm [langchain] cho LangChain).

** capsolver-mcp — Dịch vụ MCP**

Cung cấp cùng một bộ công cụ như một dịch vụ tiêu chuẩn thông qua Giao thức bối cảnh mô hình. Mọi máy khách tương thích với MCP đều tự động phát hiện ra các công cụ này khi kết nối — không yêu cầu mã bộ điều hợp cho mỗi máy khách. Hỗ trợ ba phương thức vận chuyển: stdio, SSE và streamingable-http.

Tốt nhất cho: sử dụng plug-and-play bên trong ứng dụng khách AI — Claude Desktop, Claude Code, Cursor, Windsurf, Cline, v.v., với mã tích hợp gần như bằng không.
Điểm vào: lệnh capsolver-mcp hoặc create_server() .
Cài đặt: pip install capsolver-mcp (thêm [browser] cho các công cụ của trình duyệt).

Kho lưu trữ	Trọn gói	Vai trò một dòng
lõi capsolver	`capsolver-core`	SDK lõi - phát hiện CAPTCHA, gọi API để giải quyết, điền lại mã thông báo
đại lý-capsolver	`capsolver-agent`	Công cụ tác nhân - lược đồ công cụ không xác định khung + công cụ LangChain
mcp-capsolver	`capsolver-mcp`	Dịch vụ MCP - hiển thị các công cụ giải quyết thông qua Giao thức bối cảnh mô hình

2.2 Các trường hợp sử dụng

Bất cứ khi nào CAPTCHA chặn bước tiếp theo, SDK này sẽ giành được vị trí của nó. Một vài tình huống điển hình:

** Quét web / thu thập dữ liệu **

Trình thu thập thông tin truy cập reCAPTCHA hoặc Turnstile trên trang danh sách, trang tìm kiếm hoặc tường đăng nhập và toàn bộ quy trình thu thập bị đình trệ. Sử dụng chế độ Mã thông báo để nhận mã thông báo và gửi mã thông báo đó cùng với yêu cầu của bạn hoặc sử dụng chế độ Trình duyệt để điền mã thông báo trực tiếp vào trang — dù bằng cách nào, việc thu thập dữ liệu vẫn tiếp tục. → Khuyến nghị: capsolver-core (Chế độ mã thông báo khi biết khóa trang web; solve_on_page cho các trang động).

Tự động hóa tài khoản và quy trình làm việc

Các quy trình gồm nhiều bước như đăng ký, đăng nhập, đặt lại mật khẩu và thanh toán thường đưa ra CAPTCHA ở một bước cụ thể, làm đóng băng toàn bộ tập lệnh. Đưa việc giải quyết vào chính xác bước đó — sau khi điền mã thông báo, tập lệnh sẽ tiếp tục gửi biểu mẫu, chờ chuyển hướng và chạy các bước còn lại để hoàn thành. → Khuyến nghị: capsolver-core Chế độ trình duyệt; đặc biệt mượt mà khi kịch bản của bạn đã thúc đẩy Nhà viết kịch.

Đại lý AI (duyệt tự động)

Giao cho nhân viên một nhiệm vụ như “đăng nhập và lấy đơn đặt hàng” và nhân viên sẽ nhận được CAPTCHA ở đâu đó trong quá trình thực hiện mà không cần cảnh báo. Thay vì để mô hình nhấp chuột qua chính nó — nhắm mục tiêu pixel hoàn hảo và đường dẫn con trỏ giống con người khó có thể giả mạo các công cụ gây rủi ro trong quá khứ và các vòng lặp thử lại hình ảnh tràn ngập cửa sổ ngữ cảnh — hãy đăng ký một hành động “giải quyết” cho mô hình đó: khi nó chạm vào CAPTCHA, nó sẽ gọi hành động đó, lấy lại mã thông báo và tiếp tục trong cùng một phiên trình duyệt mà không làm gián đoạn luồng. → Khuyến nghị: capsolver-agent (để mô hình tự gọi nó) hoặc capsolver-mcp (sử dụng trực tiếp bên trong ứng dụng khách AI).

Kiểm tra tự động/công cụ nội bộ

Các thử nghiệm toàn diện và các công cụ vận hành nội bộ cần xóa các bước CAPTCHA trên trang web của riêng bạn hoặc bên thứ ba một cách đáng tin cậy mà không cần can thiệp thủ công làm chậm mọi thứ. → Khuyến nghị: chọn theo môi trường — capsolver-core (trong mã) hoặc capsolver-mcp (trong ứng dụng khách).

Tóm lại: bất cứ nơi nào bạn cần xóa CAPTCHA theo chương trình bằng Python, SDK này đều nằm trong phạm vi đáp ứng.

3. Cài đặt & Thiết lập khóa API

Trước khi bạn bắt đầu, hãy ghi nhớ một điều: việc giải quyết thực tế diễn ra trên dịch vụ đám mây của CapSolver — SDK chỉ gọi nó từ phía bạn. Vì vậy, bước đầu tiên không phải là cài đặt một gói; nó có một tài khoản và khóa API. Quá trình thiết lập gồm ba bước theo thứ tự: đăng ký và nhận khóa → cài đặt SDK → kết nối khóa.

3.1 Đăng ký và nhận khóa API của bạn

Đăng ký tài khoản tại trang web CapSolver.
Mở trang tổng quan và sao chép khóa API của bạn.
Thêm tiền vào tài khoản của bạn — mỗi lần giải thành công đều tiêu tốn số dư và việc giải quyết sẽ thất bại khi số dư về 0.

3.2 Cài đặt SDK

Ba gói hiện được lưu trữ dưới dạng nguồn mở trên GitHub và chưa được xuất bản lên PyPI, vì vậy hãy cài đặt chúng qua git. capsolver-core là động cơ và cả capsolver-agent và capsolver-mcp đều phụ thuộc vào nó — vì vậy lõi luôn được yêu cầu. Thêm bất kỳ lớp trên nào bạn định sử dụng:

# Engine (required; both other packages depend on it)
pip install git+https://github.com/capsolver-ai/capsolver-core.git
 
# Optional: MCP service — exposes the tools to MCP clients
pip install git+https://github.com/capsolver-ai/capsolver-mcp.git
 
# Optional: Agent tools — LLM-callable tool definitions + LangChain tools
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

Đối với Chế độ trình duyệt (phát hiện CAPTCHA trên trang thực và điền lại mã thông báo), hãy thêm [playwright] bổ sung và cài đặt Chrome:

pip install "capsolver-core[playwright] @ git+https://github.com/capsolver-ai/capsolver-core.git"
playwright install chromium

Lưu ý: detect và solve_on_page yêu cầu bổ sung trình duyệt; Chế độ mã thông báo hoàn toàn không cần trình duyệt.

Ba kho lưu trữ là:

Trọn gói	Kho lưu trữ GitHub
`capsolver-core`	https://github.com/capsolver-ai/capsolver-core
`capsolver-agent`	https://github.com/capsolver-ai/capsolver-agent
`capsolver-mcp`	https://github.com/capsolver-ai/capsolver-mcp

Bạn cũng có thể sao chép cục bộ một kho lưu trữ trước khi cài đặt — thuận tiện cho việc đọc nguồn hoặc thực hiện quá trình phát triển của riêng bạn:

git clone https://github.com/capsolver-ai/capsolver-core.git
cd capsolver-core
pip install .            # or: pip install -e .  for an editable install

3.3 Kết nối khóa API của bạn

Cuối cùng, giao key từ bước 3.1 cho SDK. Theo mặc định, tất cả các gói đều đọc nó từ biến môi trường CAPSOLVER_API_KEY:

# bash / zsh
export CAPSOLVER_API_KEY="your-capsolver-api-key"
 
# PowerShell
$env:CAPSOLVER_API_KEY = "your-capsolver-api-key"
 
# cmd
set CAPSOLVER_API_KEY=your-capsolver-api-key

Ngoài ra, hãy bỏ qua biến môi trường và chuyển trực tiếp api_key="..." tới create_capsolver() .

4. Giải bài đầu tiên của bạn

Với môi trường đã sẵn sàng, hãy chạy từ đầu đến cuối với mã nhỏ nhất có thể. Bạn đi theo đường dẫn nào tùy thuộc vào việc bạn đã biết khóa trang hay chưa: nếu biết, hãy sử dụng chế độ Mã thông báo; nếu tất cả những gì bạn có là một URL trang, hãy sử dụng chế độ Trình duyệt.

4.1 Token Mode (bạn đã biết site key)

Khi bạn biết loại CAPTCHA, URL trang và khóa trang web, không cần trình duyệt — hãy chuyển các tham số, nhận lại mã thông báo.

import asyncio
from capsolver_core import create_capsolver, CaptchaType, CaptchaInfo
 
async def main():
    cap = create_capsolver(api_key="YOUR_API_KEY")
 
    info = CaptchaInfo(
        type=CaptchaType.RECAPTCHA_V2,
        website_url="https://example.com",
        website_key="6Lc...",
    )
    solution = await cap.solve(info)
    print(solution.token)  # submit as g-recaptcha-response
 
asyncio.run(main())

4.2 Chế độ trình duyệt (một cuộc gọi, ngay trên trang trực tiếp)

Nếu tất cả những gì bạn có chỉ là một trang — và bạn không muốn tự mình tìm kiếm khóa trang web — hãy để SDK tự động phát hiện mọi CAPTCHA trên trang, giải từng cái một và điền lại mã thông báo vào DOM. Một cuộc gọi sẽ làm được tất cả.

import asyncio
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright
 
async def main():
    cap = create_capsolver(api_key="YOUR_API_KEY")
 
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page()
        await page.goto("https://example.com/login")
 
        results = await cap.solve_on_page(page)
        for r in results:
            print(r.info.type, r.solution.token if r.solution else None, r.filled, r.error)
 
asyncio.run(main())

CapSolver Đối với các đại lý AI Cốt lõi SDK