Anfragen und Antworten

Alle Methoden werden per HTTPS POST mit JSON aufgerufen (nur /useragent ist ein GET), authentifizieren sich mit dem clientKey im Request-Body und antworten mit JSON: errorId 0 bedeutet Erfolg, 1 bedeutet Fehler mit einem errorCode. Ein Captcha zu lösen erfordert zwei Schritte: createTask erstellt die Aufgabe, getTaskResult wird alle 5 Sekunden nach dem Ergebnis abgefragt. Synchrone Typen liefern das Ergebnis direkt in createTask.

Anfrage

curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{"clientKey": "YOUR_CLIENT_KEY", "task": {"type": "ImageToTextTaskOcrBase", "body": "BASE64_IMAGE"}}'

• Endpoint: https://api.yescaptcha.com (global) oder https://cn.yescaptcha.com (China), siehe Zugangsadressen.
• Der Body ist JSON, wird mit dem Header Content-Type: application/json gesendet und darf höchstens 6 MB groß sein. JSON darf keine Kommentare enthalten.
• Jede Anfrage muss clientKey enthalten. Kopieren Sie den im Dashboard angezeigten Wert vollständig.

Achtung

Verwenden Sie bei Python requests json=data, nicht data=data. Letzteres sendet ein Formular und liefert ERROR_TASK_ABSENT oder ERROR_REQUIRED_FIELDS.

Antwort

Erfolg:

{
  "errorId": 0,
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}

Fehler:

{
  "errorId": 1,
  "errorCode": "ERROR_ZERO_BALANCE",
  "errorDescription": "帐户余额不足"
}

Feld	Beschreibung
errorId	0 Erfolg, 1 Fehler
errorCode	Fehlercode im Fehlerfall; Bedeutung und Lösung siehe Fehlercodes
errorDescription	Textbeschreibung der Fehlerursache
taskId	Aufgaben-ID
status	processing (in Bearbeitung) oder ready (fertig)
solution	Erkennungsergebnis; die Felder hängen vom Aufgabentyp ab, siehe die Seiten der einzelnen Aufgabentypen

Werten Sie errorId und errorCode aus, nicht den Text von errorDescription; er kann sich ändern.

Synchron und asynchron

	Asynchron	Synchron
Welche Typen	Typen, die ein Token zurückgeben (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), Cloudflare-Prüfseite, ImageToTextTask, ImageToTextTaskM1	Bilderkennung (Namen enden auf Classification), ImageToTextTaskOcrBase, ImageToTextTaskMuggle
createTask liefert	taskId	status: "ready" und solution
Ergebnis abrufen	getTaskResult alle 5 Sekunden aufrufen	Keine weitere Abfrage nötig

Welcher Modus für welchen Typ gilt, steht in der Spalte „Rückgabeart“ unter Aufgabentypen und Preise.

Regelmäßige Abfrage (Polling)

1. Warten Sie nach der taskId aus createTask 5 Sekunden und rufen Sie dann getTaskResult auf.
2. Bei status: "processing" warten Sie weitere 5 Sekunden und versuchen es erneut; bei status: "ready" steht das Ergebnis in solution.
3. Bei errorId: 1 beenden Sie die Abfrage dieser Aufgabe und behandeln den errorCode.

• Wiederholte Abfragen derselben taskId innerhalb von 5 Sekunden liefern sofort processing; häufigeres Abfragen liefert das Ergebnis nicht schneller.
• Eine Aufgabe wird in der Regel höchstens 110 Sekunden bearbeitet (bei wenigen Typen 180 bis 220 Sekunden); danach wird ERROR_TASK_TIMEOUT zurückgegeben und die Punkte werden automatisch erstattet (Punkteerstattung).
• Ergebnisse werden auf dem Server etwa 10 Minuten gespeichert; danach ist die taskId ungültig und Abfragen liefern ERROR_TASKID_INVALID.
• Abfragen von Ergebnissen kosten keine Punkte; nur das Erstellen einer Aufgabe führt zu einem Punkteabzug.

Sprache der Hinweise

Bei Hinweisen zu automatischer Pausierung, zwischengespeicherten ungültigen Parametern und Abbruch der Abfrage richtet sich errorDescription nach dem Request-Header Accept-Language: Beginnt er mit zh, wird Chinesisch zurückgegeben, bei jeder anderen Sprache Englisch, ohne diesen Header beides. Die Beschreibungen anderer Fehlercodes sind nicht betroffen.

Nächste Schritte

• createTask: Aufgabe erstellen
• getTaskResult: Ergebnis abrufen
• Limit gleichzeitiger Aufgaben und automatische Pausierung: Bei zu vielen Fehlern wird Ihr Zugang für einige Minuten pausiert