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

pip install capsolver-core
 
# With Playwright support (for detect / solve_on_page)
pip install capsolver-core[playwright]
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.