Pendahuluan & Mulai Cepat

1. Memperkenalkan CapSolver Python SDK

SDK dikirimkan sebagai tiga paket independen — masing-masing dapat diinstal sendiri melalui pip install — ditambah repositori contoh pendamping. Bersama-sama, keduanya memungkinkan Anda beralih dari “ada CAPTCHA di halaman” menjadi “Saya punya token yang valid” hanya dalam beberapa baris Python — baik Anda menulis skrip satu kali, menjalankan browser sungguhan dengan Playwright, atau menghubungkan kemampuan penyelesaian ke dalam agen AI yang otonom.

Ini didukung oleh layanan penyelesaian AI CapSolver. SDK menangani semua yang ada di pihak Anda — mendeteksi CAPTCHA, menyusun parameter, memanggil layanan, dan mengisi kembali hasilnya — sementara pengenalan dan penyelesaian sebenarnya terjadi di cloud. Ide intinya muncul dalam satu kalimat: kode Anda (atau model Anda) memutuskan apa yang harus dilakukan, dan CapSolver menangani menyelesaikannya.

1.1 Fitur Inti

• ✅ Pemecahan token bertenaga AI — CapSolver mengembalikan token yang Anda kirimkan ke situs target.
• ✅ Dua mode penggunaan — API murni (Mode Token, untuk kunci situs yang diketahui, tidak diperlukan browser) dan mode Browser berbasis Playwright.
• ✅ Cakupan CAPTCHA utama — reCAPTCHA v2 / v3 (termasuk Perusahaan) dan Pintu Putar Cloudflare.
• ✅ API yang sepenuhnya asinkron — dibangun di atas async / await , yang secara alami cocok untuk perayap dan agen modern.
• ✅ Paket tiga lapis — mulai dari mesin tingkat rendah, alat agen, hingga layanan MCP; pilih yang Anda perlukan (lihat 1.2).
• ✅ Paket CLI — capsolver , capsolver-agent , dan capsolver-mcp memungkinkan Anda menjalankan diagnostik tanpa menulis kode apa pun.

1.2 CAPTCHA & Parameter yang Didukung

SDK saat ini memecahkan jenis CAPTCHA berikut:

Parameter inti yang dibutuhkan oleh setiap tipe adalah website_url + website_key . reCAPTCHA v3 juga dapat menggunakan page_action , min_score , dan petunjuk enterprise, sedangkan Cloudflare dapat menggunakan cdata . Anda dapat memeriksa tipe yang didukung oleh build Anda saat ini kapan saja:

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

Catatan: Dalam mode Browser Anda tidak perlu menyediakan parameter ini secara manual — get_captcha_info(page) membaca jenis dan kunci situs langsung dari halaman aktif untuk Anda.

2. Kemampuan Inti (SDK)

2.1 Tiga Paket

Kumpulan fitur lengkap ditambah satu contoh repositori. Ini bukan tiga rekan yang dapat dipilih — dua yang terakhir dibangun di atas capsolver-core , hanya memberikan kemampuan penyelesaian yang sama melalui antarmuka yang berbeda. Pilih salah satu yang paling sesuai dengan cara Anda bekerja.

** capsolver-core — SDK Inti (Mesin)**

Paket tingkat terendah, dan mesin bersama yang diandalkan oleh dua paket lainnya. Ini memecah penyelesaian CAPTCHA menjadi empat langkah — deteksi → baca parameter → selesaikan → isi kembali — dan menawarkan dua tingkat perincian: ketika kunci situs diketahui, gunakan API murni (mode Token, tanpa browser); bila Anda hanya memiliki halamannya, biarkan Penulis Drama mendeteksi secara otomatis dan mengisi kembali hasilnya. Sepenuhnya asinkron, dengan registri pengendali yang dapat dicolokkan.

• Terbaik untuk: skrip, crawler, dan otomatisasi tempat Anda mengontrol kode dan tidak memerlukan LLM.
• Titik masuk: create_capsolver() → solve() / solve_on_page() .
• Instal: pip install capsolver-core (tambahkan [playwright] untuk mode Browser).

** capsolver-agent — Alat Agen**

Membungkus inti sebagai alat yang dapat dipanggil oleh LLM: ia menyediakan skema alat agnostik kerangka kerja ditambah eksekutor asinkron, serta implementasi LangChain BaseTool yang siap pakai. Dalam loopnya, model memanggil “solve” dengan cara yang sama seperti memanggil “click” atau “type”, dan eksekutor menyampaikan pemanggilan tersebut ke metode inti dan mengembalikan hasil terstruktur.

• Terbaik untuk: membiarkan model memutuskan kapan harus menyelesaikannya — pemanggilan fungsi OpenAI, SDK Agen OpenAI, LangChain, Penggunaan Browser, atau loop agen khusus apa pun.
• Titik masuk: get_all_tools() + create_executor() , atau get_langchain_tools() .
• Instal: pip install capsolver-agent (tambahkan [langchain] untuk LangChain).

** capsolver-mcp — Layanan MCP**

Mengekspos seperangkat alat yang sama dengan layanan standar melalui Model Context Protocol. Setiap klien yang kompatibel dengan MCP akan menemukan alat ini secara otomatis saat koneksi — tidak diperlukan kode adaptor per klien. Mendukung tiga transport: stdio, SSE, dan streamable-http.

• Terbaik untuk: penggunaan plug-and-play di dalam klien AI — Claude Desktop, Claude Code, Cursor, Windsurf, Cline, dan banyak lagi, dengan kode integrasi yang hampir nol.
• Titik masuk: perintah capsolver-mcp, atau create_server() .
• Instal: pip install capsolver-mcp (tambahkan [browser] untuk alat browser).

2.2 Kasus Penggunaan

Setiap kali CAPTCHA memblokir langkah berikutnya, SDK ini akan mendapatkan tempatnya. Beberapa skenario umum:

Pengikisan web / pengumpulan data

Perayap menemukan reCAPTCHA atau Pintu Putar pada halaman daftar, halaman pencarian, atau dinding masuk, dan seluruh saluran pengumpulan terhenti. Gunakan mode Token untuk mendapatkan token dan mengirimkannya bersama permintaan Anda, atau gunakan mode Browser untuk mengisinya langsung ke halaman — apa pun yang terjadi, pengikisan akan terus berlanjut. → Direkomendasikan: capsolver-core (Mode Token ketika kunci situs diketahui; solve_on_page untuk halaman dinamis).

Otomasi akun & alur kerja

Alur multi-langkah seperti pendaftaran, login, pengaturan ulang kata sandi, dan pembayaran sering kali memunculkan CAPTCHA pada satu langkah tertentu, sehingga membekukan seluruh skrip. Masukkan penyelesaian ke dalam langkah tersebut — setelah token diisi, skrip terus mengirimkan formulir, menunggu pengalihan, dan menjalankan langkah selanjutnya hingga selesai. → Disarankan: capsolver-core Mode peramban; sangat lancar ketika skrip Anda sudah menjalankan Playwright.

Agen AI (penjelajahan otonom)

Berikan tugas kepada agen seperti “masuk dan tarik pesanan”, dan CAPTCHA akan muncul di suatu tempat di sepanjang proses tanpa peringatan. Daripada membuat model mengklik dirinya sendiri — penargetan dengan piksel sempurna dan jalur kursor mirip manusia sulit dipalsukan melewati mesin risiko, dan loop percobaan ulang gambar membanjiri jendela konteks — daftarkan tindakan “pecahkan” untuk model tersebut: ketika mencapai CAPTCHA, ia akan memanggil tindakan tersebut, mendapatkan token kembali, dan melanjutkan di sesi browser yang sama tanpa memutus alur. → Direkomendasikan: capsolver-agent (biarkan model memanggilnya sendiri), atau capsolver-mcp (gunakan langsung di dalam klien AI).

Pengujian otomatis/alat internal

Pengujian menyeluruh dan alat operasi internal perlu menghapus langkah-langkah CAPTCHA di situs Anda sendiri atau situs pihak ketiga dengan andal, tanpa intervensi manual yang memperlambat segalanya. → Direkomendasikan: pilih berdasarkan lingkungan — capsolver-core (dalam kode) atau capsolver-mcp (di klien).

Singkatnya: di mana pun Anda perlu menghapus CAPTCHA secara terprogram dengan Python, SDK ini ada dalam jangkauan.

3. Instalasi & Pengaturan Kunci API

Sebelum memulai, ingatlah satu hal: penyelesaian sebenarnya terjadi pada layanan cloud CapSolver — SDK hanya memanggilnya dari pihak Anda. Jadi langkah pertama bukanlah menginstal sebuah paket; itu memiliki akun dan kunci API. Penyiapannya terdiri dari tiga langkah, secara berurutan: daftar dan dapatkan kunci → instal SDK → sambungkan kunci.

3.1 Daftar dan Dapatkan Kunci API Anda

1. Daftarkan akun di situs web CapSolver.
2. Buka dasbor dan salin kunci API Anda.
3. Tambahkan dana ke akun Anda — setiap penyelesaian yang berhasil akan menghabiskan saldo, dan penyelesaian akan gagal ketika saldo mencapai nol.

3.2 Instal SDK

Ketiga paket tersebut saat ini dihosting sebagai sumber terbuka di GitHub dan belum dipublikasikan ke PyPI, jadi instal melalui git. capsolver-core adalah mesinnya, dan capsolver-agent dan capsolver-mcp bergantung padanya — jadi inti selalu diperlukan. Tambahkan lapisan atas mana pun yang ingin Anda gunakan:

# 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

Untuk mode Browser (mendeteksi CAPTCHA di halaman sebenarnya dan mengisi kembali token), tambahkan ekstra [playwright] dan instal Chromium:

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

Catatan: detect dan solve_on_page memerlukan browser ekstra; Mode Token tidak memerlukan browser sama sekali.

Ketiga repositori tersebut adalah:

Anda juga dapat mengkloning repositori secara lokal sebelum menginstal — berguna untuk membaca sumber atau melakukan pengembangan Anda sendiri:

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 Hubungkan Kunci API Anda

Terakhir, serahkan kunci dari langkah 3.1 ke SDK. Secara default, semua paket membacanya dari variabel lingkungan 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

Alternatifnya, lewati variabel lingkungan dan teruskan api_key="..." langsung ke create_capsolver() .

4. Pemecahan Pertama Anda

Dengan lingkungan yang siap, mari kita jalankan ujung ke ujung dengan kode sekecil mungkin. Jalur mana yang Anda ambil bergantung pada apakah Anda sudah mengetahui kunci situsnya: jika Anda mengetahuinya, gunakan mode Token; jika yang Anda miliki hanyalah URL halaman, gunakan mode Browser.

4.1 Mode Token (Anda sudah mengetahui kunci situsnya)

Jika Anda mengetahui jenis CAPTCHA, URL halaman, dan kunci situs, tidak diperlukan browser — serahkan parameternya, dapatkan token kembali.

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 Mode Browser (satu panggilan, langsung di halaman aktif)

Jika yang Anda miliki hanyalah sebuah halaman — dan Anda memilih untuk tidak mencari kunci situsnya sendiri — biarkan SDK mendeteksi secara otomatis setiap CAPTCHA di halaman tersebut, menyelesaikannya satu per satu, dan mengisi token kembali ke DOM. Satu panggilan melakukan semuanya.

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