# hCaptcha

> Obtenez des tokens hCaptcha avec YesCaptcha : HCaptchaTaskProxyless, HCaptchaTaskProxylessM1 et HCaptchaTask avec votre propre proxy, comment renseigner userAgent et rqdata, et comment utiliser le respKey renvoyé.

Source: https://docs.yescaptcha.com/fr/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/

Une tâche hCaptcha renvoie un token (`gRecaptchaResponse`). Envoyez-le au site cible avec le `userAgent` renvoyé (et le `respKey`, s’il est présent) pour passer la vérification. `HCaptchaTaskProxyless` coûte 30 points (≈ $4.50 / 1k) par tâche et `HCaptchaTask` (avec votre propre proxy) coûte 15 points (≈ $2.25 / 1k) par tâche ; les deux sont asynchrones : `createTask`, puis `getTaskResult` toutes les 5 secondes. Les tâches échouées ou expirées donnent lieu à un remboursement de points automatique.

- POST `https://api.yescaptcha.com/createTask` (Endpoint mondial)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint Chine)

Le corps de la requête est du JSON, authentifié avec votre `clientKey`. Interrogez le résultat sur le même endpoint que celui où vous avez créé la tâche.

## Cas d’usage

La page affiche la case à cocher hCaptcha « Je suis humain » ou une épreuve d’images hCaptcha. Pour obtenir un token et le soumettre directement, utilisez les types de cette page ; pour cliquer vous-même sur les images dans un navigateur, utilisez [la reconnaissance d’images hCaptcha](https://docs.yescaptcha.com/fr/tasks/hcaptcha-classification.md).

> **Note:** Le taux de réussite de hCaptcha varie beaucoup d’un site à l’autre ; testez d’abord sur un petit lot.

## Types de tâche et prix

| Type de tâche | Prix | Mode | Remarques |
| --- | --- | --- | --- |
| `HCaptchaTaskProxyless` | $4.50 / 1k; 30 points/tâche · ¥30 / 1k | Asynchrone |  |
| `HCaptchaTaskProxylessM1` | $4.50 / 1k; 30 points/tâche · ¥30 / 1k | Asynchrone | Mêmes paramètres que HCaptchaTaskProxyless sur une autre route ; l'un peut servir de solution de secours à l'autre |
| `HCaptchaTask` | $2.25 / 1k; 15 points/tâche · ¥15 / 1k | Asynchrone | Proxy fourni |

Les prix en dollars américains sont des estimations avec 1 USD ≈ ¥6.67 ; les tâches sont facturées en points.

-   `HCaptchaTaskProxyless` et `HCaptchaTaskProxylessM1` ont les mêmes paramètres mais passent par des routes différentes ; ils peuvent se servir mutuellement de secours.
-   `HCaptchaTask` charge le captcha via votre propre proxy et nécessite les champs de proxy ; utilisez-le quand le site cible vérifie l’IP du visiteur.

## Paramètres de la requête

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `type` | string | Oui | Type de tâche ; voir « Types de tâches et prix » sur cette page |
| `websiteURL` | string | Oui | URL complète de la page qui affiche le captcha. Indiquez le site sur lequel vous voyez le captcha, pas le domaine du fournisseur du captcha |
| `websiteKey` | string | Oui | La clé du site hCaptcha (sitekey), généralement un UUID |
| `userAgent` | string | Non | User-Agent du navigateur. Recommandé, mais seule la valeur renvoyée par `GET https://api.yescaptcha.com/useragent` est acceptée ; soumettez le token avec le `userAgent` du résultat |
| `isInvisible` | boolean | Non | Indiquez true pour la variante invisible ; omettez-le sinon |
| `rqdata` | string | Non | rqdata pour hCaptcha Enterprise ; requis par certains sites et généralement présent dans la requête qui charge le captcha |
| `proxyType` | string | Certains types | Protocole du proxy : `http`, `https`, `socks4` ou `socks5` (Obligatoire pour HCaptchaTask) |
| `proxyAddress` | string | Certains types | Adresse IP ou nom d'hôte du proxy. Les adresses locales ou privées telles que 127.0.0.1 ou 192.168.x.x ne fonctionneront pas, car nos serveurs ne peuvent pas y accéder (Obligatoire pour HCaptchaTask) |
| `proxyPort` | integer | Certains types | Port du proxy (Obligatoire pour HCaptchaTask) |
| `proxyLogin` | string | Non | Nom d'utilisateur du proxy, si le proxy exige une authentification (HCaptchaTask uniquement) |
| `proxyPassword` | string | Non | Mot de passe du proxy, si le proxy exige une authentification (HCaptchaTask uniquement) |

-   `websiteURL` est la page où le captcha apparaît, **et non** hcaptcha.com.
-   `userAgent` est recommandé, mais seule la valeur renvoyée par [/useragent](https://docs.yescaptcha.com/fr/api/useragent.md) est acceptée.
-   `rqdata` : exigé par la version Enterprise de hCaptcha (par exemple sur certains sites sociaux et de messagerie) ; on le trouve généralement dans la requête qui charge le captcha. Ne le transmettez pas pour les sites ordinaires.

Pour savoir comment trouver ces paramètres, consultez [Trouver les paramètres hCaptcha](https://docs.yescaptcha.com/fr/guides/find-hcaptcha-parameters.md).

## Exemple de requête

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);
```

Avec votre propre 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"
  }
}
```

## Résultat

```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..."
  }
}
```

| Champ | Type | Description |
| --- | --- | --- |
| `gRecaptchaResponse` | string | Le token à soumettre au site cible. Usage unique, valable environ 120 secondes ; utilisez-le dans les 60 secondes |
| `userAgent` | string | Le User-Agent utilisé pour obtenir le token. Utilisez cette valeur lorsque vous soumettez le token, même si elle diffère de celle que vous avez envoyée |
| `respKey` | string | Une valeur que certains sites exigent en plus du token ; soumettez-la si elle est présente |

Pour la soumission :

1.  Placez le token dans le champ `h-captcha-response` de la page (et dans `g-recaptcha-response`, s’il existe), ou dans le champ attendu par l’API du site cible.
2.  Envoyez la requête de soumission avec le `userAgent` renvoyé comme User-Agent.
3.  Si un `respKey` a été renvoyé, soumettez-le aussi, selon les exigences du site.

Pendant le traitement, la réponse est `{"errorId": 0, "status": "processing"}` ; interrogez de nouveau 5 secondes plus tard. En cas d’erreur, traitez-la selon `errorCode`, voir [Codes d’erreur](https://docs.yescaptcha.com/fr/api/errors.md).

## FAQ

### Pourquoi le taux de réussite est-il irrégulier ?

hCaptcha se base sur les paramètres du site, l’IP du visiteur et l’environnement du navigateur, donc le taux de réussite varie selon les sites. Vérifiez que vous utilisez le `userAgent` renvoyé ; pour les sites sensibles à l’IP, utilisez `HCaptchaTask` avec votre propre proxy et effectuez aussi la soumission via ce même proxy ; vous pouvez aussi comparer avec `HCaptchaTaskProxylessM1`.

### Combien de temps un token reste-t-il valide ?

Il est à usage unique et valable environ 120 secondes. Soumettez-le dès que possible après l’avoir obtenu.

## Tutoriels associés

-   [Trouver les paramètres hCaptcha](https://docs.yescaptcha.com/fr/guides/find-hcaptcha-parameters.md)
-   [Clics sur les images hCaptcha avec Selenium](https://docs.yescaptcha.com/fr/guides/hcaptcha-click-selenium.md)