Proxy-Authentifizierungsmethoden für die CaptchaAI-API

Ein Token, das CaptchaAI aus einem beliebigen Rechenzentrum löst, während Ihr Crawler die Seite über einen Residential-Proxy in Frankfurt geladen hat, wird beim Absenden des Formulars verworfen – nicht weil das Token ungültig wäre, sondern weil die IP nicht zusammenpasst. Genau dafür existiert der proxy-Parameter: Sie hängen Ihren eigenen Proxy an den Request an in.php, und CaptchaAI löst die Abfrage aus derselben IP, die auch die Seite geladen hat. Das Wertformat bleibt dabei immer gleich – host:port:user:pass –, unterschiedlich sind nur proxytype und die Art der Authentifizierung. Dieser Leitfaden zeigt alle vier Varianten mit lauffähigem Code, das Parameterformat und die typischen Fehlercodes.

Der proxy-Parameter im Überblick

Zuerst das Format, danach der Code: proxy transportiert Host, Port und – sofern nötig – die Anmeldedaten in einem einzigen String; proxytype sagt der API, wie sie die Verbindung aufbaut.

Zwei Regeln gelten unabhängig vom Typ. Erstens gehören Anmeldedaten in die Secrets Ihrer Pipeline – in deutschen Teams meist GitLab CI oder GitHub Actions – und niemals ins Repository. Zweitens muss der Proxy von außen erreichbar sein; ein Zugang, der nur aus dem Firmennetz antwortet, ist für die Server von CaptchaAI unsichtbar.

Wann sich die Übergabe eines Proxys lohnt

Nicht jede Abfrage braucht einen eigenen Proxy:

Der Komfort hat einen Preis: Weil CaptchaAI die Anfrage über Ihren Proxy leitet, sollten Sie mit 2–5 Sekunden zusätzlicher Lösungszeit rechnen. Bei reinen reCAPTCHA-v2-Formularen ohne IP-Bindung sparen Sie diese Zeit – lassen Sie den Parameter dort einfach weg.

Szenario aus der Praxis: Preismonitoring aus einem deutschen Rechenzentrum

Ein Berliner Handelsunternehmen betreibt sein Sortiments- und Preismonitoring auf einem Hetzner-Server in Nürnberg. Die beobachtete Shop-Seite steht hinter Cloudflare Turnstile, der Crawler ruft sie über einen deutschen Residential-Proxy mit Sticky Session auf. Wird der Sitekey ohne proxy übermittelt, löst CaptchaAI aus einer anderen IP: Das Token ist formal korrekt, wird beim Absenden aber verworfen. Sobald dieselben Zugangsdaten mitgeschickt werden, die auch der Crawler nutzt, passen Seitenaufruf und Lösung zusammen.

Zwei Punkte gehören in DACH-Projekten regelmäßig dazu:

• Datenschutz: IP-Adressen gelten nach DSGVO als personenbezogene Daten. Klären Sie vorab, welche Verbindungsdaten Ihr Proxy-Anbieter protokolliert und auf welcher Rechtsgrundlage Sie die Zielseite abrufen.
• Kosten: Ein eigener Proxy ändert an der Abrechnung von CaptchaAI nichts. Abgerechnet wird pro Thread, nicht pro Lösung – BASIC kostet 15 $/Monat bei 5 Threads, ADVANCE 90 $/Monat bei 50 Threads, jeweils mit unbegrenzten Lösungen pro Thread. (Preise in US-Dollar.) Die Proxy-Gebühren laufen separat über Ihren Anbieter.

Methode 1: Benutzername und Passwort über HTTP

Der Standardfall. Die Anmeldedaten hängen Sie als drittes und viertes Segment an den Proxy-String, proxytype bleibt HTTP:

import requests
import time

CAPTCHAAI_KEY = "YOUR_API_KEY"
CAPTCHAAI_URL = "https://ocr.captchaai.com"


def solve_with_http_proxy(site_url, sitekey, proxy_host, proxy_port,
                           proxy_user, proxy_pass):
    """Pass HTTP proxy to CaptchaAI for IP-matched solving."""
    proxy_param = f"{proxy_host}:{proxy_port}:{proxy_user}:{proxy_pass}"

    resp = requests.post(f"{CAPTCHAAI_URL}/in.php", data={
        "key": CAPTCHAAI_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": site_url,
        "proxy": proxy_param,
        "proxytype": "HTTP",
        "json": 1,
    })

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

    task_id = data["request"]

    for _ in range(60):
        time.sleep(5)
        resp = requests.get(f"{CAPTCHAAI_URL}/res.php", params={
            "key": CAPTCHAAI_KEY,
            "action": "get",
            "id": task_id,
            "json": 1,
        })
        data = resp.json()
        if data["request"] == "CAPCHA_NOT_READY":
            continue
        if data["status"] == 1:
            return data["request"]
        raise Exception(f"Solve: {data['request']}")

    raise TimeoutError("Timeout")


# Usage
token = solve_with_http_proxy(
    site_url="https://example.com/form",
    sitekey="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    proxy_host="proxy.example.com",
    proxy_port=8080,
    proxy_user="myuser",
    proxy_pass="mypass",
)

Der Ablauf ist in allen Beispielen derselbe: in.php liefert die Task-ID, danach fragen Sie res.php alle fünf Sekunden ab, bis die Antwort nicht mehr CAPCHA_NOT_READY lautet. Ein hartes Timeout gehört dazu – sonst blockiert ein hängender Proxy Ihren Worker.

Methode 2: SOCKS5 mit Anmeldedaten

Am Aufbau ändert sich nichts, ausgetauscht wird nur proxytype – praktisch, wenn Ihr Anbieter denselben Zugang über mehrere Protokolle bereitstellt. SOCKS4 folgt demselben Muster:

def solve_with_socks5_proxy(site_url, sitekey, proxy_host, proxy_port,
                             proxy_user, proxy_pass):
    """Pass SOCKS5 proxy to CaptchaAI."""
    proxy_param = f"{proxy_host}:{proxy_port}:{proxy_user}:{proxy_pass}"

    resp = requests.post(f"{CAPTCHAAI_URL}/in.php", data={
        "key": CAPTCHAAI_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": site_url,
        "proxy": proxy_param,
        "proxytype": "SOCKS5",
        "json": 1,
    })

    data = resp.json()
    task_id = data["request"]

    for _ in range(60):
        time.sleep(5)
        resp = requests.get(f"{CAPTCHAAI_URL}/res.php", params={
            "key": CAPTCHAAI_KEY, "action": "get",
            "id": task_id, "json": 1,
        })
        data = resp.json()
        if data["request"] != "CAPCHA_NOT_READY":
            return data["request"]

    raise TimeoutError("Timeout")

Methode 3: IP-Whitelist ohne Anmeldedaten

Viele Anbieter authentifizieren nicht über Benutzername und Passwort, sondern über eine IP-Whitelist. Dann verkürzt sich der String auf Host und Port:

def solve_with_whitelisted_proxy(site_url, sitekey, proxy_host, proxy_port):
    """Proxy with IP whitelist — no username/password."""
    proxy_param = f"{proxy_host}:{proxy_port}"

    resp = requests.post(f"{CAPTCHAAI_URL}/in.php", data={
        "key": CAPTCHAAI_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": site_url,
        "proxy": proxy_param,
        "proxytype": "HTTP",
        "json": 1,
    })

    data = resp.json()
    task_id = data["request"]

    for _ in range(60):
        time.sleep(5)
        resp = requests.get(f"{CAPTCHAAI_URL}/res.php", params={
            "key": CAPTCHAAI_KEY, "action": "get",
            "id": task_id, "json": 1,
        })
        data = resp.json()
        if data["request"] != "CAPCHA_NOT_READY":
            return data["request"]

    raise TimeoutError("Timeout")

Wichtig: Bei IP-Whitelist-Proxys müssen zusätzlich die Server-IPs von CaptchaAI freigeschaltet sein, denn die Verbindung zu Ihrem Proxy baut CaptchaAI auf – nicht Ihr Skript. Fehlt der Eintrag, quittiert die API den Task mit ERROR_PROXY_NOT_AUTHORIZED.

Methode 4: HTTPS-Proxy über CONNECT

Zugänge, die den Tunnel per CONNECT aufbauen, laufen mit proxytype HTTPS, häufig auf Port 8443. Anmeldedaten und Polling bleiben identisch:

def solve_with_https_proxy(site_url, sitekey, proxy_host, proxy_port,
                            proxy_user, proxy_pass):
    proxy_param = f"{proxy_host}:{proxy_port}:{proxy_user}:{proxy_pass}"

    resp = requests.post(f"{CAPTCHAAI_URL}/in.php", data={
        "key": CAPTCHAAI_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": site_url,
        "proxy": proxy_param,
        "proxytype": "HTTPS",
        "json": 1,
    })

    # ... same polling logic ...

Dieselbe Logik in Node.js

In Node.js bauen Sie den Request mit axios auf. Der Typ kommt aus der Konfiguration, sodass HTTP, HTTPS, SOCKS4 und SOCKS5 über eine einzige Funktion laufen:

const axios = require("axios");

const CAPTCHAAI_KEY = "YOUR_API_KEY";
const API = "https://ocr.captchaai.com";

async function solveWithProxy(siteUrl, sitekey, proxyConfig) {
  const params = {
    key: CAPTCHAAI_KEY,
    method: "userrecaptcha",
    googlekey: sitekey,
    pageurl: siteUrl,
    proxy: `${proxyConfig.host}:${proxyConfig.port}:${proxyConfig.user}:${proxyConfig.pass}`,
    proxytype: proxyConfig.type || "HTTP",
    json: 1,
  };

  const submit = await axios.post(`${API}/in.php`, null, { params });
  const taskId = submit.data.request;

  for (let i = 0; i < 60; i++) {
    await new Promise((r) => setTimeout(r, 5000));

    const result = await axios.get(`${API}/res.php`, {
      params: { key: CAPTCHAAI_KEY, action: "get", id: taskId, json: 1 },
    });

    if (result.data.request === "CAPCHA_NOT_READY") continue;
    if (result.data.status === 1) return result.data.request;
  }

  throw new Error("Timeout");
}

// Usage
const token = await solveWithProxy(
  "https://example.com/form",
  "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
  {
    host: "proxy.example.com",
    port: 8080,
    user: "myuser",
    pass: "mypass",
    type: "HTTP", // HTTP, HTTPS, SOCKS4, or SOCKS5
  }
);

Formate gängiger Proxy-Anbieter

Die großen Anbieter unterscheiden sich vor allem darin, wie sie Kunden-ID, Zone und Session in den Benutzernamen kodieren. Übernehmen Sie ihn exakt so, wie ihn das Dashboard ausgibt – ein abgeschnittenes Zonen-Kürzel ist eine häufige Fehlerquelle:

# Bright Data
proxy = "brd.superproxy.io:22225:brd-customer-ID-zone-residential:PASSWORD"
proxytype = "HTTP"

# Smartproxy
proxy = "gate.smartproxy.com:10001:spuser:sppassword"
proxytype = "HTTP"

# Oxylabs
proxy = "pr.oxylabs.io:7777:customer-USERNAME:PASSWORD"
proxytype = "HTTP"

Fehlercodes und ihre Ursachen

Checkliste vor dem Produktivstart

• Proxy von einem externen Host aus getestet, nicht nur aus dem Firmennetz.
• Bei IP-Whitelist: Server-IPs von CaptchaAI eingetragen.
• Sticky Session so konfiguriert, dass Seitenaufruf und Lösung dieselbe IP verwenden.
• Anmeldedaten in Umgebungsvariablen oder CI-Secrets ausgelagert.
• Wiederholungslogik mit Fallback-Proxy und hartem Timeout implementiert.
• Zusätzliche Latenz von 2–5 Sekunden in den Timeouts eingeplant.

Häufige Fragen

Welche Proxy-Typen akzeptiert die CaptchaAI-API?

HTTP, HTTPS, SOCKS4 und SOCKS5 – mit Anmeldedaten oder per IP-Whitelist. Den Typ setzen Sie über proxytype; der Wert bleibt host:port:user:pass, bei Whitelist-Zugängen host:port.

Muss ich die Server-IPs von CaptchaAI freischalten?

Nur bei IP-Whitelist-Proxys, dort aber zwingend. CaptchaAI verbindet sich von den eigenen Servern aus mit Ihrem Proxy; ohne Freigabe kommt keine Verbindung zustande. Bei Zugängen mit Benutzername und Passwort ist keine Freischaltung nötig.

Ändert ein eigener Proxy die Kosten meines Plans?

Nein. CaptchaAI rechnet Thread-basiert ab, nicht pro Lösung: BASIC mit 15 $/Monat und 5 Threads, STANDARD mit 30 $/Monat und 15 Threads, jeweils mit unbegrenzten Lösungen pro Thread. Für den Proxy zahlen Sie separat bei Ihrem Anbieter.

Warum wird mein Token trotz gültiger Anmeldedaten abgelehnt?

Meist stimmen die IPs nicht überein: Ein rotierender Proxy hat zwischen Seitenaufruf und Lösung die Ausgangs-IP gewechselt. Nutzen Sie eine Sticky Session mit ausreichender Haltedauer und übergeben Sie exakt denselben Zugang wie Ihr HTTP-Client.

Was ist beim Proxy-Einsatz aus DSGVO-Sicht zu beachten?

Behandeln Sie IP-Adressen als personenbezogene Daten. Prüfen Sie, welche Verbindungsdaten Ihr Anbieter speichert und ob für den Abruf der Zielseite eine tragfähige Rechtsgrundlage vorliegt. Diese Einschätzung liegt bei Ihnen und ersetzt keine Rechtsberatung.

Verwandte Leitfäden

• SOCKS5-Proxy Schritt für Schritt einrichten
• Rotierende Residential-Proxys sauber anbinden
• Bright Data mit CaptchaAI verbinden

Hinterlegen Sie Ihren Proxy im Request an in.php und lösen Sie IP-gebundene Abfragen aus Ihrer eigenen IP – mit CaptchaAI.