CaptchaAI API-Kurzreferenzkarte

Zwei Endpunkte, eine Handvoll Pflichtfelder je CAPTCHA-Typ, elf Fehlercodes – mehr Oberfläche hat die CaptchaAI-API nicht. Zeit kostet die Detailsuche: Heißt das Feld googlekey oder sitekey, wie lange warten Sie vor der ersten Statusabfrage? Diese Seite ist zum Überfliegen gebaut.

Der Ablauf in zwei Anfragen

1. Übermitteln: POST an in.php mit key, method und den typspezifischen Feldern. Zurück kommt eine Task-ID.
2. Abfragen: GET an res.php mit action=get&id=TASK_ID, bis statt CAPCHA_NOT_READY ein Token oder ein Text erscheint.

Dazwischen liegt die Lösungszeit – deshalb nicht sofort abfragen.

Abgerechnet wird pro Thread, nicht pro Lösung: Ein Thread ist eine gleichzeitig laufende Aufgabe. BASIC (15 $/Monat, 5 Threads) verarbeitet fünf Aufgaben parallel, ADVANCE (90 $/Monat, 50 Threads) fünfzig.

API-Endpunkte und Authentifizierung

Jede Anfrage trägt key=YOUR_API_KEY – im Query-String oder im POST-Body. Header-Authentifizierung, Sitzung und Token-Refresh entfallen. Für JSON statt Pipe-Notation setzen Sie json=1.

Pflichtfelder und Zusatzparameter beim Übermitteln

*Bei Bild- und OCR-CAPTCHAs entfällt pageurl, weil kein Seitenkontext ausgewertet wird.

Feinsteuerung für Bild- und OCR-CAPTCHAs

Je enger der Zeichenraum, desto stabiler das Ergebnis: Bei Zifferncodes lohnt sich numeric=1 mit minLen und maxLen.

Abgedeckte CAPTCHA-Typen

Zwölf Typen sind generell verfügbar, drei laufen in Beta. Was fehlt, wird nicht unterstützt.

API-Methoden je CAPTCHA-Typ

reCAPTCHA v2

method=userrecaptcha
googlekey=SITE_KEY
pageurl=PAGE_URL

Für die unsichtbare Variante invisible=1 ergänzen; googlekey steht im data-sitekey-Attribut des Widgets.

reCAPTCHA v3

method=userrecaptcha
googlekey=SITE_KEY
pageurl=PAGE_URL
version=v3
action=ACTION_NAME

action muss dem Aktionsnamen der Seite exakt entsprechen – ein falscher Wert senkt den Score, ohne Fehler.

reCAPTCHA Enterprise

method=userrecaptcha
googlekey=SITE_KEY
pageurl=PAGE_URL
enterprise=1

Cloudflare Turnstile

method=turnstile
sitekey=SITE_KEY
pageurl=PAGE_URL

Der zurückgegebene Wert gehört in das Formularfeld cf-turnstile-response.

Cloudflare Challenge

method=cloudflare_challenge
sitekey=SITE_KEY
pageurl=PAGE_URL

Gemeint ist die vorgeschaltete Interstitial-Seite, nicht das Widget.

GeeTest v3

method=geetest
gt=GT_VALUE
challenge=CHALLENGE_VALUE
pageurl=PAGE_URL
api_server=API_SERVER  (optional)

gt und challenge stammen aus dem Initialisierungs-Request. challenge gilt nur einmal.

GeeTest v4 – noch nicht verfügbar

method=geetest
gt=CAPTCHA_ID
pageurl=PAGE_URL
version=4

GeeTest v4 wird derzeit nicht unterstützt, sondern nur als „bald verfügbar“ geführt.

BLS CAPTCHA

method=bls
sitekey=SITE_KEY
pageurl=PAGE_URL
instructions=INSTRUCTIONS  (optional)
code=CODE  (optional)

Vor allem für Terminportale relevant, im DACH-Raum ein häufiger Anwendungsfall. instructions und code sind optional.

Bild-CAPTCHA als Base64

method=base64
body=BASE64_STRING

Bild-CAPTCHA als Datei-Upload

method=post
[email protected]  (multipart)

Beide Wege führen zum selben Ergebnis; das Limit liegt jeweils bei 100 KB.

Antwort auf die Übermittlung

Erfolgsfall

OK|TASK_ID

Mit json=1:

{"status": 1, "request": "TASK_ID"}

Fehlerfall

ERROR_KEY_DOES_NOT_EXIST

Als JSON:

{"status": 0, "request": "ERROR_KEY_DOES_NOT_EXIST"}

Hinter dem Pipe-Zeichen steht die Task-ID – protokollieren Sie sie vor der Warteschleife.

Ergebnis abfragen

GET https://ocr.captchaai.com/res.php?key=KEY&action=get&id=TASK_ID

Noch in Bearbeitung

CAPCHA_NOT_READY

Erfolgsfall

OK|TOKEN_OR_TEXT

Fehlerfall

ERROR_CAPTCHA_UNSOLVABLE

Achten Sie auf die Schreibweise CAPCHA_NOT_READY – ohne „T“. Ein Vergleich gegen CAPTCHA_NOT_READY trifft nie zu.

Polling in der Praxis

Das Muster deckt beide Schritte ab:

import time
import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://ocr.captchaai.com"

def solve_captcha(submit_params):
    submit_params["key"] = API_KEY
    submit_params["json"] = 1

    resp = requests.post(f"{BASE}/in.php", data=submit_params)
    data = resp.json()

    if data["status"] != 1:
        raise Exception(f"Submit error: {data['request']}")

    task_id = data["request"]

    # Wait before first poll
    time.sleep(10)

    for _ in range(60):
        result = requests.get(
            f"{BASE}/res.php",
            params={"key": API_KEY, "action": "get", "id": task_id, "json": 1}
        ).json()

        if result["request"] == "CAPCHA_NOT_READY":
            time.sleep(5)
            continue

        if result["status"] == 1:
            return result["request"]

        raise Exception(f"Solve error: {result['request']}")

    raise TimeoutError("CAPTCHA solve timed out")

Richtwerte für die Zeitsteuerung:

Grundregel: erst warten, dann fragen. Häufen sich ERROR_NO_SLOT_AVAILABLE-Antworten, hilft exponentielles Backoff.

Guthaben prüfen

balance = requests.get(
    f"{BASE}/res.php",
    params={"key": API_KEY, "action": "getbalance"}
).text
print(f"Balance: ${balance}")

Der Endpunkt gibt eine reine Zahl zurück. Stündlich protokollieren und unterhalb einer Schwelle alarmieren – ERROR_ZERO_BALANCE im Nachtlauf kostet mehr Zeit als jede Vorwarnung.

Fehlercodes nachschlagen

Faustregel: Codes mit KEY oder BALANCE betreffen das Konto und lösen sich durch Wiederholen nicht auf – die übrigen sind meist vorübergehend.

Praxisbeispiel: nächtlicher Datenabgleich auf einem Hetzner-Server

Ein Berliner Team gleicht nachts öffentlich zugängliche Produktdaten mehrerer Lieferantenportale ab – als GitLab-CI-Pipeline auf einem Hetzner-VPS. Unterwegs stehen reCAPTCHA v2 an zwei Anmeldeseiten und Cloudflare Turnstile an einer dritten. Die Umsetzung folgt dieser Karte eins zu eins: method=userrecaptcha mit googlekey und pageurl, method=turnstile mit sitekey, dazu ein gemeinsamer Wrapper mit dem Polling-Muster.

Zwei Punkte für die Planung: Abgerechnet wird in US-Dollar, nicht in Euro. Und fallen personenbezogene Daten an – IP-Adressen zählen nach DSGVO dazu –, gehört die Rechtsgrundlage vor den ersten Produktivlauf.

Häufige Fragen

Warum liefert res.php dauerhaft CAPCHA_NOT_READY?

Meist wird zu früh abgefragt: 10 Sekunden warten, bei reCAPTCHA v3 20, danach 5 Sekunden je Durchlauf. Bleibt der Status bis zum Timeout, stimmt meist pageurl oder der Sitekey nicht.

Wie viele Aufgaben kann ich gleichzeitig übermitteln?

So viele, wie Ihr Plan an Threads bereitstellt: BASIC (15 $/Monat) fünf, STANDARD (30 $/Monat) fünfzehn, ADVANCE (90 $/Monat) fünfzig. Eine abgeschlossene Lösung gibt den Thread sofort wieder frei.

Wie reagiere ich richtig auf ERROR_NO_SLOT_AVAILABLE?

Kurz warten und erneut übermitteln – nach etwa 5 Sekunden, bei Wiederholung mit exponentiellem Backoff. Den Lauf abzubrechen ist selten nötig.

Welche CAPTCHA-Typen deckt die API ab – und welche nicht?

Die Tabelle oben ist die maßgebliche Liste: zwölf Typen generell verfügbar, dazu CaptchaFox (Beta), Friendly Captcha (Beta) und Lemin (Beta). hCaptcha und FunCaptcha (Arkose Labs) gehören nicht dazu; GeeTest v4 ist als bald verfügbar angekündigt.

Worin unterscheidet sich der v3-Aufruf vom v2-Aufruf?

Nur in zwei Feldern: version=v3 und action=ACTION_NAME; die Methode bleibt userrecaptcha. Planen Sie bei v3 eine längere erste Wartezeit ein.

Weiterführende Artikel

• Antwortformate und Fehlercodes im Detail
• Schnelleinstieg mit dem ersten API-Aufruf

Schlüssel holen, Aufgabe an in.php übermitteln, Token einsetzen – API-Schlüssel anlegen.