Scarnox · Blog

PopularCaptcha in Python lösen (funktionierendes Beispiel, 2026)

Wenn dein Python-Skript auf ein PopularCaptcha gestoßen ist, brauchst du weder eine Browser-Farm noch ein eigenes Modell. Du brauchst den Sitekey der Seite, eine POST-Anfrage und das Token, das zurückkommt.

Dieser Leitfaden führt dich in etwa fünf Minuten von null zu einem funktionierenden Token: API-Schlüssel holen, Sitekey finden, Token anfordern, an das Formular übermitteln und die Fehlerfälle behandeln, die auftreten, sobald ein Skript ohne Aufsicht läuft. Fehlgeschlagene Lösungen sind kostenlos, eine Wiederholung kostet dich also nur Zeit.

Scarnox löst PopularCaptcha heute, proxyless oder mit deinem eigenen Proxy. Andere Captcha-Typen wie reCAPTCHA, Cloudflare Turnstile und AWS WAF kommen demnächst, deshalb verwenden alle Beispiele hier PopularCaptcha. Die Übersicht über Captcha-Typen erklärt, wie sich die anderen unterscheiden.

1. API-Schlüssel holen

Erstelle ein Konto und starte mit kostenlosem Testguthaben, ohne Karte. Dein API-Schlüssel steht im Dashboard. Halte ihn aus deinem Quellcode heraus und lies ihn aus einer Umgebungsvariable:

export SCARNOX_KEY="scarnox_YOURAPIKEY"

2. Den Sitekey finden

Öffne die Seite mit dem Captcha, öffne die DevTools und suche im Elements-Panel nach data-sitekey. PopularCaptcha-Sitekeys sind UUIDs:

<div class="h-captcha" data-sitekey="10000000-ffff-ffff-ffff-000000000001"></div>

Kein data-sitekey im HTML? Dann rendert wahrscheinlich JavaScript das Widget. Schau im Netzwerk-Tab nach der Konfigurationsanfrage des Widgets; dessen Query-Parameter sitekey ist der, den du brauchst. Weitere Wege, ihn zu finden behandeln die iframe-URL und unsichtbare Widgets.

Sende die URL der Seite, die das Widget anzeigt, als site_url. Der Host ist am wichtigsten, aber die vollständige Seiten-URL ist die sichere Wahl.

3. Ein Token anfordern

import os
import requests

API_URL = "https://api.scarnox.com/api/tasks/create"
API_KEY = os.environ["SCARNOX_KEY"]

def solve_captcha(sitekey: str, page_url: str) -> str:
    r = requests.post(
        API_URL,
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "captcha_type": "PopularCaptchaTaskProxyless",
            "site_key": sitekey,
            "site_url": page_url,
        },
        timeout=185,  # der Aufruf blockiert, bis das Token bereit ist
    )
    data = r.json()
    if data.get("errorId") != 0:
        raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
    return data["solution"]["token"]

if __name__ == "__main__":
    token = solve_captcha("10000000-ffff-ffff-ffff-000000000001", "https://example.com/signup")
    print(token[:40], "...")

Das ist die ganze Integration. Es gibt keine Polling-Schleife und keinen zweiten Aufruf zum "Ergebnis abholen". Die Anfrage kehrt zurück, sobald das Token bereit ist. Die eine Einstellung, die zählt, ist also ein Timeout, das eine langsame Lösung abdeckt. Verwende etwa 185 Sekunden.

Eine erfolgreiche Antwort hat errorId auf 0, mit dem Token unter solution.token. Jeder andere errorId bedeutet, dass die Lösung fehlgeschlagen ist, und die Antwort enthält einen errorCode und eine errorDescription, die sagen, warum.

4. Das Token absenden

Das Token geht dorthin, wo die Seite die Captcha-Antwort erwartet. Bei PopularCaptcha ist das fast immer ein Formularfeld namens h-captcha-response. Viele Seiten akzeptieren außerdem g-recaptcha-response, also sende beide:

import requests

def sign_up(session: requests.Session, form_url: str, email: str, sitekey: str) -> requests.Response:
    token = solve_captcha(sitekey, form_url)
    return session.post(form_url, data={
        "email": email,
        "h-captcha-response": token,
        "g-recaptcha-response": token,
    }, timeout=30)

Zwei Details sind wichtig. Echte Seiten prüfen meist die Sitzungs-Cookies aus dem Seitenaufruf, also lade das Formular mit derselben requests.Session, bevor du sendest. Und sende an die action des Formulars, die nicht immer die Seiten-URL ist.

Löse direkt vor dem Absenden. Das Token läuft in etwa zwei Minuten ab, also hol es nicht am Anfang eines langen Jobs und behalte es nicht. Lehnt die Seite das Token ab, öffne das Formular in den DevTools und bestätige die Namen der versteckten Felder.

5. Fehler behandeln

Fehlgeschlagene Lösungen sind kostenlos, eine Wiederholung kostet also nur Zeit. Manche Fehler werden bei einer Wiederholung aber nie gelingen, daher solltest du nicht blind in einer Schleife wiederholen. Prüfe bei jedem Aufruf errorId, protokolliere errorCode und errorDescription und wiederhole nur die vorübergehenden Fehler.

Netzwerkfehler brauchen eine eigene Behandlung, weil requests ausgelöst wird, bevor es überhaupt eine Antwort gibt:

import requests

try:
    token = solve_captcha(sitekey, page_url)
except requests.RequestException as exc:
    print("network problem, retry later:", exc)
except RuntimeError as exc:
    print("solve rejected:", exc)

Der Fehlerbehandlungs-Leitfaden enthält eine vollständige Wiederholungsstrategie mit Zurückschalten und Jitter.

Häufige Fehler

Kostenlos ausprobieren

Erstelle ein Konto und starte mit kostenlosem Testguthaben, ohne Karte. Führe das Beispiel oben gegen ein Formular aus, das dir gehört, bevor du es in einen größeren Job einbaust. Was das Lösen im größeren Umfang kostet, steht auf der Preisseite.

Jede Lösung protokollieren

Schreibe pro Lösung eine Zeile: den Sitekey, den Host der Seite, das errorId, bei einem Fehler den errorCode und wie lange der Aufruf gedauert hat. Lass den API-Schlüssel und Proxy-Passwörter weg. Diese Zeilen zeigen dir, ob ein langsamer Lauf an der Seite, am Proxy oder am Solver liegt. Außerdem sind sie das Erste, was du für eine Support-Anfrage brauchst.

Lösen in einer Schleife

Wenn dein Skript viele Captchas hintereinander löst, halte die Schleife einfach. Lösen, absenden, Ergebnis prüfen und erst dann weitergehen. Löse nicht im Voraus und stelle Tokens nicht in eine Warteschlange, denn jedes läuft in etwa zwei Minuten ab. Eine kurze Pause zwischen Lösungen auf derselben Seite hält deine Anfragerate nahe an dem, was ein Mensch erzeugen würde.

Nächste Schritte