Cloudflare Turnstile

Une tâche Cloudflare Turnstile renvoie un token (token) à soumettre au site cible pour passer la vérification. TurnstileTaskProxyless coûte 25 points (≈ $3.75 / 1k) par tâche et fonctionne en mode asynchrone : appelez createTask, puis getTaskResult toutes les 5 secondes. Les tâches en échec ou expirées donnent lieu à un remboursement de points automatique.

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

POSThttps://cn.yescaptcha.com/createTaskEndpoint ChineCopier

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

Un widget de vérification Cloudflare (« Confirmez que vous êtes humain ») est intégré dans un formulaire de la page, et la page charge un script depuis challenges.cloudflare.com/turnstile.

Si toute la page est bloquée par Cloudflare et affiche « Veuillez patienter… » ou « Vérification de votre navigateur en cours », il s’agit de la page de vérification Cloudflare, pas de Turnstile : utilisez Page de vérification Cloudflare. La différence est expliquée dans Identifier le type de captcha.

Types de tâche et prix

Type de tâche	Prix	Mode	Remarques
TurnstileTaskProxyless	$3.75 / 1k; 25 points/tâche · ¥25 / 1k	Asynchrone
TurnstileTaskProxylessM1	$4.50 / 1k; 30 points/tâche · ¥30 / 1k	Asynchrone
TurnstileTask	$3.75 / 1k; 25 points/tâche · ¥25 / 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.

• TurnstileTaskProxyless et TurnstileTaskProxylessM1 ont les mêmes paramètres mais passent par des routes différentes ; l’un peut servir de secours à l’autre.
• TurnstileTask charge le captcha via votre propre proxy et nécessite les champs de proxy.

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 Turnstile (sitekey), commençant généralement par 0x
pageAction	string	Non	L'action que la page transmet à Turnstile (une option de turnstile.render, ou data-action sur l'élément du widget), par exemple login. Inutile dans la plupart des cas ; ajoutez-la uniquement si les tâches échouent systématiquement
data	string	Non	Le cData que la page transmet à Turnstile (une option de turnstile.render, ou data-cdata sur l'élément du widget), par exemple c0bd4b36-7419-4e18-83c6-378699f2a9a2. Inutile dans la plupart des cas ; ajoutez-le uniquement si les tâches échouent systématiquement
proxyType	string	Certains types	Protocole du proxy : http, https, socks4 ou socks5 (Obligatoire pour TurnstileTask)
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 TurnstileTask)
proxyPort	integer	Certains types	Port du proxy (Obligatoire pour TurnstileTask)
proxyLogin	string	Non	Nom d'utilisateur du proxy, si le proxy exige une authentification (TurnstileTask uniquement)
proxyPassword	string	Non	Mot de passe du proxy, si le proxy exige une authentification (TurnstileTask uniquement)
userAgent	string	Non	User-Agent du navigateur. Si le résultat contient un userAgent, utilisez cette valeur lorsque vous soumettez le token (TurnstileTask uniquement)

websiteKey commence généralement par 0x. Pour la trouver, consultez Trouver les paramètres Turnstile.

Si les tâches échouent toujours : pageAction et data

Dans la plupart des cas, websiteURL et websiteKey suffisent, et ces deux paramètres ne sont pas nécessaires. Si vous êtes certain que websiteURL et websiteKey sont corrects et que la tâche échoue quand même, vérifiez si la page transmet action et cData à Turnstile (options de turnstile.render, ou data-action et data-cdata sur l’élément du widget). Si c’est le cas, transmettez-les tels quels :

• pageAction : l’action de la page, par exemple login
• data : le cData de la page, par exemple c0bd4b36-7419-4e18-83c6-378699f2a9a2

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

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "TurnstileTaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "0x4AAAAAAA_SITE_KEY",
    "pageAction": "login",
    "data": "c0bd4b36-7419-4e18-83c6-378699f2a9a2"
  }
}

Exemple de requête

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

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "TurnstileTaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "0x4AAAAAAA_SITE_KEY"
  }
}

curl

curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "TurnstileTaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "0x4AAAAAAA_SITE_KEY"
  }
}'

# 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

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": "TurnstileTaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "0x4AAAAAAA_SITE_KEY",
})
print(solution["token"])

Node.js

solve.mjs

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: "TurnstileTaskProxyless",
  websiteURL: "https://example.com/login",
  websiteKey: "0x4AAAAAAA_SITE_KEY",
});
console.log(solution.token);

Remplacez websiteURL et websiteKey par les valeurs du site cible.

Résultat renvoyé

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "0.ufq5RgSVZd11DPSX1brdrxnEs28KcVlKj2ORchqxSy2q9yAW6ciq3hriXDF4x...",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36"
  }
}

Champ	Type	Description
token	string	Le token à soumettre au site cible. Usage unique ; soumettez-le dès que possible
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

Placez le token dans le champ cf-turnstile-response de la page (ou dans le champ attendu par l’API du site cible) et soumettez-le, en utilisant le userAgent renvoyé comme User-Agent de la requête.

Tant que la tâche est en cours, la réponse est {"errorId": 0, "status": "processing"} ; interrogez à nouveau 5 secondes plus tard. En cas d’erreur, traitez-la selon errorCode : voir Codes d’erreur.

Questions fréquentes

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

Il est à usage unique. Soumettez-le dès que possible ; un token Turnstile expire généralement au bout de quelques minutes (c’est Cloudflare qui décide).

Le site refuse toujours la soumission

Vérifiez que websiteURL est bien la page qui affiche le widget, que websiteKey est correct, et soumettez avec le userAgent renvoyé. Si la page transmet action et cData, ajoutez-les en tant que pageAction et data : voir Si les tâches échouent toujours. Si le site vérifie aussi l’IP, utilisez TurnstileTask et soumettez via le même proxy.

Tutoriels associés

• Identifier le type de captcha
• Trouver les paramètres Turnstile