Migration von NextCaptcha zu CaptchaAI: Vollständige Anleitung

Die Migration von NextCaptcha zu CaptchaAI ist vor allem eine Umstellung der API-Form – nicht Ihrer CAPTCHA-Logik. NextCaptcha arbeitet mit einer JSON-Task-API über /createTask und /getTaskResult; CaptchaAI nutzt das etablierte in.php/res.php-Schema mit Formularparametern. Ihre reCAPTCHA-, Turnstile- oder Bild-CAPTCHA-Abläufe bleiben inhaltlich identisch – Sie ändern nur, wie Anfrage und Antwort aufgebaut sind. Dieser Leitfaden zeigt das exakte Mapping: Endpunkte, Parameter, Aufgabentypen, Code in Python und JavaScript sowie einen risikoarmen Parallel-Test vor der endgültigen Umstellung.

Was sich ändert – und was gleich bleibt

Bevor Sie eine einzige Zeile anfassen, hilft eine klare Trennung zwischen dem, was Sie übernehmen, und dem, was Sie umbauen:

• Gleich bleibt: Ihre Sitekeys, die pageurl der Zielseite, die grundsätzliche Polling-Schleife und die unterstützten reCAPTCHA-Varianten.
• Ändern müssen Sie den Transport: Der JSON-Body wird zu einer flachen Liste aus Formularparametern.
• Ändern müssen Sie die Abfrage: Das Polling wechselt von POST auf GET mit Query-Parametern.
• Ändern müssen Sie das Parsing: Aus errorId === 0 wird status === 1, aus taskId wird request.

Wer diese vier Achsen im Kopf hat, kann jede bestehende NextCaptcha-Integration weitgehend mechanisch übertragen.

Praxisbeispiel: schrittweise Umstellung im laufenden Betrieb

Ein Data-Team in Berlin betreibt eine Preisüberwachung über mehrere Händlerportale und stößt dabei regelmäßig auf reCAPTCHA v2 und Cloudflare Turnstile. Statt hart umzuschalten, legt das Team einen Feature-Flag in seiner GitLab-CI-Pipeline an: Für 10 % der Läufe geht die Anfrage an CaptchaAI, der Rest weiter an NextCaptcha. Über eine Woche werden Erfolgsquote, Lösungszeit und Fehlercodes beider Wege in denselben Dashboards verglichen. Erst wenn die CaptchaAI-Werte stabil sind, steigt der Anteil schrittweise auf 100 %. Der Parallelbetrieb kostet wenig Aufwand, weil sich nur die Solver-Funktion unterscheidet.

Hinweis: IP-Adressen gelten in der DSGVO als personenbezogene Daten. Prüfen Sie unabhängig vom eingesetzten Solver Ihre Rechtsgrundlage und Ihre Datenflüsse, bevor Sie Scraping- oder Monitoring-Workflows in Produktion nehmen.

Endpunkt-Mapping

Statt zweier JSON-Endpunkte sprechen Sie bei CaptchaAI dieselbe Basis-URL mit unterschiedlichen Methoden und Query-Parametern an. Das vereinfacht den Client-Code, weil keine verschachtelten Task-Objekte mehr serialisiert werden.

Aufbau der Anfrage im Vergleich

Der deutlichste Unterschied liegt in der Übermittlung. Kurz zusammengefasst:

• NextCaptcha erwartet ein JSON-Objekt mit einem verschachtelten task-Block.
• CaptchaAI erwartet eine flache Liste aus Formularparametern an in.php.
• Der Sitekey heißt bei CaptchaAI googlekey (oder sitekey), die Zielseite pageurl.

NextCaptcha: Übermittlung als JSON-Body

{
  "clientKey": "next_captcha_key",
  "task": {
    "type": "RecaptchaV2TaskProxyless",
    "websiteURL": "https://example.com",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
  }
}

CaptchaAI: Übermittlung als Formularparameter

POST https://ocr.captchaai.com/in.php
key=YOUR_API_KEY&method=userrecaptcha&googlekey=6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-&pageurl=https://example.com&json=1

Parameter-Mapping

Die meisten Felder haben ein direktes Gegenstück. Die folgende Tabelle deckt die gängigen Token-CAPTCHA-Parameter ab:

Aufgabentypen zuordnen

Der type-String von NextCaptcha wird bei CaptchaAI zu einem method-Wert:

Wichtig: CaptchaAI unterstützt hCaptcha und FunCaptcha nicht. Setzen Ihre Zielseiten auf diese Typen, prüfen Sie vor der Migration, ob sich der betroffene Traffic anders abbilden lässt.

Antwortformate im Vergleich

Bevor Sie den Code umbauen, sollten Sie das Antwort-Parsing kennen. NextCaptcha signalisiert Erfolg über eine numerische errorId, CaptchaAI über ein status-Feld. Passen Sie beide Prüfstellen – Übermittlung und Polling – gemeinsam an.

Antwort bei der Übermittlung

Antwort beim Polling

Code-Migration in Python und JavaScript

Mit dem Mapping im Rücken betreffen die Codeänderungen genau zwei Stellen pro Solver-Funktion: die Übermittlung und das Polling. Die folgenden Vorher-/Nachher-Paare zeigen eine typische reCAPTCHA-v2-Funktion.

Python – vorher (NextCaptcha)

import requests
import time

CLIENT_KEY = "your_nextcaptcha_key"
BASE_URL = "https://api.nextcaptcha.com"

def solve_recaptcha_v2(sitekey, pageurl):
    # Submit
    resp = requests.post(f"{BASE_URL}/createTask", json={
        "clientKey": CLIENT_KEY,
        "task": {
            "type": "RecaptchaV2TaskProxyless",
            "websiteURL": pageurl,
            "websiteKey": sitekey
        }
    })
    data = resp.json()
    if data.get("errorId") != 0:
        return {"error": data.get("errorDescription")}

    task_id = data["taskId"]

    # Poll
    for _ in range(60):
        time.sleep(5)
        result = requests.post(f"{BASE_URL}/getTaskResult", json={
            "clientKey": CLIENT_KEY,
            "taskId": task_id
        }).json()
        if result.get("status") == "ready":
            return {"solution": result["solution"]["gRecaptchaResponse"]}
        if result.get("errorId") != 0:
            return {"error": result.get("errorDescription")}

    return {"error": "TIMEOUT"}

Python – nachher (CaptchaAI)

import os
import time
import requests

API_KEY = os.environ["CAPTCHAAI_API_KEY"]

def solve_recaptcha_v2(sitekey, pageurl):
    # Submit — different endpoint and format
    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 — GET instead of POST, different response format
    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 (NextCaptcha)

const axios = require("axios");
const CLIENT_KEY = "your_nextcaptcha_key";
const BASE_URL = "https://api.nextcaptcha.com";

async function solveRecaptchaV2(sitekey, pageurl) {
  const submit = await axios.post(`${BASE_URL}/createTask`, {
    clientKey: CLIENT_KEY,
    task: {
      type: "RecaptchaV2TaskProxyless",
      websiteURL: pageurl,
      websiteKey: sitekey,
    },
  });
  if (submit.data.errorId !== 0) return { error: submit.data.errorDescription };

  const taskId = submit.data.taskId;

  for (let i = 0; i < 60; i++) {
    await new Promise((r) => setTimeout(r, 5000));
    const poll = await axios.post(`${BASE_URL}/getTaskResult`, {
      clientKey: CLIENT_KEY,
      taskId,
    });
    if (poll.data.status === "ready") return { solution: poll.data.solution.gRecaptchaResponse };
    if (poll.data.errorId !== 0) return { error: poll.data.errorDescription };
  }
  return { error: "TIMEOUT" };
}

JavaScript – nachher (CaptchaAI)

const axios = require("axios");
const API_KEY = process.env.CAPTCHAAI_API_KEY;

async function solveRecaptchaV2(sitekey, pageurl) {
  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" };
}

Migrations-Checkliste

Arbeiten Sie die Schritte in dieser Reihenfolge ab – jeder baut auf dem vorigen auf. Die Umstellung des Produktionsverkehrs steht bewusst am Ende, nach dem Parallel-Test.

Fehlerbehebung

Häufige Fragen

Kann ich NextCaptcha und CaptchaAI parallel betreiben?

Ja. Genau das ist der empfohlene Weg: Beide Solver laufen eine Weile nebeneinander, Sie leiten einen kleinen Traffic-Anteil an CaptchaAI und vergleichen Erfolgsquote und Lösungszeit, bevor Sie vollständig umstellen. So bleibt jederzeit ein Fallback erhalten.

Muss ich meine reCAPTCHA-Sitekeys oder Ziel-URLs ändern?

Nein. Sitekey und pageurl beziehen sich auf die Zielseite, nicht auf den Solver. Sie übergeben dieselben Werte – lediglich unter den CaptchaAI-Feldnamen googlekey/sitekey und pageurl statt websiteKey und websiteURL.

Unterstützt CaptchaAI dieselben CAPTCHA-Typen wie NextCaptcha?

Für die gängigen Typen ja: reCAPTCHA v2 und v3, Cloudflare Turnstile und Cloudflare Challenge, GeeTest v3 sowie Bild-/OCR- und Rasterbild-CAPTCHAs. hCaptcha und FunCaptcha unterstützt CaptchaAI nicht – prüfen Sie vor der Migration, ob Ihre Zielseiten darauf setzen.

Wie unterscheidet sich die Abrechnung von NextCaptcha?

CaptchaAI rechnet pro gleichzeitigem Thread ab, nicht pro Lösung – jeder Plan enthält unbegrenzte Lösungen pro Thread im Abrechnungsmonat. Der Einstieg ist BASIC ab 15 $/Monat mit 5 Threads; STANDARD (30 $/Monat, 15 Threads) und höhere Tarife skalieren die Parallelität. Für konstant hohe Volumen ist das oft besser kalkulierbar als eine Abrechnung pro Solve.

Verwandte Leitfäden

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