SDK cốt lõi

Động cơ của toàn bộ hệ sinh thái. capsolver-core sử dụng Python thuần túy để phát hiện CAPTCHA trên một trang, đọc các tham số của chúng, giải quyết chúng thông qua dịch vụ CapSolver AI và điền lại mã thông báo. Các gói capsolver-agent và capsolver-mcp cấp cao hơn đều được xây dựng dựa trên nó.

Chỉ chế độ mã thông báo. SDK này giải quyết bằng cách yêu cầu mã thông báo từ API CapSolver (reCAPTCHA v2/v3, Cloudflare Turnstile). Nó không nhấp vào lưới hình ảnh hoặc kéo thanh trượt trên trang.

1. Tổng quan

capsolver-core chia việc “giải CAPTCHA” thành bốn giai đoạn rõ ràng, được xâu chuỗi thành một quy trình duy nhất:

1. Phát hiện ( detect ) — xác định loại CAPTCHA nào có trên trang.
2. Đọc tham số ( get_captcha_info ) — đọc tham số có cấu trúc của từng CAPTCHA (loại, khóa trang web, URL, v.v.) ngay từ trang trực tiếp.
3. Giải ( solve ) — giao các tham số cho dịch vụ AI của CapSolver và nhận lại mã thông báo có thể sử dụng được.
4. Điền lại ( solve_on_page ) — ghi lại mã thông báo vào DOM của trang để trang web coi việc xác minh là đã được thông qua.

Xung quanh đường ống này, nó bổ sung thêm một số tiện ích kỹ thuật:

• ✅ API hoàn toàn không đồng bộ — được xây dựng trên async / await , do đó bạn có thể chạy nhiều lượt giải cùng lúc.
• ✅ Sử dụng lại và dọn dẹp kết nối — duy trì nhóm kết nối HTTP nội bộ và hoạt động như một trình quản lý bối cảnh không đồng bộ.
• ✅ Đăng ký trình xử lý có thể cắm — mỗi loại CAPTCHA được xử lý bởi một trình xử lý mà bạn có thể tùy chỉnh hoặc ghi đè.
• ✅ Hai cấp độ chi tiết — chuyển sang API thuần túy khi đã biết các tham số; sử dụng chế độ Trình duyệt Playwright khi tất cả những gì bạn có chỉ là trang đó.

Khi nào bạn nên sử dụng trực tiếp core? Khi bạn tự mình kiểm soát mã và không cần chuyển sang giải pháp LLM.

2. Cài đặt

capsolver-core là mã 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 nó qua git:

pip install git+https://github.com/capsolver-ai/capsolver-core.git
 
# With Playwright support (for detect / solve_on_page)
pip install "capsolver-core[playwright] @ git+https://github.com/capsolver-ai/capsolver-core.git"
playwright install chromium

Đặt chìa khóa của bạn:

export CAPSOLVER_API_KEY="your-capsolver-api-key"

Lưu ý: SDK hoạt động mà không cần thêm [playwright] — trong trường hợp đó chỉ có chế độ Mã thông báo ( solve ) khả dụng và các phương thức phụ thuộc vào trình duyệt detect / get_captcha_info / solve_on_page không khả dụng vì thiếu Playwright.

3. API & Hai chế độ

3.1 Tạo khách hàng

create_capsolver(**options) (hoặc Capsolver(**options) ) trả về một khách hàng.

Capsolver chứa nhóm kết nối HTTP nội bộ, vì vậy, nó được sử dụng tốt nhất làm trình quản lý bối cảnh không đồng bộ để đảm bảo các kết nối được giải phóng:

async with create_capsolver(api_key="YOUR_API_KEY") as cap:
    solution = await cap.solve(info)
# or call await cap.aclose() explicitly when you're done

3.2 Sơ lược về các phương pháp

3.3 Giải Đầu vào: CaptchaInfo

Đầu vào cốt lõi của solve() là CaptchaInfo . type , website_url và website_key là bắt buộc (website_url hoặc website_key trống tăng ValueError ); phần còn lại là tùy chọn tùy thuộc vào loại CAPTCHA:

Các tùy chọn cho solve_on_page() được điều khiển bởi SolveOnPageOptions :

wait_options cho solve() ( WaitOptions ) chỉ có hai trường tùy chọn timeout và polling_interval , được sử dụng để ghi đè các giá trị mặc định chung của máy khách cho một lần giải quyết.

3.4 Kiểu trả về

detect() trả về list[CaptchaType] và get_captcha_info() trả về list[CaptchaInfo] .

3.5 Cách mỗi chế độ sử dụng các API này

Sự khác biệt duy nhất giữa hai chế độ là nguồn gốc của các tham số — đó là lý do tại sao chúng gọi các API khác nhau:

Chế độ mã thông báo (bạn đã biết khóa trang web) — chỉ sử dụng solve() . Bạn tự xây dựng CaptchaInfo và nhận lại mã thông báo:

info = CaptchaInfo(type=CaptchaType.RECAPTCHA_V2, website_url=..., website_key=...)
solution = await cap.solve(info)

Chế độ trình duyệt (điều khiển trang bằng Playwright) — sử dụng detect() / get_captcha_info() / solve_on_page() . solve_on_page() tất cả trong một bao gồm việc phát hiện, giải quyết và điền lại; hoặc bạn có thể chạy các bước riêng biệt để tự mình kiểm soát từng giai đoạn:

results = await cap.solve_on_page(page)              # all in one call
# or step by step:
types = await cap.detect(page)
infos = await cap.get_captcha_info(page)
solution = await cap.solve(infos[0])

4. Gọi từng API: Yêu cầu & Phản hồi

Phần này sẽ trình bày từng phương thức riêng lẻ — lệnh gọi thực, các tham số cần truyền, phản hồi mẫu và giải thích về các trường phản hồi.

4.1 solve — Giải (Chế độ mã thông báo)

Ví dụ về cuộc gọi và phản hồi:

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,        # required: CAPTCHA type
        website_url="https://example.com",    # required: page URL
        website_key="6Lc...",                 # required: site public key (data-sitekey)
        # v3 also takes page_action / min_score; Enterprise takes enterprise/s; Cloudflare takes cdata
    )
    solution = await cap.solve(info)
    print(solution.token)
 
asyncio.run(main())

Câu trả lời mẫu ( Solution ):

Solution(
  token="03AFcWeA6f...",                  # the credential to submit to the target site
  captcha_type=CaptchaType.RECAPTCHA_V2,
  expire_time=120,
  user_agent="Mozilla/5.0 ...",
  raw=TokenSolution(...),
)

Trường phản hồi:

• token — mã thông báo đã được giải quyết; gửi nó dưới dạng g-recaptcha-response cho reCAPTCHA hoặc cf-turnstile-response cho Turnstile.
• captcha_type — loại CAPTCHA đã được giải quyết.
• expire_time — mã thông báo hết hạn sau vài giây; chỉ xuất hiện khi dịch vụ trả về nó, nếu không thì None .
• user_agent — UA dùng để giải; chỉ xuất hiện khi dịch vụ trả về nó, nếu không thì None .
• raw — thô TokenSolution , chứa g_recaptcha_response / token / user_agent / expire_time .

4.2 solve_on_page — Phát hiện toàn bộ trang + giải quyết + điền lại (Chế độ trình duyệt)

Cuộc gọi và tham số: đầu vào là Nhà viết kịch page , với SolveOnPageOptions tùy chọn.

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)   # or pass options=SolveOnPageOptions(...)
        for r in results:
            print(r.info.type, r.solution.token if r.solution else None, r.filled, r.error)
 
asyncio.run(main())

Câu trả lời mẫu ( list[SolveOnPageResult] ):

[
  SolveOnPageResult(
      info=CaptchaInfo(type=CaptchaType.RECAPTCHA_V2, website_url=..., website_key=...),
      solution=Solution(token="03AF...", captcha_type=CaptchaType.RECAPTCHA_V2),
      filled=True,
      error=None,
  ),
]

Trường phản hồi (mỗi mục):

• info — CaptchaInfo cho CAPTCHA đó (loại và tham số).
• solution — cái Solution ; None khi thất bại.
• filled — liệu mã thông báo đã được điền lại thành công vào trang hay chưa.
• error — chuỗi lý do lỗi; None thành công.

4.3 detect — Phát hiện CAPTCHA nào có trên trang

Cuộc gọi và tham số: đầu vào là Nhà viết kịch page .

types = await cap.detect(page)

Phản hồi / trường mẫu ( list[CaptchaType] ):

[<CaptchaType.RECAPTCHA_V2: 'reCaptchaV2'>]

Trả về danh sách các enum loại CAPTCHA được phát hiện trên trang; một danh sách trống có nghĩa là không có gì được tìm thấy.

4.4 get_captcha_info — Đọc tham số có cấu trúc

Cuộc gọi và tham số: đầu vào là Nhà viết kịch page .

infos = await cap.get_captcha_info(page)
for info in infos:
    print(info.type, info.website_url, info.website_key)
solution = await cap.solve(infos[0])     # once read, can be solved directly

Phản hồi / trường mẫu ( list[CaptchaInfo] ):

# [CaptchaInfo(type=CaptchaType.RECAPTCHA_V2,
#              website_url="https://example.com",
#              website_key="6Lc...")]

4.5 get_balance — Kiểm tra số dư

Cuộc gọi và tham số: không có đầu vào.

balance = await cap.get_balance()
print(balance.balance, balance.packages)

Phản hồi / trường mẫu ( BalanceResp ):

BalanceResp(balance=12.34, packages=[])

• balance — số dư tài khoản (thả nổi).
• packages — danh sách các gói/gói đăng ký; một danh sách trống nếu không có.

4.6 get_supported_captchas / get_handler — Quyền truy cập sổ đăng ký

Gọi và trả lời:

cap.get_supported_captchas()      # → ['reCaptchaV2', 'reCaptchaV3', 'cloudflare']

• get_supported_captchas() — trả về danh sách các chuỗi loại hiện được hỗ trợ.