SDK Inti

Mesin seluruh ekosistem. capsolver-core menggunakan Python murni untuk mendeteksi CAPTCHA di halaman, membaca parameternya, menyelesaikannya melalui layanan CapSolver AI, dan mengisi kembali token. Paket capsolver-agent dan capsolver-mcp tingkat yang lebih tinggi keduanya dibuat di atasnya.

Hanya mode token. SDK ini menyelesaikan masalah dengan meminta token dari CapSolver API (reCAPTCHA v2/v3, Cloudflare Turnstile). Itu tidak mengklik kisi gambar atau menyeret penggeser pada halaman.

1. Ikhtisar

capsolver-core memecah “pemecahan CAPTCHA” menjadi empat tahap yang jelas, dirangkai menjadi satu saluran:

1. Deteksi ( detect ) — mengidentifikasi jenis CAPTCHA mana yang ada di laman.
2. Baca parameter ( get_captcha_info ) — membaca parameter terstruktur setiap CAPTCHA (jenis, kunci situs, URL, dan sebagainya) langsung dari laman aktif.
3. Solve ( solve ) — serahkan parameter ke layanan AI CapSolver dan dapatkan kembali token yang dapat digunakan.
4. Isi kembali ( solve_on_page ) — tulis kembali token ke halaman DOM sehingga situs menganggap verifikasi telah lulus.

Di sekitar jalur pipa ini, terdapat beberapa kemudahan teknik tambahan:

• ✅ API yang sepenuhnya asinkron — dibangun di atas async / await , sehingga Anda dapat menjalankan banyak penyelesaian secara bersamaan.
• ✅ Penggunaan kembali dan pembersihan koneksi — mengelola kumpulan koneksi HTTP internal dan berfungsi sebagai pengelola konteks asinkron.
• ✅ Registri penangan yang dapat dicolokkan — setiap jenis CAPTCHA ditangani oleh satu penangan, yang dapat Anda sesuaikan atau ganti.
• ✅ Dua tingkat perincian — gunakan API murni ketika parameternya diketahui; gunakan mode Playwright Browser ketika yang Anda miliki hanyalah halamannya.

Kapan sebaiknya Anda menggunakan core secara langsung? Saat Anda mengontrol kode sendiri dan tidak perlu memaparkan penyelesaian ke LLM.

2. Instalasi

capsolver-core adalah open source di GitHub dan belum dipublikasikan ke PyPI, jadi instal melalui 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

Tetapkan kunci Anda:

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

Catatan: SDK berfungsi tanpa tambahan [playwright] — dalam hal ini hanya mode Token ( solve ) yang tersedia, dan metode yang bergantung pada browser detect / get_captcha_info / solve_on_page tidak tersedia karena Playwright tidak ada.

3. API & Dua Mode

3.1 Buat Klien

create_capsolver(**options) (atau Capsolver(**options) ) mengembalikan klien.

Capsolver menyimpan kumpulan koneksi HTTP internal, jadi paling baik digunakan sebagai pengelola konteks asinkron untuk memastikan koneksi dilepaskan:

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 Sekilas Metode

3.3 Selesaikan Masukan: CaptchaInfo

Masukan inti ke solve() adalah CaptchaInfo . type , website_url , dan website_key diperlukan (kosong website_url atau website_key memunculkan ValueError ); sisanya opsional tergantung pada jenis CAPTCHA:

Opsi untuk solve_on_page() dikendalikan oleh SolveOnPageOptions :

wait_options untuk solve() ( WaitOptions ) hanya memiliki dua bidang opsional, timeout dan polling_interval , yang digunakan untuk mengganti default global klien untuk satu penyelesaian.

3.4 Tipe Pengembalian

detect() mengembalikan list[CaptchaType] , dan get_captcha_info() mengembalikan list[CaptchaInfo] .

3.5 Cara Setiap Mode Menggunakan API Ini

Satu-satunya perbedaan antara kedua mode ini adalah dari mana parameternya berasal — itulah sebabnya keduanya memanggil API yang berbeda:

Mode token (Anda sudah mengetahui kunci situsnya) — hanya menggunakan solve() . Anda membuat CaptchaInfo sendiri dan mendapatkan token kembali:

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

Mode browser (menelusuri halaman dengan Playwright) — menggunakan detect() / get_captcha_info() / solve_on_page() . solve_on_page() lengkap mencakup deteksi, penyelesaian, dan pengisian kembali; atau Anda dapat menjalankan langkah-langkah secara terpisah untuk mengontrol sendiri setiap tahapan:

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. Memanggil Setiap API: Permintaan & Respons

Bagian ini membahas setiap metode satu per satu — panggilan sebenarnya, parameter yang akan diteruskan, contoh respons, dan penjelasan bidang respons.

4.1 solve — Selesaikan (Mode Token)

Contoh panggilan dan respons:

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())

Contoh tanggapan ( 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(...),
)

Bidang tanggapan:

• token — token yang terselesaikan; kirimkan sebagai g-recaptcha-response untuk reCAPTCHA atau cf-turnstile-response untuk Pintu Putar.
• captcha_type — tipe CAPTCHA yang dipecahkan.
• expire_time — masa berlaku token dalam hitungan detik; hadir hanya ketika layanan mengembalikannya, jika tidak None .
• user_agent — UA yang digunakan untuk menyelesaikan; hadir hanya ketika layanan mengembalikannya, jika tidak None .
• raw — TokenSolution mentah, berisi g_recaptcha_response / token / user_agent / expire_time .

4.2 solve_on_page — Deteksi seluruh halaman + penyelesaian + pengisian kembali (mode Browser)

Panggilan dan parameter: masukannya adalah Penulis Drama page , dengan SolveOnPageOptions opsional.

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())

Contoh tanggapan ( 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,
  ),
]

Bidang respons (per item):

• info — CaptchaInfo untuk CAPTCHA tersebut (jenis dan parameter).
• solution — Solution ; None karena kegagalan.
• filled — apakah token berhasil diisi kembali ke halaman.
• error — string alasan kegagalan; None sukses.

4.3 detect — Mendeteksi CAPTCHA mana yang ada di halaman

Panggilan dan parameter: masukannya adalah Penulis Drama page .

types = await cap.detect(page)

Contoh respons/bidang ( list[CaptchaType] ):

[<CaptchaType.RECAPTCHA_V2: 'reCaptchaV2'>]

Mengembalikan daftar enum tipe CAPTCHA yang terdeteksi pada halaman; daftar kosong berarti tidak ada yang ditemukan.

4.4 get_captcha_info — Membaca parameter terstruktur

Panggilan dan parameter: masukannya adalah Penulis Drama 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

Contoh respons/bidang ( list[CaptchaInfo] ):

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

4.5 get_balance — Periksa saldo

Panggilan dan parameter: tidak ada masukan.

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

Contoh respons/bidang ( BalanceResp ):

BalanceResp(balance=12.34, packages=[])

• balance — saldo akun (mengambang).
• packages — daftar paket/paket berlangganan; daftar kosong jika tidak ada.

4.6 get_supported_captchas / get_handler — Akses registri

Panggilan dan tanggapan:

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

• get_supported_captchas() — mengembalikan daftar tipe string yang saat ini didukung.