Cloudflare Turnstile per API lösen

Wenn Ihre Automatisierung an einem Cloudflare-Turnstile-Widget hängen bleibt, brauchen Sie genau eine Sache: einen gültigen cf-turnstile-response-Token. Turnstile zeigt selten ein sichtbares Rätsel – es wertet im Hintergrund Browser-Signale aus und gibt still einen Token aus, den das Backend der Zielseite prüft. Genau diesen Token liefert die CaptchaAI-API, ohne dass Sie einen echten Browser durch die Abfrage steuern müssen.

Diese Anleitung führt Sie in vier Schritten durch den kompletten Ablauf – Sitekey extrahieren, Aufgabe übermitteln, Ergebnis abfragen und Token einsetzen:

• Schritt 1: den öffentlichen Sitekey aus der Zielseite lesen.
• Schritt 2: eine Solve-Aufgabe an CaptchaAI übermitteln.
• Schritt 3: das Ergebnis abfragen, bis der Token vorliegt.
• Schritt 4: den Token in das Formular einsetzen und absenden.

Falls Ihnen der grundlegende Vier-Schritte-Rhythmus der API noch nicht vertraut ist, beginnen Sie mit dem CaptchaAI Schnellstart – dort ist der allgemeine Ablauf einmal von Grund auf beschrieben.

Voraussetzungen

Schritt 1: Den Turnstile-Sitekey extrahieren

Der Sitekey ist öffentlich und steht direkt im HTML der Seite – meist in einem div- oder script-Tag:

<div class="cf-turnstile" data-sitekey="0x4AAAAAAAC3DHQFLr1GavNl"></div>

Oder per JavaScript gerendert:

turnstile.render('#widget', {
  sitekey: '0x4AAAAAAAC3DHQFLr1GavNl',
  callback: function(token) { /* ... */ }
});

Drei zuverlässige Wege, ihn zu finden:

1. Browser-DevTools – im Tab „Elements" nach data-sitekey oder cf-turnstile suchen.
2. Seitenquelltext – mit Strg+U öffnen und nach Zeichenketten suchen, die mit 0x beginnen.
3. Network-Tab – auf challenges.cloudflare.com filtern; der Sitekey steckt in den Request-Parametern.

Ein Turnstile-Sitekey beginnt immer mit 0x und ist in der Regel 22 Zeichen lang. Daran erkennen Sie ihn sicher – reCAPTCHA-Keys starten dagegen mit 6L.

Schritt 2: Die Aufgabe an CaptchaAI übermitteln

Senden Sie Sitekey und Seiten-URL per POST an https://ocr.captchaai.com/in.php mit method=turnstile:

import requests

API_KEY = "YOUR_CAPTCHAAI_KEY"
SITEKEY = "0x4AAAAAAAC3DHQFLr1GavNl"
PAGEURL = "https://example.com/login"

r = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": API_KEY,
    "method": "turnstile",
    "sitekey": SITEKEY,
    "pageurl": PAGEURL,
    "json": 1,
})
data = r.json()
if data["status"] != 1:
    raise RuntimeError(f"submit failed: {data}")
task_id = data["request"]
print("task id:", task_id)

Dasselbe in Node.js:

const axios = require("axios");

const { data } = await axios.post("https://ocr.captchaai.com/in.php", null, {
  params: {
    key: process.env.CAPTCHAAI_KEY,
    method: "turnstile",
    sitekey: "0x4AAAAAAAC3DHQFLr1GavNl",
    pageurl: "https://example.com/login",
    json: 1,
  },
});
if (data.status !== 1) throw new Error(`submit failed: ${JSON.stringify(data)}`);
const taskId = data.request;

Bei Erfolg antwortet die API mit {"status": 1, "request": "<task_id>"}. Merken Sie sich die task_id – sie identifiziert Ihre Aufgabe beim anschließenden Polling.

Schritt 3: Das Ergebnis abfragen (Polling)

Turnstile löst CaptchaAI in der Regel in unter 10 Sekunden. Ein kleiner Sicherheitspuffer schadet trotzdem nicht: Warten Sie zunächst 10 Sekunden und fragen Sie den Status danach alle 5 Sekunden ab, höchstens 40 Durchläufe lang.

import time

time.sleep(10)
for _ in range(40):
    r = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": API_KEY,
        "action": "get",
        "id": task_id,
        "json": 1,
    })
    res = r.json()
    if res["status"] == 1:
        token = res["request"]
        break
    if res["request"] != "CAPCHA_NOT_READY":
        raise RuntimeError(f"solver error: {res}")
    time.sleep(5)
else:
    raise TimeoutError("turnstile solving timed out")

print("token (erste 60 Zeichen):", token[:60])

Solange die Lösung noch läuft, liefert die API CAPCHA_NOT_READY – das ist kein Fehler, sondern das Signal, weiter abzufragen. Der zurückgegebene Token ist ein Base64-String, der meist mit 0. beginnt und 400–600 Zeichen lang ist.

Schritt 4: Den Token in das Formularfeld einfügen

Sobald der Token vorliegt, schreiben Sie ihn in das versteckte Feld cf-turnstile-response des Turnstile-Formulars und senden das Formular ab.

Selenium:

driver.execute_script(
    "document.querySelector('[name=cf-turnstile-response]').value = arguments[0];",
    token,
)
driver.find_element("css selector", "form").submit()

Playwright:

page.evaluate(
    "(t) => document.querySelector('[name=cf-turnstile-response]').value = t",
    token,
)
page.click("button[type=submit]")

Bei reinem HTTP hängen Sie cf-turnstile-response=<token> an den application/x-www-form-urlencoded-Body der Anfrage an.

Ein Turnstile-Token lebt nur etwa 120–300 Sekunden. Setzen Sie ihn sofort ein – sonst antwortet das Backend mit timeout-or-duplicate, und Sie müssen neu lösen.

Vollständiges Python-Beispiel

Alle vier Schritte in einer wiederverwendbaren Funktion – von der Übermittlung bis zum fertigen Token:

import os, time, requests

API = "https://ocr.captchaai.com"
KEY = os.environ["CAPTCHAAI_KEY"]

def solve_turnstile(sitekey: str, pageurl: str) -> str:
    r = requests.post(f"{API}/in.php", data={
        "key": KEY, "method": "turnstile",
        "sitekey": sitekey, "pageurl": pageurl, "json": 1,
    }, timeout=30)
    j = r.json()
    if j["status"] != 1:
        raise RuntimeError(f"submit: {j}")
    tid = j["request"]

    time.sleep(10)
    for _ in range(40):
        r = requests.get(f"{API}/res.php", params={
            "key": KEY, "action": "get", "id": tid, "json": 1,
        }, timeout=30)
        j = r.json()
        if j["status"] == 1:
            return j["request"]
        if j["request"] != "CAPCHA_NOT_READY":
            raise RuntimeError(f"poll: {j}")
        time.sleep(5)
    raise TimeoutError("timeout")

if __name__ == "__main__":
    print(solve_turnstile("0x4AAAAAAAC3DHQFLr1GavNl", "https://example.com/login"))

Was das Lösen von Turnstile kostet

CaptchaAI rechnet pro Thread ab, nicht pro Lösung. Ein Thread ist eine gerade laufende CAPTCHA-Abfrage; sobald sie fertig ist, nimmt derselbe Thread die nächste. Innerhalb eines Tarifs gibt es keine Tageslimits und keinen Aufpreis nach CAPTCHA-Typ.

Für ein typisches DACH-Szenario – etwa ein Monitoring-Skript, das stündlich Preise hinter einem Turnstile-Widget abfragt und auf einem Hetzner- oder netcup-Server läuft – reicht der Einstiegstarif deutlich aus: BASIC (15 $/Monat, 5 Threads) löst bis zu fünf Turnstile-Abfragen gleichzeitig. Wächst die Last, skalieren Sie über STANDARD (30 $/Monat, 15 Threads) oder ADVANCE (90 $/Monat, 50 Threads) nach oben. Die aktuellen Tarife finden Sie unter captchaai.com/pricing; alle Preise sind in US-Dollar.

Häufige Fehler und ihre Ursachen

Die vollständige Fehlertabelle finden Sie in der Anleitung zu reCAPTCHA v2 – die Fehlercodes sind über alle CAPTCHA-Typen hinweg identisch.

Wenn Turnstile nicht durchgeht

Vier Ursachen erklären fast jeden fehlgeschlagenen Solve. Prüfen Sie sie in dieser Reihenfolge:

Der Sitekey ändert sich pro Aufruf

Manche Cloudflare-Seiten geben bei jedem Laden einen neuen Sitekey aus. Scrapen Sie ihn deshalb direkt vor jeder Aufgabe frisch, statt einen gespeicherten Wert wiederzuverwenden.

Die pageurl passt nicht exakt

Das Turnstile-Backend vergleicht die URL streng. Senden Sie den exakten Pfad, auf dem das Widget erscheint – ohne angehängten Query-String.

Cloudflare lehnt den Client an der TLS-Signatur ab

Ein nackter HTTP-Client fällt hier schneller auf als ein echter Browser. Ein Vollbrowser (Playwright) oder eine Bibliothek wie curl_cffi liefert stabilere Ergebnisse.

Der Token ist abgelaufen oder die Proxy-Qualität ist schlecht

Verwenden Sie jeden Token innerhalb von zwei Minuten. Günstige Rechenzentrums-IPs lösen zudem oft zusätzliche Abfragen aus – Residential- oder Mobile-Proxys sind meist stabiler. Beachten Sie dabei: In der EU gelten IP-Adressen als personenbezogene Daten, prüfen Sie für produktive Scraping-Workflows also die datenschutzrechtliche Grundlage (DSGVO).

Häufige Fragen

Woran erkenne ich einen Turnstile-Sitekey?

An zwei Merkmalen: Er beginnt mit 0x und ist meist 22 Zeichen lang. Im HTML steht er als data-sitekey in einem Element mit der Klasse cf-turnstile oder im Aufruf von turnstile.render(...).

Warum lehnt die Zielseite meinen Token mit timeout-or-duplicate ab?

Weil der Token entweder abgelaufen ist oder bereits verwendet wurde. Ein Turnstile-Token gilt nur wenige Minuten und lässt sich nur einmal einlösen. Lösen Sie kurz vor dem Absenden des Formulars und geben Sie jeden Token genau einmal weiter.

Kann ich Turnstile ohne echten Browser lösen?

Ja. Der API genügen Sitekey und Seiten-URL – zum Lösen selbst ist kein Headless- oder Vollbrowser nötig. Erst beim Einsetzen des Tokens hilft ein Browser (Selenium, Playwright), falls die Seite das Formular clientseitig weiterverarbeitet.

Wie viele Turnstile-Abfragen kann ich parallel lösen?

So viele, wie Ihr Tarif Threads hat. Mit 5 Threads (BASIC) laufen fünf Lösungen gleichzeitig; jede fertige Lösung gibt ihren Thread sofort für die nächste Abfrage frei.

Verwandte Leitfäden

• So funktioniert die Cloudflare Challenge