Guide de modification et de résolution du CAPTCHA GeeTest v4

Un site que vous automatisez vient de passer à GeeTest v4 et votre intégration prévue pour la v3 ne répond plus. Le point le plus important d'abord : CaptchaAI résout GeeTest v3 dès aujourd'hui, avec un taux de réussite élevé, tandis que la prise en charge de GeeTest v4 est à venir et n'est pas encore disponible. Ce guide explique ce qui change entre la v3 et la v4, comment reconnaître chaque version dans une page, et comment préparer votre code au flux v4 attendu.

Où en est CaptchaAI avec GeeTest v4

Soyons direct sur le statut : GeeTest v4 n'est pas encore pris en charge par CaptchaAI. Elle figure sur la feuille de route et ne peut être décrite que comme « à venir ». En attendant, GeeTest v3 est pleinement prise en charge et résolue via l'API. Voici la règle de décision à retenir avant d'écrire une seule ligne :

• GeeTest v3 : pleinement prise en charge, résolue via l'API dès aujourd'hui avec un taux de réussite élevé — traitez vos cibles v3 maintenant.
• GeeTest v4 : à venir, pas encore disponible — préparez votre code au flux décrit plus bas, sans l'activer en production, et suivez le statut sur la page des types pris en charge par CaptchaAI.

GeeTest v3 vs v4 : les différences qui comptent

La v4 n'est pas une simple mise à jour cosmétique. L'initialisation, la validation et l'éventail des défis changent, ce qui casse une intégration v3 non adaptée.

Les types de défis de la v4

La v4 élargit la palette de défis, ce qui explique pourquoi une logique écrite pour la v3 ne suffit plus. Comprendre cette palette avant de coder vous évite d'adapter votre détection après coup.

Puzzle coulissant

Le défi classique du glissement : l'utilisateur fait coulisser une pièce jusqu'à sa place. Déjà présent en v3.

Sélection par clic

L'utilisateur clique sur des objets précis (« cliquez sur tous les visages »). Repose sur la reconnaissance d'icônes.

Raisonnement spatial

Nouveau en v4 : l'utilisateur agence des formes selon un motif spatial. Plus exigeant que tout ce que proposait la v3.

Correspondance d'icônes

L'utilisateur reproduit une séquence d'icônes affichée à l'écran. Difficile à automatiser à la main.

Une fois la v4 disponible, l'API CaptchaAI masquera la logique propre à chaque défi, comme elle le fait déjà pour la v3. Aujourd'hui, CaptchaAI résout GeeTest v3 ; la v4 reste à venir.

Reconnaître la v4 dans une page

Avant toute chose, identifiez la version réellement servie. Trois signaux distinguent la v4 de la v3 dans le code de la page :

• un paramètre captcha_id seul, sans le couple gt + challenge de la v3 ;
• un script gcaptcha4 ou un fichier gt4.js chargé dans la page ;
• des appels vers gcaptcha4.geetest.com plutôt que api.geetest.com.

Le rendu étant piloté par JavaScript, un navigateur headless comme Selenium fiabilise l'extraction.

# extract_geetest_v4.py
import re
from selenium import webdriver


def extract_geetest_v4_params(url):
    """Extract GeeTest v4 captcha_id from a page."""
    driver = webdriver.Chrome()
    driver.get(url)

    page_source = driver.page_source

    # GeeTest v4 uses captcha_id instead of gt
    match = re.search(r'captcha_id["\']?\s*[:=]\s*["\']([a-f0-9]+)', page_source)
    captcha_id = match.group(1) if match else None

    # Check for v4-specific script
    is_v4 = "gcaptcha4" in page_source or "gt4.js" in page_source

    driver.quit()

    return {
        "captcha_id": captcha_id,
        "is_v4": is_v4,
        "pageurl": url,
    }


# Usage
params = extract_geetest_v4_params("https://example.com/login")
print(f"Captcha ID: {params['captcha_id']}")
print(f"Is v4: {params['is_v4']}")

Le flux d'intégration v4 attendu

La prise en charge de la v4 étant à venir et non encore disponible, l'intégration ci-dessous décrit le flux prévu, pour que vous puissiez anticiper votre code. Tant qu'elle n'est pas livrée, utilisez GeeTest v3, que CaptchaAI résout aujourd'hui. Le schéma reste le même que pour les autres types :

1. envoyez la tâche à l'endpoint in.php avec le captcha_id et version: "4" ;
2. interrogez régulièrement res.php jusqu'à ce que le statut passe à prêt ;
3. récupérez les tokens de validation renvoyés, puis injectez-les dans la page.

# solve_geetest_v4.py
import requests
import time
import os


def solve_geetest_v4(captcha_id, pageurl):
    """Submit GeeTest v4 to CaptchaAI and get solution."""
    api_key = os.environ["CAPTCHAAI_API_KEY"]

    # Submit task
    resp = requests.post("https://ocr.captchaai.com/in.php", data={
        "key": api_key,
        "method": "geetest",
        "gt": captcha_id,      # captcha_id maps to the gt parameter
        "pageurl": pageurl,
        "version": "4",        # Specify v4 explicitly
        "json": 1,
    }, timeout=30)

    result = resp.json()
    if result.get("status") != 1:
        raise RuntimeError(f"Submit failed: {result.get('request')}")

    task_id = result["request"]

    # Poll for result
    time.sleep(10)
    for _ in range(30):
        resp = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": api_key,
            "action": "get",
            "id": task_id,
            "json": 1,
        }, timeout=15)
        data = resp.json()

        if data.get("status") == 1:
            return data["request"]  # Contains validation tokens
        if data["request"] != "CAPCHA_NOT_READY":
            raise RuntimeError(data["request"])
        time.sleep(5)

    raise TimeoutError("GeeTest v4 solve timeout")


# Usage
solution = solve_geetest_v4(
    captcha_id="abc123def456",
    pageurl="https://example.com/login",
)
print(f"Solution: {solution}")

Injecter la solution dans la page

Là où la v3 renvoyait un challenge, la v4 valide avec quatre champs :

• lot_number — identifiant du lot de vérification ;
• pass_token — jeton de réussite du défi ;
• gen_time — horodatage de génération ;
• captcha_output — charge de sortie encodée.

Analysez la réponse en JSON, puis renseignez ces champs cachés du formulaire avant l'envoi.

# inject_geetest_v4.py
import json
from selenium import webdriver
from selenium.webdriver.common.by import By


def inject_geetest_v4_solution(driver, solution):
    """Inject GeeTest v4 solution tokens into the page."""
    # Parse solution — v4 returns different tokens than v3
    if isinstance(solution, str):
        try:
            solution = json.loads(solution)
        except json.JSONDecodeError:
            pass

    # GeeTest v4 validation uses lot_number, pass_token, gen_time, captcha_output
    driver.execute_script("""
        var solution = arguments[0];

        // Set hidden form fields
        var fields = {
            'lot_number': solution.lot_number,
            'pass_token': solution.pass_token,
            'gen_time': solution.gen_time,
            'captcha_output': solution.captcha_output,
        };

        for (var name in fields) {
            var input = document.querySelector('input[name="' + name + '"]');
            if (!input) {
                input = document.createElement('input');
                input.type = 'hidden';
                input.name = name;
                document.forms[0].appendChild(input);
            }
            input.value = fields[name];
        }

        // Trigger validation callback if available
        if (window.captchaObj && typeof window.captchaObj.appendTo === 'function') {
            window.captchaObj.appendTo('#captcha-container');
        }
    """, solution)

Exemple : un portail francophone qui migre vers la v4

Imaginez une équipe QA basée à Lyon qui surveille en continu un portail e-commerce hébergé sur OVHcloud. Le site protégeait sa page de connexion avec GeeTest v3, puis bascule vers la v4 sans préavis. Les tests automatisés commencent à échouer : le paramètre challenge a disparu, remplacé par un captcha_id seul. La bonne réaction n'est pas de bricoler l'ancien code, mais de détecter la version servie (script gcaptcha4), de router les cibles encore en v3 vers la résolution actuelle de CaptchaAI, et de garder le flux v4 en attente jusqu'à sa disponibilité. Côté données, restez sur le principe RGPD de minimisation : ne collectez que ce dont vos tests ont réellement besoin.

Dépannage

Voici les erreurs les plus probables lorsque vous préparez ou basculez une intégration vers le flux v4.

FAQ

Comment détecter si un site utilise GeeTest v3 ou v4 ?

Cherchez gcaptcha4.geetest.com ou gt4.js dans la source de la page : c'est la v4. Si vous trouvez api.geetest.com avec un paramètre challenge, il s'agit de la v3.

CaptchaAI peut-il résoudre GeeTest v4 aujourd'hui ?

Non, pas encore : la prise en charge de la v4 est à venir. En revanche, GeeTest v3 est pleinement prise en charge et résolue via l'API dès maintenant.

Faut-il migrer mon intégration de la v3 vers la v4 ?

Uniquement si vos cibles sont déjà passées en v4. Tant qu'un site sert la v3, gardez la résolution actuelle ; ajoutez une détection de version pour router automatiquement chaque cible vers le bon flux.

La v4 remplace-t-elle définitivement la v3 ?

Pas dans l'immédiat. De nombreux sites restent en v3, et les deux versions coexistent. Une détection de version dans votre code vous évite d'avoir à choisir à la main.

Guides connexes

• Les paramètres du défi coulissant GeeTest
• GeeTest face à Cloudflare Turnstile

GeeTest v3 se résout dès aujourd'hui — démarrez avec CaptchaAI. La prise en charge de GeeTest v4 est à venir.