reCAPTCHA v2 per API lösen: Schritt-für-Schritt-Anleitung

reCAPTCHA v2 lösen Sie per API in vier Schritten: sitekey und pageurl aus der Seite auslesen, beide an den reCAPTCHA-v2-Solver von CaptchaAI übermitteln, das Ergebnis abfragen und das zurückgegebene Token in den geschützten Formularfluss einfügen. Dieser Ablauf bleibt gleich – egal ob die Checkbox „Ich bin kein Roboter", eine Bild-Abfrage oder eine unsichtbare Variante geladen wird.

Diese Anleitung ist für Entwickler geschrieben, die eine lauffähige Integration brauchen: vollständiger Code in Python und Node.js, dazu die Fehlerbilder, die in der Praxis wirklich auftreten. Kein Theorie-Überblick, sondern der direkte Weg vom leeren Formular zum gültigen Token.

Sie wissen nicht, welche reCAPTCHA-Version die Seite verwendet? Klären Sie das zuerst mit reCAPTCHA-Version erkennen.

Was Sie vorab brauchen

Der Ablauf in Kürze

Bevor es an den Code geht, hier die vier Schritte im Überblick – die Reihenfolge bleibt bei jedem reCAPTCHA-v2-Widget identisch:

1. Extrahieren – sitekey und pageurl aus der Zielseite lesen.
2. Übermitteln – beide an in.php senden; die API antwortet mit einer Task-ID.
3. Abfragen – res.php pollen, bis statt CAPCHA_NOT_READY das Token kommt.
4. Einfügen – das Token in das Feld g-recaptcha-response schreiben und das Formular absenden.

Schritt 1: sitekey und pageurl aus der Seite holen

Die pageurl ist die vollständige URL der Seite, auf der reCAPTCHA erscheint – immer mit https:// übergeben. Ein falsches sitekey/pageurl-Paar ist der mit Abstand häufigste Grund, warum ein Auftrag scheitert.

Den sitekey finden Sie auf drei Wegen:

1. Im HTML – suchen Sie nach <div class="g-recaptcha" data-sitekey="...">:

<div class="g-recaptcha" data-sitekey="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"></div>

2. In der iframe-URL – in https://www.google.com/recaptcha/api2/anchor?ar=1&k=6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-&... ist der Parameter k= der sitekey.

3. Im Netzwerk-Traffic – filtern Sie in den DevTools unter „Network" nach recaptcha; in jeder Anfrage taucht der Parameter k auf.

Liegt das Widget in einem iframe auf einer anderen Subdomain, verwenden Sie als pageurl die Quell-URL des iframes, nicht die der übergeordneten Seite.

Schritt 2: Lösungsauftrag an die API übermitteln

Senden Sie sitekey (als googlekey) und pageurl per POST an in.php. Die Methode für reCAPTCHA v2 heißt userrecaptcha:

import requests

API_KEY = "YOUR_API_KEY"
SITEKEY = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
PAGEURL = "https://example.com/login"

submit = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": API_KEY,
    "method": "userrecaptcha",
    "googlekey": SITEKEY,
    "pageurl": PAGEURL,
    "json": 1,
}).json()

assert submit["status"] == 1, submit
task_id = submit["request"]
print("task id:", task_id)

Dieselbe Anfrage in Node.js:

const r = await fetch("https://ocr.captchaai.com/in.php", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    key: API_KEY,
    method: "userrecaptcha",
    googlekey: SITEKEY,
    pageurl: PAGEURL,
    json: "1",
  }),
});
const { status, request: taskId } = await r.json();
if (status !== 1) throw new Error(taskId);

Unsichtbares reCAPTCHA? Ergänzen Sie invisible=1. Details in Wie unsichtbares reCAPTCHA funktioniert.

Schritt 3: Auf das Token warten

reCAPTCHA v2 wird in der Regel in unter 60 Sekunden gelöst. Warten Sie 20 Sekunden und fragen Sie danach alle 5 Sekunden das Ergebnis ab:

import time

time.sleep(20)
while True:
    res = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": API_KEY,
        "action": "get",
        "id": task_id,
        "json": 1,
    }).json()

    if res.get("request") == "CAPCHA_NOT_READY":
        time.sleep(5)
        continue

    if res.get("status") == 1:
        token = res["request"]
        print("token:", token[:60], "…")
        break

    raise RuntimeError(res)

Das zurückgegebene Token ist eine lange Zeichenkette, die typischerweise mit 03AGdBq25... beginnt.

Schritt 4: Token in den Flow einfügen

Wie das Token die Seite erreicht, hängt vom Formular ab. Am häufigsten schreiben Sie es direkt in das versteckte Textarea g-recaptcha-response:

document.querySelector('textarea[name="g-recaptcha-response"]').value = token;
document.querySelector("form").submit();

Mit Selenium:

driver.execute_script(
    "document.querySelector('[name=\"g-recaptcha-response\"]').value = arguments[0];",
    token,
)
driver.find_element(By.CSS_SELECTOR, "form").submit()

Mit Playwright:

await page.evaluate((t) => {
  document.querySelector('[name="g-recaptcha-response"]').value = t;
}, token);
await page.click('button[type="submit"]');

Hat das Widget einen data-callback, rufen Sie diesen zusätzlich auf – sonst verarbeitet die Seite das Token nicht:

const callback = document.querySelector(".g-recaptcha").dataset.callback;
if (callback && window[callback]) window[callback](token);

Vollständiges Beispiel (Python)

Alle vier Schritte in einer Funktion zusammengefasst – übermitteln, warten, pollen, Token zurückgeben:

import time
import requests

API_KEY = "YOUR_API_KEY"
SITEKEY = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
PAGEURL = "https://example.com/login"

def solve_recaptcha_v2():
    submit = requests.post("https://ocr.captchaai.com/in.php", data={
        "key": API_KEY, "method": "userrecaptcha",
        "googlekey": SITEKEY, "pageurl": PAGEURL, "json": 1,
    }).json()
    if submit["status"] != 1:
        raise RuntimeError(submit)
    task_id = submit["request"]

    time.sleep(20)
    for _ in range(40):
        res = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": API_KEY, "action": "get", "id": task_id, "json": 1,
        }).json()
        if res.get("request") == "CAPCHA_NOT_READY":
            time.sleep(5)
            continue
        if res.get("status") == 1:
            return res["request"]
        raise RuntimeError(res)
    raise TimeoutError("solve timed out")

if __name__ == "__main__":
    token = solve_recaptcha_v2()
    print("token:", token[:80])

Beispiel aus der Praxis: Scraping-Worker auf einem Hetzner-Server

Angenommen, Sie betreiben einen Selenium-Worker auf einem Hetzner- oder netcup-VPS, angestoßen aus einer GitLab-CI-Pipeline, und die Zielseite blendet bei jedem Login eine reCAPTCHA-v2-Checkbox ein. Ihr Worker liest den sitekey aus dem DOM, übermittelt ihn per in.php, holt das Token nach rund 20 bis 40 Sekunden ab und schreibt es in das Feld g-recaptcha-response, bevor er das Formular absendet. Der Rest der Automatisierung bleibt unverändert – CaptchaAI übernimmt nur den Lösungsschritt.

Ein Hinweis mit DACH-Bezug: Sobald Sie Proxys oder gescrapte Nutzerdaten verarbeiten, gelten IP-Adressen in der EU als personenbezogene Daten. Prüfen Sie Rechtsgrundlage und Datenfluss Ihres Workflows unabhängig von der eingesetzten CAPTCHA-Lösung – das ist Sorgfaltspflicht des Betreibers, keine Eigenschaft der API. Mehr zum Zusammenspiel mit Crawlern in reCAPTCHA v2 in Web-Scraping-Workflows.

Typische Fehler und wie Sie sie beheben

Wenn die Seite das Token trotzdem abweist

• Token erhalten, Seite blockiert weiter – das Formular nutzt einen eigenen Handler. Finden Sie den Callback und rufen Sie ihn auf, statt nur das Textarea zu füllen.
• Konsistente Session nötig – senden Sie dieselben Cookies und denselben User-Agent mit, die beim Anfordern des Tokens aktiv waren.
• Proxy-gebundenes reCAPTCHA – hängen Sie proxy und proxytype an den Auftrag an, damit der Solver aus Ihrem IP-Pool arbeitet.

Häufige Fragen

Was kostet das Lösen von reCAPTCHA v2 mit CaptchaAI?

CaptchaAI rechnet pro Thread ab, nicht pro Lösung. Der Einstieg beginnt bei BASIC (15 $/Monat, 5 Threads) mit unbegrenzten Lösungen pro Thread – ein reCAPTCHA v2 kostet also keinen Aufpreis gegenüber anderen Typen. Die Durchsatzgrenze ergibt sich allein aus der Anzahl paralleler Threads; die Preise verstehen sich in US-Dollar.

Kann ich mehrere reCAPTCHA-v2-Abfragen gleichzeitig lösen?

Ja. Jeder Thread verarbeitet eine Abfrage zur gleichen Zeit; mit fünf Threads laufen also fünf Lösungen parallel. Übermitteln Sie mehrere Aufträge an in.php und fragen Sie jede id unabhängig an res.php ab. Für Scraping mit hohem Volumen skalieren Sie einfach über die Thread-Anzahl Ihres Tarifs.

Wie lange ist ein gelöstes Token gültig?

Etwa zwei Minuten. reCAPTCHA-v2-Tokens laufen rund 120 Sekunden nach der Ausstellung ab. Fügen Sie das Token deshalb sofort nach Erhalt ein und senden Sie das Formular ab – lösen Sie es niemals auf Vorrat.

Warum lehnt die Seite ein technisch gültiges Token ab?

Fast immer liegt es an der Einfügung, nicht an der API. Prüfen Sie, ob die Seite tatsächlich das Feld g-recaptcha-response erwartet oder stattdessen einen data-callback aufruft, ob das Widget in einem iframe liegt und ob Cookies und User-Agent zwischen Anforderung und Einreichung identisch bleiben.

Brauche ich einen Browser, um das Token einzureichen?

Nein. Ohne Browser hängen Sie das Token einfach als Feld g-recaptcha-response an den POST-Request an, den das Formular ohnehin auslöst. Selenium, Puppeteer oder Playwright brauchen Sie nur, wenn die Seite den Flow über JavaScript oder einen Callback steuert.

Verwandte Leitfäden

• CaptchaAI Schnellstart
• Cloudflare Turnstile per API lösen
• Häufige Fehler bei reCAPTCHA v2