Zum Inhalt springen

API-Dokumentation

Drei Endpunkte, vollständige Codebeispiele in sechs Sprachen. Integriere den Hochleistungs-Solver-Cluster von Capzy in unter 60 Sekunden.

Schnellstart

schritt 1
POST /createTask

Sende den Captcha-Typ + Website-Parameter. Du erhältst sofort eine taskId zurück.

schritt 2
POST /getTaskResult

Frage etwa jede Sekunde ab, bis der Status ready ist. Das Token steckt im Objekt solution.

schritt 3
POST /getBalance

Prüfe das verbleibende Guthaben. Fehlgeschlagene Lösungen werden hier automatisch erstattet.

basis-urlhttps://api.capzy.aiAuthentifizierung über clientKey im Request-Body

Endpunkte

POST/createTaskNeue Aufgabe zum Lösen eines Captchas erstellen
anfrage
{
  "clientKey": "capzy_...",
  "task": {
    "type": "AntiTurnstileTaskProxyLess",
    "websiteURL": "https://example.com",
    "websiteKey": "0x4AAA..."
  }
}
antwort
{
  "errorId": 0,
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "status": "processing"
}
POST/getTaskResultAufgabenergebnis abfragen
anfrage
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
antwort
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "0.eyJhbGci..."
  }
}
POST/getBalanceKontoguthaben prüfen
anfrage
{ "clientKey": "capzy_..." }
antwort
{ "errorId": 0, "balance": 9.50 }
POST/reportScoreOptional: Melde den von Google verifizierten Score für V3-Aufgaben zurück. Speist die V3-Qualitätsansicht in deinem Dashboard. Ein Bericht pro Aufgabe; Berichte müssen innerhalb von 24 Stunden nach Abschluss der Lösung eingehen.
anfrage
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "score": 0.9,
  "action": "login",
  "hostname": "example.com"
}
antwort
{ "errorId": 0 }
POST/reportCorrectCaptchaOptional: Teile uns mit, dass die Lösung von der Zielseite AKZEPTIERT wurde. Besonders nützlich für Typen mit Koordinatenrückgabe (z. B. Shopee-Slider), bei denen wir eine Position liefern und dein eigener Browser das Ziehen ausführt. Dieser Bericht ist unser einziges Genauigkeitssignal aus der Praxis. Ein Bericht pro Aufgabe, innerhalb von 24 Stunden; hat nie Einfluss auf den Preis.
anfrage
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
antwort
{ "errorId": 0 }
POST/reportIncorrectCaptchaOptional: Teile uns mit, dass die Lösung von der Zielseite ABGELEHNT wurde. Fließt in dieselbe Genauigkeitsmessung aus der Praxis ein wie /reportCorrectCaptcha. Ein Bericht pro Aufgabe, innerhalb von 24 Stunden; hat nie Einfluss auf den Preis.
anfrage
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
antwort
{ "errorId": 0 }

Unterstützte Aufgabentypen

Wird geladen…

Live-Liste der aktuell aktivierten Aufgabentypen, gruppiert nach Captcha-Anbieter. Preise und durchschnittliche Lösungszeit aktualisieren sich automatisch aus der Cluster-Telemetrie.

Aufgabentypen werden geladen…

Ratenlimits

Limits gelten pro Konto, zusammengefasst über alle deine API-Schlüssel. Bei Überschreitung wird ein Fehlercode zurückgegeben, ohne Guthaben zu verbrauchen.

Standard
30 gleichzeitig · 30 Anf./Sek.

Jedes neue Konto startet hier

Höhere Parallelität
300+ gleichzeitig · 100+ Anf./Sek.

Eröffne ein Support-Ticket mit deinem erwarteten Volumen (keine separate Preisstufe, gleicher Preis pro Lösung)

gleichzeitige Aufgaben

Wie viele Aufgaben du gleichzeitig in der Lösungswarteschlange haben kannst. Eine Aufgabe zählt ab createTask zu deinem Limit, bis sie beendet ist (Erfolg, Fehler oder Timeout).

ratenlimit

Wie viele createTask-Aufrufe du pro Sekunde machen kannst. Gleitendes Fenster, pro Konto. Bei Überschreitung wird ERROR_RATE_LIMITED zurückgegeben, ohne dass Guthaben abgezogen wird.

Fehlercodes

Jeder Fehler, den /createTask / /getTaskResult zurückgibt, mit Lösung. Fehlgeschlagene Lösungen werden automatisch erstattet: Das Guthaben geht sofort zurück auf dein Konto.

Authentifizierung

Probleme mit deinem API-Schlüssel oder deiner IP.
  • ERROR_KEY_DOES_NOT_EXIST

    Dein API-Schlüssel wurde nicht erkannt.

    lösungPrüfe den Wert unter Dashboard → API-Schlüssel. Schlüssel beginnen mit `capzy_`. Rotierte Schlüssel werden sofort ungültig.

    #
  • ERROR_IP_NOT_ALLOWED

    Die IP deiner Anfrage steht nicht auf der Allowlist des API-Schlüssels.

    lösungFüge deine IP unter Dashboard → API-Schlüssel zur Allowlist des Schlüssels hinzu oder entferne die Allowlist ganz, wenn du keine IP-Bindung brauchst.

    #
  • ERROR_IP_BLOCKED

    Deine IP ist vorübergehend gesperrt, weil sie zu viele ungültige Anfragen gesendet hat.

    lösungWir sperren IPs, die 100+ ungültige Anfragen in 10 Minuten senden (mit steigender Dauer). Behebe den Fehler, der die ungültigen Anfragen verursacht, und warte dann. Sperren laufen je nach Stufe nach 1 Minute bis 24 Stunden automatisch ab.

    #

Validierung

Fehlerhafte Aufgabenparameter oder falscher Typ für den Sitekey.
  • ERROR_INVALID_PARAMS

    Der Request-Body war fehlerhaft oder es fehlten Pflichtfelder.

    lösungPrüfe, dass `clientKey` auf oberster Ebene steht und `task` den `type` plus den erforderlichen Bezeichner enthält (websiteURL/websiteKey/captchaId/usw.). Die Pflichtparameter pro Typ findest du im Abschnitt Aufgabentypen.

    #
  • ERROR_BAD_SITEKEY

    Der `websiteKey` ist bei keinem Captcha-Anbieter registriert, den wir erkennen können.

    lösungAchte darauf, den vollständigen Sitekey von der Zielseite zu kopieren (suche nach `data-sitekey`, `sitekey:` oder dem Parameter in `grecaptcha.render` / `hcaptcha.render`).

    #
  • ERROR_TASK_NOT_SUPPORTED

    Der übermittelte Aufgaben-`type` ist kein Captcha-Typ, den Capzy derzeit unterstützt.

    lösungDie vollständige Liste der aktivierten Typen findest du unten im Abschnitt Aufgabentypen. Wenn du ein nicht aufgeführtes Captcha brauchst, eröffne ein Ticket, und wir priorisieren es.

    #
  • ERROR_WRONG_TASK_TYPE

    Der Aufgabentyp passt nicht zum tatsächlichen Anbieter des Sitekeys.

    lösungWir prüfen Sitekeys vorab gegen ihren echten Anbieter. Die Fehlerantwort enthält ein Feld `recommended`: Wechsle zu diesem Aufgabentyp. (Es wird kein Guthaben berechnet.)

    #
  • ERROR_PROXY_REQUIRED

    Dieses Captcha ist IP-gebunden: Seine Token sind an die IP gebunden, die sie gelöst hat.

    lösungWechsle zur Variante `*Task` (statt `*TaskProxyLess`) und übergib eine `proxyAddress`, die der IP entspricht, mit der du das Token übermittelst. Betrifft: Cloudflare Challenge, CaptchaFox, AWS WAF, DataDome, PerimeterX, Kasada, Akamai, Imperva.

    #
  • ERROR_NO_PROXY

    Für diesen Aufgabentyp sind Proxy-Felder erforderlich, sie fehlten aber.

    lösungGib `proxyType`, `proxyAddress`, `proxyPort` (und optional `proxyLogin`/`proxyPassword`/`userAgent`) im Aufgaben-Body an.

    #
  • ERROR_PROXY_CONNECT_REFUSED

    Dein angegebener Proxy hat die Verbindung abgelehnt.

    lösungPrüfe Proxy-Zugangsdaten, Erreichbarkeit des Hosts und ob die IP aktiv ist. Teste denselben Proxy zuerst von deinem eigenen Rechner aus, um Probleme des Anbieters einzugrenzen.

    #

Ratenlimits

Limits für Parallelität, pro Sekunde und Erstattungsquote.
  • ERROR_MAX_TASKS_REACHED

    Du hast das Limit gleichzeitiger Aufgaben deiner Kontostufe erreicht.

    lösungWarte, bis laufende Aufgaben abgeschlossen sind, bevor du weitere sendest. Die Standardstufe Regular erlaubt 30 gleichzeitige Aufgaben; kontaktiere den Support für ein Upgrade.

    #
  • ERROR_RATE_LIMITED

    Du sendest /createTask schneller, als dein Ratenlimit erlaubt.

    lösungVerlangsame und versuche es erneut. Die Standardstufe Regular erlaubt 30 Anf./Sek. im gleitenden Fenster. Das Überschreiten des Limits verbraucht kein Guthaben.

    #
  • ERROR_NO_SLOT_AVAILABLE

    Die Cluster-Kapazität ist vorübergehend ausgelastet.

    lösungVersuche es nach einigen Sekunden erneut (das ist vorübergehend). Wenn es minutenlang anhält, prüfe status.capzy.ai.

    #
  • ERROR_SYSTEM_MAINTENANCE

    Capzy befindet sich in einer geplanten Wartung.

    lösungVersuche es nach dem Wartungsfenster erneut. Wir kündigen Wartungen vorab auf der Statusseite an.

    #

Lösungsergebnisse

Was der Solver zurückgegeben hat. Fehlgeschlagene Lösungen werden automatisch erstattet.
  • ERROR_TIMEOUT

    Die Aufgabe wurde nicht innerhalb des Zeitlimits ihres Typs abgeschlossen.

    lösungAutomatisch erstattet, keine Kosten. Die meisten Timeouts sind vorübergehend. Wenn ein bestimmtes Captcha regelmäßig ins Timeout läuft, eröffne ein Ticket mit der Aufgaben-UUID.

    #
  • ERROR_CAPTCHA_UNSOLVABLE

    Der Solver hat sein Kontingent an Wiederholungen für diese Challenge aufgebraucht.

    lösungAutomatisch erstattet, keine Kosten. Häufige Ursachen: veralteter Sitekey, websiteURL passt nicht zur einbettenden Domain, das Captcha wurde von der Zielseite deaktiviert.

    #
  • ERROR_NULL_RESULT

    Der Solver wurde beendet, hat aber kein Token geliefert.

    lösungAutomatisch erstattet. Meist hat die Zielseite das Captcha während der Lösung entfernt. Versuche es erneut; wenn es anhält, eröffne ein Ticket.

    #
  • ERROR_INTERNAL

    Unerwarteter Fehler in der Lösungs-Pipeline.

    lösungAutomatisch erstattet. Versuche es erneut (das ist selten). Wenn du sie in schneller Folge siehst, eröffne ein Ticket mit der Aufgaben-UUID.

    #
  • ERROR_ZERO_BALANCE

    Das Kontoguthaben reicht nicht für die Kosten der Aufgabe.

    lösungLade Guthaben unter Dashboard → Abrechnung auf. Fehlgeschlagene Lösungen werden automatisch erstattet, du zahlst also nur für erfolgreiche Token.

    #

Score-Berichte

Fehler speziell für /reportScore (V3-Qualitätsfeedback).
  • ERROR_TASK_NOT_FOUND

    /reportScore: Die taskId gehört nicht zu deinem Konto oder wurde gelöscht.

    lösungScore-Berichte müssen sich auf eine Aufgabe beziehen, die dir gehörte, und innerhalb von 24 h nach Abschluss der Lösung eingereicht werden.

    #
  • ERROR_TASK_NOT_READY

    /reportScore: Die Aufgabe wird noch bearbeitet oder ist bereits fehlgeschlagen.

    lösungNur Aufgaben im Status `ready` können bewertet werden. Warte, bis /getTaskResult ready liefert, bevor du berichtest.

    #
  • ERROR_REPORT_TOO_LATE

    /reportScore: Seit Abschluss der Lösung sind mehr als 24 h vergangen.

    lösungMelde Scores innerhalb weniger Minuten nach deinem siteverify-Aufruf. Dann sind die Daten für unser V3-Qualitäts-Dashboard am nützlichsten.

    #
06

Code-Playground

Vollständige, funktionierende Beispiele in allen gängigen Sprachen. Kopieren, API-Schlüssel einfügen, ausführen.

solve.py
import requests, time

API = "https://api.capzy.ai"
KEY = "capzy_your_key_here"

# Create task
task = requests.post(f"{API}/createTask", json={
    "clientKey": KEY,
    "task": {
        "type": "AntiTurnstileTaskProxyLess",
        "websiteURL": "https://example.com",
        "websiteKey": "0x4AAA..."
    }
}).json()

task_id = task["taskId"]

# Poll for result
while True:
    result = requests.post(f"{API}/getTaskResult", json={
        "clientKey": KEY,
        "taskId": task_id
    }).json()

    if result["status"] == "ready":
        token = result["solution"]["token"]
        print(f"Solved: {token[:50]}...")
        break
    elif result["status"] == "failed":
        print(f"Failed: {result.get('errorDescription')}")
        break

    time.sleep(1)
AusgabevorschauErfolg (200 OK)
{ "errorId": 0, "status": "ready", "solution": { "token": "0.eyJhbGci..." } }

Integration in unter 60 Sekunden.

$0.10 kostenloses Guthaben bei der Registrierung. Keine Kreditkarte erforderlich.

Kostenlosen API-Schlüssel holen →