Démarrage rapide CaptchaAI : votre première résolution de CAPTCHA en 5 minutes

Résoudre votre premier CAPTCHA avec CaptchaAI tient en quatre appels : vous soumettez le défi à l'API, vous récupérez un identifiant de tâche, vous interrogez le résultat, puis vous injectez le token dans la page cible. Comptez environ cinq minutes entre l'inscription et le premier token renvoyé — sans théorie ni détour, uniquement les étapes minimales et du code prêt à copier.

Ce cycle est identique pour tous les types pris en charge : reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, OCR d'image et grilles d'images. Apprenez-le une fois sur Turnstile, vous le réutiliserez partout ailleurs :

1. Soumettre — envoyer les données du CAPTCHA à in.php
2. Récupérer l'ID de la tâche depuis la réponse
3. Interroger res.php toutes les 5 secondes jusqu'à obtention du résultat
4. Injecter le token — dans la page ou la requête cible

Fil conducteur de ce guide : vous testez le formulaire de connexion d'un site que vous exploitez — hébergé sur OVHcloud ou Scaleway, par exemple — protégé par un widget Turnstile.

Étape 0 : obtenez votre clé API CaptchaAI

1. Inscrivez-vous sur le site CaptchaAI
2. Ouvrez votre tableau de bord API
3. Copiez la clé API de 32 caractères

Votre compte doit disposer de threads actifs pour soumettre des tâches. Si vous évaluez le service, contactez le support pour obtenir des threads d'essai.

Étape 1 : soumettez le CAPTCHA à l'API

L'exemple résout un Cloudflare Turnstile, l'un des types les plus répandus. Deux valeurs se lisent sur la page cible :

• sitekey — la clé publique du widget Turnstile (attribut data-sitekey ou paramètres du script Turnstile, commence par 0x)
• pageurl — l'URL complète où le widget est chargé

cURL

curl -X POST "https://ocr.captchaai.com/in.php" \
  -d "key=YOUR_API_KEY" \
  -d "method=turnstile" \
  -d "sitekey=0x4AAAAAAAC3DHQFLr1GavNl" \
  -d "pageurl=https://example.com/login" \
  -d "json=1"

Python

import requests

response = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "turnstile",
    "sitekey": "0x4AAAAAAAC3DHQFLr1GavNl",
    "pageurl": "https://example.com/login",
    "json": 1,
})
print(response.json())

Node.js

const response = await fetch("https://ocr.captchaai.com/in.php", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    key: "YOUR_API_KEY",
    method: "turnstile",
    sitekey: "0x4AAAAAAAC3DHQFLr1GavNl",
    pageurl: "https://example.com/login",
    json: "1",
  }),
});
console.log(await response.json());

PHP

<?php
$response = file_get_contents("https://ocr.captchaai.com/in.php?" . http_build_query([
    "key"       => "YOUR_API_KEY",
    "method"    => "turnstile",
    "sitekey"   => "0x4AAAAAAAC3DHQFLr1GavNl",
    "pageurl"   => "https://example.com/login",
    "json"      => 1,
]));
echo $response;

Étape 2 : récupérez l'ID de la tâche

Réponse en cas de succès :

{
  "status": 1,
  "request": "71823469"
}

Le champ request contient l'ID de votre tâche — gardez-le, il sert à récupérer le résultat.

Si status vaut 0, quelque chose a échoué : le code d'erreur se trouve alors dans request.

Étape 3 : interrogez le résultat du solveur

Patientez 15 secondes, puis interrogez res.php toutes les 5 secondes jusqu'à la réponse.

Python

import time

time.sleep(15)

while True:
    result = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": "YOUR_API_KEY",
        "action": "get",
        "id": "71823469",
        "json": 1,
    }).json()

    if result.get("request") == "CAPCHA_NOT_READY":
        time.sleep(5)
        continue

    if result.get("status") == 1:
        token = result["request"]
        print(f"Solved! Token: {token[:60]}...")
        break

    raise RuntimeError(result)

Node.js

await new Promise((r) => setTimeout(r, 15000));

while (true) {
  const r = await fetch(
    `https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=get&id=71823469&json=1`,
  );
  const data = await r.json();
  if (data.request === "CAPCHA_NOT_READY") {
    await new Promise((r) => setTimeout(r, 5000));
    continue;
  }
  if (data.status === 1) {
    console.log("Solved:", data.request.slice(0, 60));
    break;
  }
  throw new Error(JSON.stringify(data));
}

Tant que la résolution est en cours, l'API renvoie CAPCHA_NOT_READY ; dès que status passe à 1, le champ request contient le token résolu.

Étape 4 : injectez le token dans la page

Le mode d'injection dépend du type de CAPTCHA :

Injection minimale dans le navigateur :

document.querySelector('[name="cf-turnstile-response"]').value = token;
document.querySelector("form").submit();

Le token Turnstile est à usage unique et expire vite : soumettez-le, utilisez-le, jetez-le. Ne le mettez jamais en cache. Côté journalisation, ne stockez ni le token ni les données personnelles du formulaire — c'est le réflexe RGPD attendu sur les marchés francophones.

Erreurs de premier appel les plus fréquentes

Ces détails piègent presque tout le monde le premier jour. Vérifiez-les avant d'ouvrir un ticket :

Questions fréquentes

Combien de temps prend une première résolution Turnstile ?

En général de 15 à 30 secondes. C'est pourquoi vous attendez 15 secondes avant la première interrogation, puis vous relancez toutes les 5 secondes jusqu'à la réponse.

Ai-je besoin d'un navigateur pour utiliser l'API ?

Non. L'API fonctionne en pur HTTP : vous pouvez tout piloter en cURL, Python, Node.js ou PHP. Le navigateur n'intervient que si le site cible exige d'injecter le token dans une vraie page.

Que signifie le code CAPCHA_NOT_READY ?

Que la tâche est encore en cours de résolution. Ce n'est pas une erreur : continuez à interroger res.php toutes les 5 secondes jusqu'à ce que status passe à 1.

Combien de threads faut-il pour démarrer ?

Le plan d'entrée BASIC ($15/mois, 5 threads) suffit pour ce démarrage rapide et pour de premiers scripts. Un thread correspond à un CAPTCHA en cours ; il se libère dès la résolution terminée.

CaptchaAI prend-il en charge hCaptcha ?

Non — pas encore pris en charge, comme FunCaptcha. Ce démarrage rapide couvre Turnstile ; les types disponibles sont reCAPTCHA v2 et v3, Turnstile, Cloudflare Challenge, GeeTest v3 et les CAPTCHA image.

Et ensuite ?

Poursuivez selon le type de CAPTCHA que vous rencontrez le plus :

• Résoudre reCAPTCHA v2 via l'API
• Résoudre Cloudflare Turnstile via l'API
• Résoudre GeeTest v3 via l'API
• Résoudre les CAPTCHA image via l'API

Récupérez votre clé API sur le tableau de bord CaptchaAI et bouclez votre première résolution réussie en moins de cinq minutes.