Einführung und Schnellstart

1. Einführung des CapSolver Python SDK

Das SDK wird als drei unabhängige Pakete geliefert – jedes einzeln über pip install installierbar – sowie als begleitendes Beispiel-Repository. Zusammen ermöglichen sie es Ihnen, in nur wenigen Python-Zeilen von „Es gibt ein CAPTCHA auf der Seite“ zu „Ich habe ein gültiges Token“ zu gelangen – egal, ob Sie ein einmaliges Skript schreiben, einen echten Browser mit Playwright steuern oder Lösungsfähigkeiten in einen autonomen KI-Agenten integrieren.

Es basiert auf dem KI-Lösungsdienst von CapSolver. Das SDK kümmert sich um alles auf Ihrer Seite – das Erkennen des CAPTCHAs, das Zusammenstellen der Parameter, das Aufrufen des Dienstes und das erneute Ausfüllen des Ergebnisses – während die eigentliche Erkennung und Lösung in der Cloud erfolgt. Die Kernidee lässt sich in einem einzigen Satz zusammenfassen: Ihr Code (oder Ihr Modell) entscheidet, was zu tun ist, und CapSolver kümmert sich um die Lösung.

1.1 Kernfunktionen

• ✅ KI-gestützte Token-Lösung – CapSolver gibt einen Token zurück, den Sie an die Zielseite übermitteln.
• ✅ Zwei Nutzungsmodi – reine API (Token-Modus, für bekannte Site-Schlüssel, kein Browser erforderlich) und Playwright-basierter Browser-Modus.
• ✅ Abdeckung der wichtigsten CAPTCHAs – reCAPTCHA v2 / v3 (einschließlich Enterprise) und Cloudflare Turnstile.
• ✅ Vollständig asynchrone API – basiert auf async / await, eine natürliche Ergänzung für moderne Crawler und Agenten.
• ✅ Dreischichtige Pakete – von der Low-Level-Engine über Agent-Tools bis hin zu einem MCP-Dienst; Wählen Sie aus, was Sie brauchen (siehe 1.2).
• ✅ Gebündelte CLIs – capsolver , capsolver-agent und capsolver-mcp ermöglichen Ihnen die Ausführung von Diagnosen, ohne Code schreiben zu müssen.

1.2 Unterstützte CAPTCHAs und Parameter

Das SDK löst derzeit die folgenden CAPTCHA-Typen:

Die für jeden Typ erforderlichen Kernparameter sind website_url + website_key . reCAPTCHA v3 kann zusätzlich page_action , min_score und einen enterprise-Hinweis annehmen, während Cloudflare cdata annehmen kann. Sie können die von Ihrem aktuellen Build unterstützten Typen jederzeit überprüfen:

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

Hinweis: Im Browsermodus müssen Sie diese Parameter nicht manuell angeben – get_captcha_info(page) liest den Typ und den Site-Schlüssel direkt von der Live-Seite für Sie.

2. Kernfunktionen (SDK)

2.1 Die drei Pakete

Der vollständige Funktionsumfang plus ein Beispiel-Repository. Dabei handelt es sich nicht um drei Peers, zwischen denen man wählen kann – die beiden letztgenannten basieren beide auf capsolver-core und bieten lediglich die gleiche Lösungsfähigkeit über eine andere Schnittstelle. Wählen Sie diejenige aus, die am besten zu Ihrer Arbeitsweise passt.

** capsolver-core – Das Kern-SDK (Engine)**

Das Paket der untersten Ebene und die gemeinsame Engine, von der die anderen beiden abhängen. Es unterteilt die Lösung eines CAPTCHAs in vier Schritte – Erkennen → Parameter lesen → Lösen → Zurückfüllen – und bietet zwei Granularitätsebenen: Wenn der Site-Schlüssel bekannt ist, gehen Sie zur reinen API (Token-Modus, kein Browser); Wenn Sie nur die Seite haben, lassen Sie Playwright das Ergebnis automatisch erkennen und wieder einfüllen. Vollständig asynchron, mit einer steckbaren Handler-Registrierung.

• Am besten geeignet für: Skripte, Crawler und Automatisierung, bei denen Sie den Code kontrollieren und kein LLM benötigen.
• Einstiegspunkte: create_capsolver() → solve() / solve_on_page() .
• Installieren: pip install capsolver-core (fügen Sie [playwright] für den Browsermodus hinzu).

** capsolver-agent – Agent-Tools**

Umfasst den Kern als Tools, die ein LLM aufrufen kann: Es bietet Framework-unabhängige Tool-Schemata sowie einen asynchronen Executor sowie vorgefertigte LangChain BaseTool-Implementierungen. Innerhalb seiner Schleife ruft das Modell „solve“ auf die gleiche Weise auf, wie es „click“ oder „type“ aufruft, und der Executor leitet diesen Aufruf an die Methoden des Kerns weiter und gibt ein strukturiertes Ergebnis zurück.

• Am besten für: das Modell entscheiden lassen, wann gelöst werden soll – OpenAI-Funktionsaufruf, das OpenAI Agents SDK, LangChain, Browser-Nutzung oder eine beliebige benutzerdefinierte Agentenschleife.
• Einstiegspunkte: get_all_tools() + create_executor() oder get_langchain_tools() .
• Installieren: pip install capsolver-agent (füge [langchain] für LangChain hinzu).

** capsolver-mcp – MCP-Dienst**

Stellt die gleichen Tools wie ein Standarddienst über das Model Context Protocol bereit. Jeder MCP-kompatible Client erkennt diese Tools automatisch bei der Verbindung – es ist kein Adaptercode pro Client erforderlich. Unterstützt drei Transporte: stdio, SSE und streamable-http.

• Am besten geeignet für: Plug-and-Play-Einsatz in einem KI-Client – Claude Desktop, Claude Code, Cursor, Windsurf, Cline und mehr, mit nahezu keinem Integrationscode.
• Einstiegspunkte: der Befehl capsolver-mcp oder create_server() .
• Installieren: pip install capsolver-mcp (fügen Sie [browser] für die Browser-Tools hinzu).

2.2 Anwendungsfälle

Jedes Mal, wenn ein CAPTCHA den nächsten Schritt blockiert, verdient dieses SDK seinen Platz. Einige typische Szenarien:

Web Scraping/Datenerfassung

Ein Crawler stößt auf ein reCAPTCHA oder Turnstile auf einer Listingseite, Suchseite oder Login-Wall und die gesamte Sammelpipeline bleibt stehen. Verwenden Sie den Token-Modus, um ein Token abzurufen und es mit Ihrer Anfrage zu übermitteln, oder verwenden Sie den Browser-Modus, um es direkt in die Seite einzufügen – in jedem Fall wird das Scraping fortgesetzt. → Empfohlen: capsolver-core (Token-Modus, wenn der Site-Schlüssel bekannt ist; solve_on_page für dynamische Seiten).

Konto- und Workflow-Automatisierung

Bei mehrstufigen Abläufen wie der Registrierung, dem Login, dem Zurücksetzen des Passworts und dem Auschecken wird oft ein CAPTCHA bei einem bestimmten Schritt ausgelöst, wodurch das gesamte Skript einfriert. Lassen Sie die Lösung in genau diesem Schritt fallen – sobald das Token ausgefüllt ist, sendet das Skript das Formular weiter, wartet auf die Weiterleitung und führt die verbleibenden Schritte bis zum Abschluss aus. → Empfohlen: capsolver-core Browsermodus; besonders reibungslos, wenn Ihr Skript bereits Playwright steuert.

KI-Agenten (autonomes Surfen)

Geben Sie einem Agenten eine Aufgabe wie „Anmelden und Bestellungen entgegennehmen“, und unterwegs wird ohne Vorwarnung irgendwo ein CAPTCHA angezeigt. Anstatt das Modell durch sich selbst klicken zu lassen – pixelgenaues Targeting und menschenähnliche Cursorpfade lassen sich kaum über Risiko-Engines hinweg fälschen, und Bildwiederholungsschleifen überschwemmen das Kontextfenster – registrieren Sie eine „Lösen“-Aktion dafür: Wenn es auf ein CAPTCHA trifft, ruft es die Aktion auf, erhält ein Token zurück und fährt in derselben Browsersitzung fort, ohne den Fluss zu unterbrechen. → Empfohlen: capsolver-agent (vom Modell selbst aufrufen lassen) oder capsolver-mcp (direkt in einem KI-Client verwenden).

Automatisierte Tests / interne Tools

End-to-End-Tests und interne Betriebstools müssen CAPTCHA-Schritte auf Ihren eigenen Websites oder auf Websites Dritter zuverlässig löschen, ohne dass manuelle Eingriffe die Prozesse verlangsamen. → Empfohlen: Wählen Sie nach Umgebung – capsolver-core (im Code) oder capsolver-mcp (in einem Client).

Kurz gesagt: Überall dort, wo Sie ein CAPTCHA programmgesteuert in Python löschen müssen, ist dieses SDK in Reichweite.

3. Installation und API-Schlüssel-Setup

Bevor Sie beginnen, sollten Sie eines im Hinterkopf behalten: Die eigentliche Lösung erfolgt über den Cloud-Service von CapSolver – das SDK ruft sie nur von Ihrer Seite auf. Der erste Schritt besteht also nicht darin, ein Paket zu installieren; Es geht darum, ein Konto und einen API-Schlüssel zu haben. Die Einrichtung besteht aus drei Schritten in der Reihenfolge: Registrieren und einen Schlüssel erhalten → SDK installieren → Schlüssel verbinden.

3.1 Registrieren Sie sich und erhalten Sie Ihren API-Schlüssel

1. Registrieren Sie ein Konto auf der CapSolver-Website.
2. Öffnen Sie das Dashboard und kopieren Sie Ihren API-Schlüssel.
3. Fügen Sie Ihrem Konto Geld hinzu – jede erfolgreiche Lösung verbraucht Guthaben und die Lösung schlägt fehl, wenn das Guthaben Null erreicht.

3.2 Installieren Sie das SDK

Die drei Pakete werden derzeit als Open Source auf GitHub gehostet und noch nicht auf PyPI veröffentlicht, also installieren Sie sie über Git. capsolver-core ist die Engine, und sowohl capsolver-agent als auch capsolver-mcp hängen von ihr ab – Kern ist also immer erforderlich. Fügen Sie die obere Ebene hinzu, die Sie verwenden möchten:

# 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

Fügen Sie für den Browsermodus (Erkennen von CAPTCHAs auf einer echten Seite und erneutes Ausfüllen des Tokens) das Extra [playwright] hinzu und installieren Sie Chromium:

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

Hinweis: detect und solve_on_page erfordern den Browser zusätzlich; Der Token-Modus benötigt überhaupt keinen Browser.

Die drei Repositorys sind:

Sie können ein Repository auch vor der Installation lokal klonen – praktisch zum Lesen der Quelle oder für Ihre eigene Entwicklung:

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 Verbinden Sie Ihren API-Schlüssel

Übergeben Sie abschließend den Schlüssel aus Schritt 3.1 an das SDK. Standardmäßig lesen alle Pakete es aus der Umgebungsvariablen 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

Alternativ können Sie die Umgebungsvariable überspringen und api_key="..." direkt an create_capsolver() übergeben.

4. Ihre erste Lösung

Wenn die Umgebung bereit ist, lassen Sie uns ein Ende mit dem kleinstmöglichen Code ausführen. Welchen Weg Sie einschlagen, hängt davon ab, ob Sie den Site-Schlüssel bereits kennen: Wenn ja, verwenden Sie den Token-Modus. Wenn Sie lediglich eine Seiten-URL haben, verwenden Sie den Browsermodus.

4.1 Token-Modus (Sie kennen den Site-Schlüssel bereits)

Wenn Sie den CAPTCHA-Typ, die Seiten-URL und den Site-Schlüssel kennen, ist kein Browser erforderlich – übergeben Sie die Parameter und erhalten Sie ein Token zurück.

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 Browsermodus (ein Aufruf, direkt auf der Live-Seite)

Wenn Sie nur eine Seite haben – und Sie lieber nicht selbst nach dem Site-Schlüssel suchen möchten – lassen Sie das SDK jedes CAPTCHA auf der Seite automatisch erkennen, sie einzeln lösen und die Token wieder in das DOM füllen. Ein Anruf erledigt alles.

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