cURL + CaptchaAI: CLI-CAPTCHA-Lösung

curl ist auf jedem Linux- und macOS-System vorinstalliert und seit Windows 10 auch dort verfügbar – damit lässt sich die CaptchaAI-API ohne eine Zeile Anwendungscode ansprechen. Hängt eine Integration in Python oder Node.js, klärt ein einzelner Aufruf im Terminal in Sekunden, ob API-Schlüssel, Sitekey und Page-URL stimmen – oder ob der Fehler im eigenen Code liegt.

Dieser Leitfaden zeigt cURL in drei Rollen: als Prüfwerkzeug für die API, als Baustein für Shell-Skripte und als kleinsten gemeinsamen Nenner in CI-Runnern und schlanken Containern ohne Python oder Node.js.

Was Sie brauchen

Die API antwortet standardmäßig im Klartext nach dem Muster OK|…, deshalb kommen alle Beispiele hier ohne zusätzliche Werkzeuge aus. Erst wenn Sie json=1 anhängen, lohnt sich ein JSON-Parser in der Pipeline.

So lösen Sie ein CAPTCHA per cURL in zwei Schritten

Jeder Vorgang folgt demselben Muster: Aufgabe übermitteln, Task-ID erhalten, Status abfragen, Token weiterverwenden. Das gilt für reCAPTCHA v2 genauso wie für Cloudflare Turnstile oder ein Bild-CAPTCHA – nur der Parameter method ändert sich.

Guthaben prüfen

curl -s "https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=getbalance"

Ausgabe: 1.234

Dieser Aufruf ist der schnellste Test, ob der Schlüssel überhaupt akzeptiert wird. Kommt hier bereits ein Fehlercode zurück, ist jede weitere Fehlersuche im Skript verlorene Zeit.

reCAPTCHA v2 übermitteln

curl -s "https://ocr.captchaai.com/in.php?key=YOUR_API_KEY&method=userrecaptcha&googlekey=6Le-wvkS...&pageurl=https://example.com"

Ausgabe: OK|73548291

googlekey ist der Sitekey aus dem HTML der Zielseite, pageurl die vollständige Adresse der Seite inklusive https://. Die Zahl hinter dem senkrechten Strich ist die Task-ID für den nächsten Schritt.

Ergebnis abfragen

curl -s "https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=get&id=73548291"

Ausgabe: OK|03AGdBq24PBCbw... oder CAPCHA_NOT_READY

Solange die Lösung läuft, antwortet die API mit CAPCHA_NOT_READY – so geschrieben, ohne „T“, das ist kein Tippfehler im Skript. Fragen Sie das erste Ergebnis nach etwa 15 Sekunden ab und danach im Fünf-Sekunden-Takt. Cloudflare Turnstile liegt üblicherweise unter 10 Sekunden, reCAPTCHA v2 unter 60 Sekunden.

Wiederverwendbares Solver-Skript für die Shell

Zum Ausprobieren reicht der Einzeiler, für Cron-Jobs und Pipelines brauchen Sie Fehlerbehandlung und ein Timeout. Das folgende Skript kapselt beides in eine Funktion.

Erstellen Sie solve_captcha.sh:

#!/bin/bash
set -euo pipefail

API_KEY="${CAPTCHAAI_API_KEY:?Set CAPTCHAAI_API_KEY environment variable}"
BASE_URL="https://ocr.captchaai.com"

solve_recaptcha() {
    local site_key="$1"
    local page_url="$2"
    local timeout="${3:-300}"

    # Submit
    local response
    response=$(curl -s "${BASE_URL}/in.php?key=${API_KEY}&method=userrecaptcha&googlekey=${site_key}&pageurl=${page_url}")

    if [[ ! "$response" == OK|* ]]; then
        echo "ERROR: Submit failed: $response" >&2
        return 1
    fi

    local task_id="${response#OK|}"
    echo "Submitted task: $task_id" >&2

    # Poll
    local deadline=$((SECONDS + timeout))
    while (( SECONDS < deadline )); do
        sleep 5
        local result
        result=$(curl -s "${BASE_URL}/res.php?key=${API_KEY}&action=get&id=${task_id}")

        if [[ "$result" == "CAPCHA_NOT_READY" ]]; then
            echo "Waiting..." >&2
            continue
        fi

        if [[ "$result" == OK|* ]]; then
            echo "${result#OK|}"
            return 0
        fi

        echo "ERROR: Solve failed: $result" >&2
        return 1
    done

    echo "ERROR: Timeout after ${timeout}s" >&2
    return 1
}

# Usage: ./solve_captcha.sh SITE_KEY PAGE_URL
if [[ $# -ge 2 ]]; then
    solve_recaptcha "$1" "$2"
fi

Machen Sie es ausführbar:

chmod +x solve_captcha.sh

Ausführen:

export CAPTCHAAI_API_KEY="your_key_here"
./solve_captcha.sh "6Le-wvkS..." "https://example.com"

Drei Details lohnen einen zweiten Blick:

• set -euo pipefail sorgt dafür, dass ein fehlgeschlagener Aufruf den Job abbricht, statt mit leerem Token weiterzulaufen.
• Statusmeldungen gehen nach stderr, ausschließlich das Token nach stdout. Nur deshalb liefert $(./solve_captcha.sh …) einen sauberen Wert.
• Das Timeout von 300 Sekunden gilt für den gesamten Vorgang; in CI-Jobs ist ein kürzerer Wert meist sinnvoller.

Cloudflare Turnstile per cURL lösen

curl -s "https://ocr.captchaai.com/in.php?key=${CAPTCHAAI_API_KEY}&method=turnstile&sitekey=0x4AAAAA...&pageurl=https://example.com"

Gegenüber reCAPTCHA ändern sich genau zwei Dinge: method=turnstile und sitekey statt googlekey. Das Abfragen bleibt identisch, das Token gehört in das Feld cf-turnstile-response.

Bild-CAPTCHAs: base64 oder Datei-Upload

# Encode image to base64
IMAGE_B64=$(base64 -w 0 captcha.png)

# Submit
curl -s "https://ocr.captchaai.com/in.php?key=${CAPTCHAAI_API_KEY}&method=base64&body=${IMAGE_B64}"

Wichtig ist -w 0: Ohne diesen Schalter fügt GNU base64 Zeilenumbrüche ein und die Übermittlung scheitert. Unter macOS heißt das Gegenstück base64 -i captcha.png.

Für große Bilder verwenden Sie POST:

curl -s -X POST "https://ocr.captchaai.com/in.php" \
  -F "key=${CAPTCHAAI_API_KEY}" \
  -F "method=post" \
  -F "[email protected]"

Der Multipart-Upload umgeht die Längenbegrenzung von URLs und ist bei Screenshots die robustere Variante. Bild- und OCR-Aufgaben werden typischerweise in unter 0,5 Sekunden beantwortet, Rasterbild-CAPTCHAs in unter 1 Sekunde.

Token in das Formular übernehmen

#!/bin/bash
# Solve CAPTCHA and submit form in one pipeline

API_KEY="${CAPTCHAAI_API_KEY}"
SITE_KEY="6Le-wvkS..."
TARGET_URL="https://example.com/login"

# Solve
TOKEN=$(./solve_captcha.sh "$SITE_KEY" "$TARGET_URL")

if [[ -z "$TOKEN" ]]; then
    echo "Failed to solve CAPTCHA"
    exit 1
fi

# Submit form with token
curl -s -X POST "$TARGET_URL" \
  -d "username=user" \
  -d "password=pass" \
  -d "g-recaptcha-response=${TOKEN}"

Das gelöste Token wird wie ein ganz normales Formularfeld mitgesendet, bei reCAPTCHA als g-recaptcha-response. Lösen Sie es unmittelbar vor dem Absenden: Ein Token ist nur rund 120 Sekunden gültig, es auf Vorrat zu halten bringt also nichts. Steht im Skript noch ein langer Vorbereitungsschritt an, verschieben Sie den Löseaufruf ans Ende.

Mehrere CAPTCHAs stapelweise per Shell-Skript lösen

#!/bin/bash
# Input file: urls.txt (one URL per line)

while IFS= read -r url; do
    echo "Processing: $url"
    TOKEN=$(./solve_captcha.sh "6Le-wvkS..." "$url")
    if [[ -n "$TOKEN" ]]; then
        echo "$url,$TOKEN" >> results.csv
        echo "  Solved ✓"
    else
        echo "  Failed ✗"
    fi
done < urls.txt

Diese Schleife arbeitet streng nacheinander. Wer Durchsatz braucht, startet mehrere Aufrufe mit & im Hintergrund und begrenzt die Zahl gleichzeitiger Jobs auf die Threads des eigenen Tarifs. CaptchaAI rechnet nämlich pro gleichzeitigem Thread ab, nicht pro Lösung: BASIC kostet 15 $ pro Monat und erlaubt 5 parallele Aufgaben, ADVANCE 90 $ bei 50 Threads, ENTERPRISE 300 $ bei 200 Threads. Die Zahl der Lösungen pro Thread ist dabei nicht gedeckelt. Alle Preise verstehen sich in US-Dollar.

PowerShell unter Windows

$ApiKey = $env:CAPTCHAAI_API_KEY
$BaseUrl = "https://ocr.captchaai.com"

# Submit
$response = Invoke-RestMethod "${BaseUrl}/in.php?key=${ApiKey}&method=userrecaptcha&googlekey=6Le-wvkS...&pageurl=https://example.com"

if ($response -match '^OK\|(.+)$') {
    $taskId = $Matches[1]
    Write-Host "Task: $taskId"
} else {
    Write-Error "Submit failed: $response"
    exit 1
}

# Poll
do {
    Start-Sleep -Seconds 5
    $result = Invoke-RestMethod "${BaseUrl}/res.php?key=${ApiKey}&action=get&id=${taskId}"
} while ($result -eq 'CAPCHA_NOT_READY')

if ($result -match '^OK\|(.+)$') {
    $token = $Matches[1]
    Write-Host "Token: $token"
} else {
    Write-Error "Solve failed: $result"
}

In Windows PowerShell 5.1 ist curl ein Alias für Invoke-WebRequest und akzeptiert die gewohnten cURL-Schalter nicht. Rufen Sie deshalb curl.exe mit vollem Namen auf oder nutzen Sie Invoke-RestMethod wie oben.

Schlüsselverwaltung in CI/CD

Ein Beispiel aus der Praxis: Ein Team in Köln prüft jede Nacht, ob das Login der eigenen Staging-Umgebung noch funktioniert. Der Job läuft in GitLab CI auf einem kleinen Hetzner-Server, das Solver-Skript liegt im Repository, der API-Schlüssel nicht. Er wird als maskierte CI-Variable CAPTCHAAI_API_KEY hinterlegt und zur Laufzeit exportiert – genauso funktioniert das mit GitHub Actions, Jenkins oder einem schlichten Cron-Eintrag auf dem Server.

Zwei Gewohnheiten sparen dabei Ärger: set -x im Debug-Modus wieder abschalten, weil der Schlüssel Teil der Abfrage-URL ist und sonst im Job-Log landet, und vor dem eigentlichen Durchlauf einmal action=getbalance aufrufen. Wenn Ihre Protokolle Page-URLs oder IP-Adressen mitschreiben, gehören sie außerdem in Ihr Löschkonzept – IP-Adressen gelten nach DSGVO als personenbezogene Daten.

Fehlerbehebung

FAQ

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

Rund 120 Sekunden, danach weist die Zielseite es ab. Bauen Sie Ihr Skript deshalb so, dass der Löseaufruf der letzte Schritt vor dem Absenden ist und nicht der erste einer langen Kette.

Warum antwortet res.php dauerhaft mit CAPCHA_NOT_READY?

Meist wird zu früh abgefragt. Die erste Abfrage gehört etwa 15 Sekunden nach der Übermittlung, weitere folgen im Fünf-Sekunden-Takt; reCAPTCHA v2 darf bis zu 60 Sekunden brauchen. Kommt nach Ablauf des Timeouts ein Fehlercode, liegt es an den Parametern, nicht an der Wartezeit.

Funktioniert das auch in schlanken Containern und unter Windows?

Ja. In Alpine-Images installieren Sie curl per apk add curl; da dort standardmäßig ash statt bash läuft, brauchen Sie zusätzlich apk add bash oder passen die Shebang-Zeile an. Unter Windows bringt das System seit Windows 10 curl.exe mit, alternativ nutzen Sie die PowerShell-Variante oben.

Lassen sich hCaptcha oder FunCaptcha auf demselben Weg verarbeiten?

Nein, CaptchaAI unterstützt hCaptcha und FunCaptcha nicht, und GeeTest v4 ist bislang nur als „bald verfügbar“ angekündigt. Per cURL erreichbar sind unter anderem reCAPTCHA v2 und v3 (auch Enterprise), Cloudflare Turnstile und Cloudflare Challenge, GeeTest v3, Bild- und Rasterbild-CAPTCHAs sowie BLS; CaptchaFox, Friendly Captcha und Lemin befinden sich in der Beta.

Wie halte ich den API-Schlüssel aus den Logs heraus?

Der Schlüssel steht im Query-String und taucht damit in jeder Trace-Ausgabe auf. Übergeben Sie ihn nur über eine Umgebungsvariable, verzichten Sie auf set -x, und protokollieren Sie ausschließlich die Task-ID.

Verwandte Leitfäden

• Axios + CaptchaAI: CAPTCHAs ohne Browser lösen
• API-Schlüssel einrichten und authentifizieren
• Antwortformate der API verstehen