AZCaptcha zu CaptchaAI migrieren: Anleitung in 4 Schritten

Der Wechsel von AZCaptcha zu CaptchaAI ist in den meisten Codebasen eine Sache von Minuten, nicht von Tagen. Beide Dienste sprechen dasselbe 2Captcha-kompatible API-Format: Sie tauschen im Kern zwei Basis-URLs und einen API-Schlüssel aus, Parameternamen und Antwortformat bleiben gleich. Dieser Leitfaden zeigt die Umstellung in vier Schritten.

Vor dem Umstieg: Aufwand und Risiko einschätzen

Für eine einzelne Codebasis ist der Wechsel meist in 15 bis 30 Minuten erledigt – der Großteil davon ist Suchen-und-Ersetzen der Basis-URL plus ein paralleler Testlauf zur Absicherung. Vier Punkte sollten Sie vorab kennen:

• Gleiches API-Format: Beide Dienste sind 2Captcha-kompatibel; Parameternamen und Antwortstruktur bleiben identisch.
• Zwei echte Änderungen: die Host-Domain in der Request-URL und der API-Schlüssel – idealerweise aus einer Umgebungsvariablen statt fest im Code.
• Reversibel: Solange Sie den alten Schlüssel behalten, ist ein Rollback ein Einzeiler (siehe Schritt 3).
• Abrechnung: CaptchaAI rechnet Thread-basiert ab, nicht pro Lösung – die Kostenrechnung folgt also einer anderen Logik als ein reines Pay-per-Solve-Modell.

Konkret läuft die Umstellung in vier Schritten vom neuen Konto bis zum umgeschalteten Produktionsverkehr. Die vollständige Endpunkt- und Parameterzuordnung folgt anschließend als Referenz zum Nachschlagen.

Migration in vier Schritten

Schritt 1: CaptchaAI-API-Schlüssel anlegen

1. Registrieren Sie sich unter captchaai.com
2. Laden Sie Guthaben auf Ihr Konto
3. Kopieren Sie Ihren API-Schlüssel aus dem Dashboard

Schritt 2: Basis-URL und Schlüssel im Code austauschen

Die Umstellung betrifft zwei Zeilen pro Aufruf: die Request-URL und den Schlüssel, den Sie jetzt aus einer Umgebungsvariablen lesen.

Python – Vorher (AZCaptcha)

import requests

API_KEY = "your_azcaptcha_key"

def solve_recaptcha(sitekey, pageurl):
    # Submit
    resp = requests.post("https://azcaptcha.com/in.php", data={
        "key": API_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": pageurl,
        "json": 1
    })
    data = resp.json()
    if data["status"] != 1:
        return {"error": data["request"]}

    captcha_id = data["request"]

    # Poll
    import time
    for _ in range(60):
        time.sleep(5)
        result = requests.get("https://azcaptcha.com/res.php", params={
            "key": API_KEY, "action": "get", "id": captcha_id, "json": 1
        }).json()
        if result["status"] == 1:
            return {"solution": result["request"]}
        if result["request"] != "CAPCHA_NOT_READY":
            return {"error": result["request"]}

    return {"error": "TIMEOUT"}

Python – Nachher (CaptchaAI)

import os
import time
import requests

API_KEY = os.environ["CAPTCHAAI_API_KEY"]  # Changed: use env var

def solve_recaptcha(sitekey, pageurl):
    # Submit — only URL changed
    resp = requests.post("https://ocr.captchaai.com/in.php", data={
        "key": API_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": pageurl,
        "json": 1
    })
    data = resp.json()
    if data.get("status") != 1:
        return {"error": data.get("request")}

    captcha_id = data["request"]

    # Poll — only URL changed
    for _ in range(60):
        time.sleep(5)
        result = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": API_KEY, "action": "get", "id": captcha_id, "json": 1
        }).json()
        if result.get("status") == 1:
            return {"solution": result["request"]}
        if result.get("request") != "CAPCHA_NOT_READY":
            return {"error": result.get("request")}

    return {"error": "TIMEOUT"}

JavaScript – Vorher (AZCaptcha)

const axios = require("axios");
const API_KEY = "your_azcaptcha_key";

async function solveRecaptcha(sitekey, pageurl) {
  const submit = await axios.post("https://azcaptcha.com/in.php", null, {
    params: { key: API_KEY, method: "userrecaptcha", googlekey: sitekey, pageurl, json: 1 },
  });
  if (submit.data.status !== 1) return { error: submit.data.request };

  const captchaId = submit.data.request;
  for (let i = 0; i < 60; i++) {
    await new Promise((r) => setTimeout(r, 5000));
    const poll = await axios.get("https://azcaptcha.com/res.php", {
      params: { key: API_KEY, action: "get", id: captchaId, json: 1 },
    });
    if (poll.data.status === 1) return { solution: poll.data.request };
    if (poll.data.request !== "CAPCHA_NOT_READY") return { error: poll.data.request };
  }
  return { error: "TIMEOUT" };
}

JavaScript – Nachher (CaptchaAI)

const axios = require("axios");
const API_KEY = process.env.CAPTCHAAI_API_KEY;  // Changed: env var

async function solveRecaptcha(sitekey, pageurl) {
  // Only URLs changed
  const submit = await axios.post("https://ocr.captchaai.com/in.php", null, {
    params: { key: API_KEY, method: "userrecaptcha", googlekey: sitekey, pageurl, json: 1 },
  });
  if (submit.data.status !== 1) return { error: submit.data.request };

  const captchaId = submit.data.request;
  for (let i = 0; i < 60; i++) {
    await new Promise((r) => setTimeout(r, 5000));
    const poll = await axios.get("https://ocr.captchaai.com/res.php", {
      params: { key: API_KEY, action: "get", id: captchaId, json: 1 },
    });
    if (poll.data.status === 1) return { solution: poll.data.request };
    if (poll.data.request !== "CAPCHA_NOT_READY") return { error: poll.data.request };
  }
  return { error: "TIMEOUT" };
}

Schritt 3: Anbieter hinter einer Abstraktion kapseln

Für einen risikoärmeren Umstieg kapseln Sie den Solver hinter einem anbieterunabhängigen Wrapper – Anbieterwechsel und Rollback werden dann zum Einzeiler:

import os
import time
import requests


class CaptchaProvider:
    def __init__(self, base_url, api_key):
        self.submit_url = f"{base_url}/in.php"
        self.result_url = f"{base_url}/res.php"
        self.api_key = api_key
        self.session = requests.Session()

    def solve(self, sitekey, pageurl, method="userrecaptcha"):
        resp = self.session.post(self.submit_url, data={
            "key": self.api_key,
            "method": method,
            "googlekey": sitekey,
            "pageurl": pageurl,
            "json": 1
        })
        data = resp.json()
        if data.get("status") != 1:
            return {"error": data.get("request")}

        captcha_id = data["request"]
        for _ in range(60):
            time.sleep(5)
            result = self.session.get(self.result_url, params={
                "key": self.api_key, "action": "get",
                "id": captcha_id, "json": 1
            }).json()
            if result.get("status") == 1:
                return {"solution": result["request"]}
            if result.get("request") != "CAPCHA_NOT_READY":
                return {"error": result.get("request")}
        return {"error": "TIMEOUT"}


# Switch by changing one line:
# provider = CaptchaProvider("https://azcaptcha.com", "old_key")
provider = CaptchaProvider(
    "https://ocr.captchaai.com",
    os.environ["CAPTCHAAI_API_KEY"]
)

Schritt 4: Parallel testen und vergleichen

Bevor Sie umschalten, lassen Sie beide Anbieter gegeneinander laufen und vergleichen Erfolgsquote und Lösungszeit auf Ihren Zielseiten:

def parallel_test(sitekey, pageurl, runs=10):
    azcaptcha = CaptchaProvider("https://azcaptcha.com", "old_key")
    captchaai = CaptchaProvider(
        "https://ocr.captchaai.com",
        os.environ["CAPTCHAAI_API_KEY"]
    )

    results = {"azcaptcha": [], "captchaai": []}

    for i in range(runs):
        start = time.time()
        az_result = azcaptcha.solve(sitekey, pageurl)
        results["azcaptcha"].append({
            "success": "solution" in az_result,
            "time": time.time() - start
        })

        start = time.time()
        cai_result = captchaai.solve(sitekey, pageurl)
        results["captchaai"].append({
            "success": "solution" in cai_result,
            "time": time.time() - start
        })

    for provider, data in results.items():
        successes = sum(1 for r in data if r["success"])
        avg_time = sum(r["time"] for r in data) / len(data)
        print(f"{provider}: {successes}/{runs} success, {avg_time:.1f}s avg")

Ein typisches DACH-Setup zeigt den geringen Aufwand: Laufen Ihre Worker auf Hetzner-VPS und werden über GitLab CI ausgerollt, hinterlegen Sie CAPTCHAAI_API_KEY im CI-Secret-Store und passen die Basis-URL im Deployment an – ohne Rebuild. Bei Proxy-Aufrufen prüfen Sie zudem Ihre DSGVO-Rechtsgrundlage, da IP-Adressen als personenbezogene Daten gelten.

Tipp: Lassen Sie den AZCaptcha-Schlüssel während der gesamten Testphase aktiv. So schalten Sie den Verkehr bei Auffälligkeiten sofort zurück, ohne ein neues Deployment auszurollen.

Referenz: Endpunkte zuordnen

Jeder AZCaptcha-Aufruf hat ein direktes CaptchaAI-Gegenstück – in der Praxis ein Suchen-und-Ersetzen der Host-Domain:

In der Praxis reduziert sich die Zuordnung damit auf einen Host-Tausch: azcaptcha.com wird zu ocr.captchaai.com, die Pfade in.php und res.php bleiben unverändert.

Genauso verhält es sich mit den Query-Aktionen: getbalance und reportbad heißen auf beiden Seiten gleich und liefern dasselbe Antwortformat.

Referenz: Parameterzuordnung

Die meisten Parameter sind identisch. Relevant sind nur diese Punkte:

Weil googlekey, pageurl und method unverändert bleiben, ist der einzige Parameter, den Sie aktiv anfassen, key – und den lesen Sie idealerweise aus der Umgebungsvariablen.

Checkliste für den Umstieg

Arbeiten Sie die folgenden Punkte der Reihe nach ab; jeder Haken entspricht einem überprüfbaren Zwischenstand:

Typische Probleme beim Umstieg

Die meisten Fehler in der Umstellungsphase gehen auf einen von vier Punkten zurück – Schlüssel, Guthaben, Mapping oder Stichprobengröße:

Hinweis: Eine abweichende Erfolgsquote in den ersten Läufen ist selten ein Kompatibilitätsproblem, sondern meist eine Frage der Stichprobengröße. Vergleichen Sie erst nach ausreichend vielen Lösungen und auf denselben Zielseiten.

Häufige Fragen

Muss ich meinen Code neu schreiben oder reicht die URL?

In den meisten Fällen reicht die URL. Beide APIs nutzen dasselbe 2Captcha-kompatible Format – Sie tauschen Basis-URL und key, alles andere bleibt gleich.

Welche CAPTCHA-Typen löst CaptchaAI nach der Migration?

CaptchaAI löst reCAPTCHA v2 und v3 (inklusive Enterprise), Cloudflare Turnstile und Challenge, GeeTest v3 sowie Bild-/OCR-, Grid- und BLS-CAPTCHAs; CaptchaFox, Friendly Captcha und Lemin sind in der Beta. hCaptcha und FunCaptcha werden derzeit nicht unterstützt – baut Ihr Workflow darauf auf, planen Sie das ein.

Wie stelle ich ohne Ausfallrisiko um?

Kapseln Sie den Anbieter hinter der Abstraktion aus Schritt 3, leiten Sie zunächst nur einen Teil des Verkehrs auf CaptchaAI und behalten Sie den AZCaptcha-Schlüssel als Fallback. Erst nach 24 Stunden stabiler Beobachtung deaktivieren Sie den alten Schlüssel. CaptchaAI rechnet dabei Thread-basiert ab (Pläne ab BASIC, 15 $/Monat, 5 Threads), nicht pro Lösung.

Ändern sich die Fehlercodes nach der Migration?

Die meisten Fehlercodes sind identisch, da beide APIs demselben Schema folgen. Achten Sie direkt nach dem Wechsel vor allem auf ERROR_KEY_DOES_NOT_EXIST und ERROR_ZERO_BALANCE – beide weisen auf einen noch nicht korrekt hinterlegten Schlüssel oder fehlendes Guthaben hin, nicht auf ein Kompatibilitätsproblem.

Verwandte Leitfäden

• Migration von 2Captcha zu CaptchaAI
• Migration von Anti-Captcha zu CaptchaAI
• API-Antwortformate und Fehlercodes