Types de tâches

hCaptcha

Cette page a été traduite automatiquement à partir de la version chinoise et peut contenir des erreurs. La version chinoise fait foi.

Je suis humainhCaptchaConfidentialité - Conditions

IllustrationhCaptcha : une case « Je suis humain ». Un clic la coche aussitôt ou ouvre une épreuve d'images.

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.

POSThttps://api.yescaptcha.com/createTaskEndpoint mondial

POSThttps://cn.yescaptcha.com/createTaskEndpoint 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.

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 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.

Exemple de requête

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

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"}'

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"])

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 :

{
  "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

{
  "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 :

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.
Envoyez la requête de soumission avec le userAgent renvoyé comme User-Agent.
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.

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.