GeeTest v3 vs v4: o que mudou e como resolver hoje

Se o formulário que você testa passou a carregar gcaptcha4.geetest.com em vez de api.geetest.com, o site migrou para o GeeTest v4 — e a resposta rápida é: ainda não, o suporte segue listado como "em breve". A CaptchaAI resolve o GeeTest v3 hoje, com alta taxa de sucesso, e essa segue sendo a integração estável enquanto a v4 não sai do pré-lançamento.

Para quem mantém suíte de QA ou pipeline de automação, essa distinção importa mais do que parece: confundir as duas versões é a causa mais comum de ERROR_WRONG_CAPTCHA_ID e de solução rejeitada. Este guia mostra o que muda tecnicamente entre v3 e v4, como identificar qual delas está rodando na sua página, o fluxo que a API deve seguir quando o suporte à v4 for liberado e como deixar sua integração pronta com antecedência, sem depender de uma versão que ainda não está em produção.

Diferenças entre GeeTest v3 e v4

A v4 muda inicialização, parâmetros, tipos de desafio, endpoint e até a escala de dificuldade. A mudança mais relevante para quem integra é a pontuação de risco adaptativa: em vez de um desafio fixo, a dificuldade que o usuário (ou o solver) enfrenta varia conforme o sinal de risco calculado pelo GeeTest naquela sessão.

Na prática, isso significa que testes automatizados podem ver desafios de dificuldade diferente em execuções distintas, mesmo na mesma página — vale registrar o tipo de desafio recebido em cada execução de QA para comparar resultados de forma justa.

Tipos de desafio da v4

A v4 amplia o catálogo além do slide clássico da v3, com quatro formatos que podem aparecer para o mesmo captcha_id dependendo da pontuação de risco:

Quebra-cabeça de slides

O clássico desafio de arrastar: o usuário move uma peça do quebra-cabeça até a posição que completa a imagem.

Clique em seleção

O usuário clica em objetos específicos indicados na instrução (por exemplo, "clique em todos os rostos"), usando reconhecimento de ícone.

Raciocínio espacial

Novidade da v4 — o usuário organiza formas seguindo um padrão espacial. Mais complexo que qualquer desafio disponível na v3.

Correspondência de ícones

O usuário casa ícones mostrados em sequência, na ordem correta. Mais difícil de reproduzir manualmente do que o slide.

A expectativa é que, quando o suporte à v4 for liberado, a API abstraia essas quatro variações do mesmo jeito que já faz hoje na v3: você envia o desafio e recebe o token pronto, sem tratar cada tipo manualmente no seu código.

Como identificar se a página usa GeeTest v3 ou v4

Antes de qualquer solução automática, o primeiro passo é confirmar qual versão a página está servindo — muitos sites migram silenciosamente e sem aviso na changelog pública. O script abaixo abre a página, procura captcha_id no HTML renderizado e verifica a presença do script gcaptcha4 ou gt4.js, sinais exclusivos da v4:

# 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://staging.example.com/qa-login")
print(f"Captcha ID: {params['captcha_id']}")
print(f"Is v4: {params['is_v4']}")

Se o worker de QA roda a partir da região sa-east-1 (São Paulo) contra um endpoint fora do país, dê uma folga extra ao timeout dessa checagem: a variação de RTT entre a região e o servidor do provedor pode somar alguns segundos ao ciclo de detecção, principalmente em suítes que rodam em lote contra vários domínios.

Fluxo de integração previsto para a v4

O código abaixo é o fluxo planejado para a v4: mesmo in.php, mas com method: "geetest", version: "4" e o captcha_id no lugar do gt da v3. Ainda não roda contra produção:

# 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://staging.example.com/qa-login",
)
print(f"Solution: {solution}")

Guarde o script: quando a v4 sair do "em breve", a mudança será trocar o alvo, não a integração inteira.

Como as soluções são injetadas na página

A v4 devolve quatro tokens para campos ocultos específicos, e o callback de validação pode precisar ser disparado manualmente:

# 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)

Solução de problemas

Como preparar a suíte de QA para a chegada da v4

Você não precisa esperar o lançamento para deixar a integração pronta:

• Isole a detecção de versão em uma função só (como extract_geetest_v4_params neste guia) para não espalhar checagens de gcaptcha4/gt4.js pelo código.
• Trate v3 e v4 como caminhos separados atrás de um único ponto de decisão, para trocar de um para o outro sem reescrever o pipeline inteiro.
• Registre a versão detectada e o tipo de desafio em cada execução de QA — isso facilita comparar taxa de sucesso e tempo de resolução entre execuções, já que a v4 varia a dificuldade por sessão.
• Acompanhe o status do suporte à v4 na página de tipos suportados da CaptchaAI antes de promover o fluxo planejado para produção.

Perguntas frequentes

O GeeTest v4 já está disponível na CaptchaAI?

Ainda não — o suporte aparece como "em breve". Hoje a CaptchaAI resolve o GeeTest v3, com alta taxa de sucesso.

Como sei se um site já migrou do GeeTest v3 para a v4?

Veja o código-fonte: gcaptcha4.geetest.com ou gt4.js indicam v4; api.geetest.com com challenge ainda é v3.

O que muda na minha integração quando o site atualiza para v4?

Os parâmetros trocam de challenge para lot_number, pass_token, gen_time e captcha_output, e o endpoint sai de api.geetest.com para gcaptcha4.geetest.com.

Preciso de um plano diferente da CaptchaAI para resolver captchas GeeTest?

Não. A cobrança é por thread concorrente, com resoluções ilimitadas por thread — não por tipo de CAPTCHA. Para uma suíte de QA com volume baixo, o BASIC (US$ 15/mês, 5 threads) costuma bastar; suba para o ADVANCE (US$ 90/mês, 50 threads) se o paralelismo dos testes crescer.

Por que meu pipeline de v3 parou de funcionar depois que o site mudou para v4?

Provavelmente porque a integração ainda envia gt e challenge, parâmetros que a v4 não usa. Rode o script de detecção deste guia para confirmar a versão antes de depurar qualquer outra coisa.

Guias relacionados

• Guia de parâmetros de slide do GeeTest
• GeeTest vs Cloudflare Turnstile

Resolva o GeeTest v3 agora e acompanhe a chegada do suporte à v4 — comece com a CaptchaAI.