API-Dokumentation
Drei Endpunkte, vollständige Codebeispiele in sechs Sprachen. Integriere den Hochleistungs-Solver-Cluster von Capzy in unter 60 Sekunden.
Schnellstart
POST /createTaskSende den Captcha-Typ + Website-Parameter. Du erhältst sofort eine taskId zurück.
POST /getTaskResultFrage etwa jede Sekunde ab, bis der Status ready ist. Das Token steckt im Objekt solution.
POST /getBalancePrüfe das verbleibende Guthaben. Fehlgeschlagene Lösungen werden hier automatisch erstattet.
https://api.capzy.aiAuthentifizierung über clientKey im Request-BodyEndpunkte
/createTaskNeue Aufgabe zum Lösen eines Captchas erstellen{
"clientKey": "capzy_...",
"task": {
"type": "AntiTurnstileTaskProxyLess",
"websiteURL": "https://example.com",
"websiteKey": "0x4AAA..."
}
}{
"errorId": 0,
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"status": "processing"
}/getTaskResultAufgabenergebnis abfragen{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{
"errorId": 0,
"status": "ready",
"solution": {
"token": "0.eyJhbGci..."
}
}/getBalanceKontoguthaben prüfen{ "clientKey": "capzy_..." }{ "errorId": 0, "balance": 9.50 }/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.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"score": 0.9,
"action": "login",
"hostname": "example.com"
}{ "errorId": 0 }/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.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "errorId": 0 }/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.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "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.
Ratenlimits
Limits gelten pro Konto, zusammengefasst über alle deine API-Schlüssel. Bei Überschreitung wird ein Fehlercode zurückgegeben, ohne Guthaben zu verbrauchen.
Jedes neue Konto startet hier
Eröffne ein Support-Ticket mit deinem erwarteten Volumen (keine separate Preisstufe, gleicher Preis pro Lösung)
gleichzeitige AufgabenWie 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).
ratenlimitWie 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_EXISTDein 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_ALLOWEDDie 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_BLOCKEDDeine 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_PARAMSDer 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_SITEKEYDer `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_SUPPORTEDDer ü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_TYPEDer 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_REQUIREDDieses 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_PROXYFü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_REFUSEDDein 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_REACHEDDu 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_LIMITEDDu 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_AVAILABLEDie 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_MAINTENANCECapzy 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_TIMEOUTDie 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_UNSOLVABLEDer 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_RESULTDer 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_INTERNALUnerwarteter 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_BALANCEDas 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.
Code-Playground
Vollständige, funktionierende Beispiele in allen gängigen Sprachen. Kopieren, API-Schlüssel einfügen, ausführen.
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)Ressourcen
Integration in unter 60 Sekunden.
$0.10 kostenloses Guthaben bei der Registrierung. Keine Kreditkarte erforderlich.
Kostenlosen API-Schlüssel holen →