# hCaptcha

> hCaptcha-Token mit YesCaptcha abrufen: HCaptchaTaskProxyless, HCaptchaTaskProxylessM1 und HCaptchaTask mit eigenem Proxy, wie Sie userAgent und rqdata füllen und wie Sie den zurückgegebenen respKey verwenden.

Source: https://docs.yescaptcha.com/de/tasks/hcaptcha/ · Last verified: 2026-10-15

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/hcaptcha/

Eine hCaptcha-Aufgabe liefert ein Token (`gRecaptchaResponse`). Senden Sie es zusammen mit dem zurückgegebenen `userAgent` (manchmal auch `respKey`) an die Zielwebsite, um die Prüfung zu bestehen. `HCaptchaTaskProxyless` kostet 30 Punkte (≈ $4.50 / 1k) pro Aufgabe, `HCaptchaTask` (eigener Proxy) kostet 15 Punkte (≈ $2.25 / 1k) pro Aufgabe. Beide sind asynchron: zuerst `createTask`, dann alle 5 Sekunden `getTaskResult`. Bei fehlgeschlagener Erkennung oder Timeout erfolgt automatisch eine Punkteerstattung.

- POST `https://api.yescaptcha.com/createTask` (Globaler Endpoint)
- POST `https://cn.yescaptcha.com/createTask` (China-Endpoint)

Der Request-Body ist JSON; die Authentifizierung erfolgt mit `clientKey`. Fragen Sie das Ergebnis auf demselben Endpoint ab, auf dem Sie die Aufgabe erstellt haben.

## Anwendungsfälle

Auf der Seite gibt es das hCaptcha-Kontrollkästchen „Ich bin ein Mensch” oder es erscheint eine hCaptcha-Bildaufgabe. Wenn Sie ein Token direkt absenden möchten, nutzen Sie die Typen auf dieser Seite. Wenn Sie die Bilder selbst im Browser anklicken möchten, nutzen Sie [hCaptcha-Bilderkennung](https://docs.yescaptcha.com/de/tasks/hcaptcha-classification.md).

> **Hinweis:** Die Erfolgsquote von hCaptcha schwankt je nach Website stark. Testen Sie zuerst mit einer kleinen Menge.

## Typen und Preise

| Aufgabentyp | Preis | Modus | Hinweise |
| --- | --- | --- | --- |
| `HCaptchaTaskProxyless` | $4.50 / 1k; 30 Punkte/Aufgabe · ¥30 / 1k | Asynchron |  |
| `HCaptchaTaskProxylessM1` | $4.50 / 1k; 30 Punkte/Aufgabe · ¥30 / 1k | Asynchron | Gleiche Parameter wie HCaptchaTaskProxyless, aber über eine andere Route; beide können als Fallback füreinander verwendet werden |
| `HCaptchaTask` | $2.25 / 1k; 15 Punkte/Aufgabe · ¥15 / 1k | Asynchron | Eigener Proxy |

Die Preise in US-Dollar sind Schätzwerte bei 1 US$ ≈ ¥6.67; Aufgaben werden in Punkten berechnet.

-   `HCaptchaTaskProxyless` und `HCaptchaTaskProxylessM1` haben dieselben Parameter, aber unterschiedliche Routen und können sich gegenseitig als Ausweichlösung dienen.
-   `HCaptchaTask` lädt das Captcha über Ihren eigenen Proxy; die Proxy-Felder müssen angegeben werden. Verwenden Sie diesen Typ, wenn die Zielwebsite die IP des Besuchers prüft.

## Request-Parameter

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `type` | string | Ja | Aufgabentyp; siehe „Aufgabentypen und Preise“ auf dieser Seite |
| `websiteURL` | string | Ja | Vollständige URL der Seite, auf der das Captcha angezeigt wird. Verwenden Sie die Website, auf der Sie das Captcha sehen, nicht die Domain des Captcha-Anbieters |
| `websiteKey` | string | Ja | Der hCaptcha-Website-Schlüssel (sitekey), in der Regel eine UUID |
| `userAgent` | string | Nein | User-Agent des Browsers. Empfohlen, aber es wird nur der Wert akzeptiert, den `GET https://api.yescaptcha.com/useragent` zurückgibt; senden Sie das Token mit dem `userAgent` aus dem Ergebnis |
| `isInvisible` | boolean | Nein | Auf true setzen für die unsichtbare Variante; sonst weglassen |
| `rqdata` | string | Nein | rqdata für hCaptcha Enterprise; wird von manchen Websites verlangt und findet sich in der Regel in der Anfrage, die das Captcha lädt |
| `proxyType` | string | Einige Typen | Proxy-Protokoll: `http`, `https`, `socks4` oder `socks5` (Erforderlich für HCaptchaTask) |
| `proxyAddress` | string | Einige Typen | IP-Adresse oder Hostname des Proxys. Lokale oder private Adressen wie 127.0.0.1 oder 192.168.x.x funktionieren nicht, da unsere Server sie nicht erreichen können (Erforderlich für HCaptchaTask) |
| `proxyPort` | integer | Einige Typen | Proxy-Port (Erforderlich für HCaptchaTask) |
| `proxyLogin` | string | Nein | Proxy-Benutzername, falls der Proxy eine Authentifizierung erfordert (nur HCaptchaTask) |
| `proxyPassword` | string | Nein | Proxy-Passwort, falls der Proxy eine Authentifizierung erfordert (nur HCaptchaTask) |

-   `websiteURL` ist die Seite, auf der das Captcha erscheint, **nicht** hcaptcha.com.
-   `userAgent` wird empfohlen; erlaubt ist nur ein Wert, den [/useragent](https://docs.yescaptcha.com/de/api/useragent.md) zurückgibt.
-   `rqdata`: Wird von hCaptcha Enterprise verlangt (z. B. bei einigen Social- und Chat-Websites) und lässt sich meist in der Anfrage finden, die das Captcha lädt. Bei normalen Websites nicht angeben.

Wie Sie die Parameter finden, steht unter [hCaptcha-Parameter finden](https://docs.yescaptcha.com/de/guides/find-hcaptcha-parameters.md).

## Request-Beispiel

POST https://api.yescaptcha.com/createTask

```json
{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
  }
}
```

**curl**

```bash
curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
  }
}'

# Returns {"errorId":0,"taskId":"..."}; then poll every 5 seconds:
curl -s https://api.yescaptcha.com/getTaskResult \
  -H 'Content-Type: application/json' \
  -d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'
```

**Python**

solve.py

```python
import os
import time

import requests

API = "https://api.yescaptcha.com"
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]  # Read the clientKey from an environment variable

def call(method, payload):
    r = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30)
    data = r.json()
    if data.get("errorId"):
        raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
    return data

def solve(task):
    task_id = call("createTask", {"task": task})["taskId"]
    for _ in range(36):  # Poll every 5 seconds, for up to about 3 minutes
        time.sleep(5)
        result = call("getTaskResult", {"taskId": task_id})
        if result.get("status") == "ready":
            return result["solution"]
    raise TimeoutError(task_id)

solution = solve({
    "type": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
})
print(solution["gRecaptchaResponse"])
```

**Node.js**

solve.mjs

```js
const API = 'https://api.yescaptcha.com';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY; // Read the clientKey from an environment variable

async function call(method, payload) {
  const res = await fetch(`${API}/${method}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ clientKey: CLIENT_KEY, ...payload }),
  });
  const data = await res.json();
  if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
  return data;
}

async function solve(task) {
  const { taskId } = await call('createTask', { task });
  for (let i = 0; i < 36; i++) { // Poll every 5 seconds, for up to about 3 minutes
    await new Promise((r) => setTimeout(r, 5000));
    const result = await call('getTaskResult', { taskId });
    if (result.status === 'ready') return result.solution;
  }
  throw new Error(`timeout: ${taskId}`);
}

const solution = await solve({
  type: "HCaptchaTaskProxyless",
  websiteURL: "https://accounts.hcaptcha.com/demo",
  websiteKey: "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
});
console.log(solution.gRecaptchaResponse);
```

Mit eigenem Proxy:

POST https://api.yescaptcha.com/createTask

```json
{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaTask",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
    "proxyType": "http",
    "proxyAddress": "proxy.example.com",
    "proxyPort": 8080,
    "proxyLogin": "user",
    "proxyPassword": "pass"
  }
}
```

## Ergebnis

```json
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36",
    "respKey": "E0_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
  }
}
```

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `gRecaptchaResponse` | string | Das Token, das an die Zielwebsite gesendet wird. Einmalig verwendbar, ca. 120 Sekunden gültig; verwenden Sie es innerhalb von 60 Sekunden |
| `userAgent` | string | Der User-Agent, mit dem das Token erzeugt wurde. Verwenden Sie diesen Wert beim Senden des Tokens, auch wenn er von dem abweicht, den Sie übergeben haben |
| `respKey` | string | Ein Wert, den manche Websites zusammen mit dem Token verlangen; senden Sie ihn mit, falls vorhanden |

So senden Sie das Ergebnis ab:

1.  Tragen Sie das Token in das Feld `h-captcha-response` der Seite ein (und in `g-recaptcha-response`, falls vorhanden) oder in das Feld, das die Schnittstelle der Zielwebsite verlangt.
2.  Verwenden Sie beim Absenden der Anfrage den zurückgegebenen `userAgent` als User-Agent.
3.  Wurde ein `respKey` zurückgegeben, senden Sie ihn wie von der Website verlangt mit.

Solange die Aufgabe bearbeitet wird, lautet die Antwort `{"errorId": 0, "status": "processing"}`; fragen Sie nach 5 Sekunden erneut ab. Fehler behandeln Sie anhand von `errorCode`, siehe [Fehlercodes](https://docs.yescaptcha.com/de/api/errors.md).

## Häufige Fragen

### Warum ist die Erfolgsquote nicht stabil?

hCaptcha entscheidet anhand der Einstellungen der Website, der IP des Besuchers und der Browserumgebung, daher unterscheidet sich die Erfolgsquote je nach Website. Prüfen Sie, dass Sie den zurückgegebenen `userAgent` verwenden. Nutzen Sie bei IP-sensiblen Websites `HCaptchaTask` mit eigenem Proxy und senden Sie auch die Anfrage über denselben Proxy ab. Sie können außerdem zum Vergleich `HCaptchaTaskProxylessM1` ausprobieren.

### Wie lange ist ein Token gültig?

Es ist nur einmal verwendbar und etwa 120 Sekunden gültig. Senden Sie es nach Erhalt möglichst schnell ab.

## Verwandte Anleitungen

-   [hCaptcha-Parameter finden](https://docs.yescaptcha.com/de/guides/find-hcaptcha-parameters.md)
-   [hCaptcha-Bilderkennung: Klicks simulieren (Selenium)](https://docs.yescaptcha.com/de/guides/hcaptcha-click-selenium.md)