Kern-SDK

Der Motor des gesamten Ökosystems. capsolver-core verwendet reines Python, um CAPTCHAs auf einer Seite zu erkennen, ihre Parameter zu lesen, sie über den CapSolver AI-Dienst zu lösen und das Token wieder einzufügen. Die übergeordneten Pakete capsolver-agent und capsolver-mcp bauen beide darauf auf.

Nur Token-Modus. Dieses SDK löst durch die Anforderung eines Tokens von der CapSolver-API (reCAPTCHA v2/v3, Cloudflare Turnstile). Es werden keine Bildraster angeklickt oder Schieberegler auf der Seite gezogen.

1. Übersicht

capsolver-core unterteilt das „Lösen eines CAPTCHA“ in vier klare Phasen, die in einer einzigen Pipeline verkettet sind:

1. Erkennen ( detect ) – Identifizieren Sie, welche CAPTCHA-Typen auf der Seite vorhanden sind.
2. Parameter lesen ( get_captcha_info ) – liest die strukturierten Parameter jedes CAPTCHAs (Typ, Site-Schlüssel, URL usw.) direkt von der Live-Seite.
3. Solve ( solve ) – übergeben Sie die Parameter an den KI-Dienst von CapSolver und erhalten Sie ein verwendbares Token zurück.
4. Zurückfüllen ( solve_on_page ) – Schreiben Sie das Token zurück in das Seiten-DOM, damit die Site die Verifizierung als bestanden behandelt.

Rund um diese Pipeline werden mehrere technische Annehmlichkeiten hinzugefügt:

• ✅ Vollständig asynchrone API – basiert auf async / await, sodass Sie eine große Anzahl von Lösungen gleichzeitig ausführen können.
• ✅ Wiederverwendung und Bereinigung von Verbindungen – verwaltet einen internen HTTP-Verbindungspool und fungiert als asynchroner Kontextmanager.
• ✅ Pluggable Handler Registry – jeder CAPTCHA-Typ wird von einem Handler verarbeitet, den Sie anpassen oder überschreiben können.
• ✅ Zwei Granularitätsebenen – gehen Sie auf reine API um, wenn die Parameter bekannt sind; Verwenden Sie den Playwright-Browsermodus, wenn Sie nur die Seite haben.

Wann sollten Sie core direkt verwenden? Wenn Sie den Code selbst steuern und die Lösung nicht einem LLM aussetzen müssen.

2. Installation

capsolver-core ist Open Source auf GitHub und noch nicht auf PyPI veröffentlicht, also installieren Sie es über 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

Legen Sie Ihren Schlüssel fest:

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

Hinweis: Das SDK funktioniert ohne das Extra [playwright] – in diesem Fall ist nur der Token-Modus ( solve ) verfügbar und die browserabhängigen Methoden detect / get_captcha_info / solve_on_page sind nicht verfügbar, da Playwright fehlt.

3. Die API und die beiden Modi

3.1 Erstellen Sie einen Kunden

create_capsolver(**options) (oder Capsolver(**options) ) gibt einen Client zurück.

Capsolver enthält einen internen HTTP-Verbindungspool und wird daher am besten als asynchroner Kontextmanager verwendet, um sicherzustellen, dass Verbindungen freigegeben werden:

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 Methoden im Überblick

3.3 Eingabe lösen: CaptchaInfo

Die Kerneingabe für solve() ist ein CaptchaInfo . type , website_url und website_key sind erforderlich (ein leeres website_url oder website_key löst ValueError aus); Der Rest ist je nach CAPTCHA-Typ optional:

Die Optionen für solve_on_page() werden von SolveOnPageOptions gesteuert:

Der wait_options für solve() ( WaitOptions ) verfügt nur über zwei optionale Felder, timeout und polling_interval , die zum Überschreiben der globalen Standardeinstellungen des Clients für eine einzelne Lösung verwendet werden.

3.4 Rückgabetypen

detect() gibt list[CaptchaType] zurück und get_captcha_info() gibt list[CaptchaInfo] zurück.

3.5 Wie jeder Modus diese APIs verwendet

Der einzige Unterschied zwischen den beiden Modi besteht darin, woher die Parameter kommen – weshalb sie unterschiedliche APIs aufrufen:

Token-Modus (Sie kennen den Site-Schlüssel bereits) – verwendet nur solve() . Sie konstruieren den CaptchaInfo selbst und erhalten einen Token zurück:

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

Browsermodus (Antreiben der Seite mit Playwright) – verwendet detect() / get_captcha_info() / solve_on_page() . Das All-in-one-solve_on_page() deckt Erkennung, Lösung und Auffüllung ab; Sie können die Schritte auch separat ausführen, um jede Phase selbst zu steuern:

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. Aufrufen jeder API: Anfragen und Antworten

In diesem Abschnitt wird jede Methode einzeln beschrieben – der eigentliche Aufruf, die zu übergebenden Parameter, eine Beispielantwort und eine Erläuterung der Antwortfelder.

4.1 solve – Lösen (Token-Modus)

Beispiel für einen Anruf und eine Antwort:

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

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

Antwortfelder:

• token – das gelöste Token; Reichen Sie es als g-recaptcha-response für reCAPTCHA oder cf-turnstile-response für Turnstile ein.
• captcha_type – der CAPTCHA-Typ, der gelöst wurde.
• expire_time – Token-Ablauf in Sekunden; Nur vorhanden, wenn der Dienst es zurückgibt, andernfalls None .
• user_agent – der zur Lösung verwendete UA; Nur vorhanden, wenn der Dienst es zurückgibt, andernfalls None .
• raw – der rohe TokenSolution, der g_recaptcha_response / token / user_agent / expire_time enthält.

4.2 solve_on_page – Ganzseitige Erkennung + Lösung + Auffüllen (Browsermodus)

Aufruf und Parameter: Die Eingabe ist ein Playwright page mit einem optionalen SolveOnPageOptions .

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

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

Antwortfelder (pro Element):

• info – der CaptchaInfo für dieses CAPTCHA (Typ und Parameter).
• solution – der Solution ; None bei Fehler.
• filled – ob das Token erfolgreich wieder in die Seite eingefügt wurde.
• error – Zeichenfolge für die Fehlerursache; None auf Erfolg.

4.3 detect – Erkennen Sie, welche CAPTCHAs sich auf der Seite befinden

Aufruf und Parameter: Die Eingabe ist ein Playwright page .

types = await cap.detect(page)

Beispielantwort/Felder ( list[CaptchaType] ):

[<CaptchaType.RECAPTCHA_V2: 'reCaptchaV2'>]

Gibt eine Liste der auf der Seite erkannten Aufzählungen vom Typ CAPTCHA zurück. Eine leere Liste bedeutet, dass keine gefunden wurden.

4.4 get_captcha_info – Strukturierte Parameter lesen

Aufruf und Parameter: Die Eingabe ist ein Playwright 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

Beispielantwort/Felder ( list[CaptchaInfo] ):

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

4.5 get_balance – Guthaben prüfen

Aufruf und Parameter: keine Eingabe.

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

Beispielantwort/Felder ( BalanceResp ):

BalanceResp(balance=12.34, packages=[])

• balance – Kontostand (Float).
• packages – Liste der Pläne/Abonnementpakete; eine leere Liste, wenn keine vorhanden sind.

4.6 get_supported_captchas / get_handler – Registrierungszugriff

Anruf und Antwort:

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

• get_supported_captchas() – gibt eine Liste der derzeit unterstützten Typzeichenfolgen zurück.