Guia completo de integração Python Selenium + CaptchaAI

Um teste em Selenium passa por três páginas sem problema e trava exatamente no reCAPTCHA, no Turnstile ou num CAPTCHA de imagem — porque o Selenium simula clique e digitação, mas não resolve desafios visuais sozinho. É aí que entra a API da CaptchaAI: ela recebe a sitekey extraída da página, resolve o desafio e devolve um token que você grava no DOM antes de enviar o formulário. Este guia mostra o padrão completo em Python — do driver configurado corretamente até a detecção automática do tipo de CAPTCHA — cobrindo reCAPTCHA v2/v3, Cloudflare Turnstile e CAPTCHA de imagem, com código pronto para cada etapa.

Pré-requisitos

Instale as três dependências antes de rodar qualquer exemplo deste guia: o Selenium para controlar o navegador, requests para chamar a API da CaptchaAI e o webdriver-manager para baixar o driver do Chrome automaticamente.

pip install selenium requests webdriver-manager

Configuração do driver Selenium sem sinalizadores óbvios de automação

from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from webdriver_manager.chrome import ChromeDriverManager

def create_driver():
    """Create a Selenium driver with stealth-configuredion settings."""
    options = webdriver.ChromeOptions()
    options.add_argument("--disable-blink-features=AutomationControlled")
    options.add_experimental_option("excludeSwitches", ["enable-automation"])
    options.add_experimental_option("useAutomationExtension", False)

    driver = webdriver.Chrome(
        service=Service(ChromeDriverManager().install()),
        options=options,
    )

    # Remove webdriver flag
    driver.execute_cdp_cmd("Page.addScriptToEvaluateOnNewDocument", {
        "source": "Object.defineProperty(navigator, 'webdriver', {get: () => undefined})"
    })

    return driver

A função create_driver() desativa as flags de automação padrão do Chrome e remove o sinalizador do webdriver por um comando CDP. Isso evita a detecção mais básica; sites mais rigorosos ainda identificam a automação por outros sinais — por isso a resolução via API da CaptchaAI entra no fluxo, em vez de depender só da configuração do navegador.

Helper de resolução: enviar e consultar o token na CaptchaAI

import time
import requests

API_KEY = "YOUR_API_KEY"


def solve_captcha(method, **params):
    """Generic CaptchaAI solver — works for all supported CAPTCHA types."""
    submit_data = {
        "key": API_KEY,
        "method": method,
        "json": 1,
        **params,
    }

    submit = requests.post("https://ocr.captchaai.com/in.php", data=submit_data, timeout=30)
    data = submit.json()

    if data.get("status") != 1:
        raise Exception(f"Submit error: {data.get('request')}")

    task_id = data["request"]

    for _ in range(30):
        time.sleep(5)
        result = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": API_KEY,
            "action": "get",
            "id": task_id,
            "json": 1,
        }, timeout=30).json()

        if result.get("status") == 1:
            return result["request"]
        if result.get("request") == "ERROR_CAPTCHA_UNSOLVABLE":
            raise Exception("CAPTCHA unsolvable")

    raise TimeoutError("Solve timed out")

A função solve_captcha() serve para qualquer tipo suportado — você troca só o parâmetro method. Ela envia a tarefa para in.php, guarda o task_id e consulta res.php a cada 5 segundos, por até 150 segundos. Quando status vem 1, request já contém o token pronto; quando vem ERROR_CAPTCHA_UNSOLVABLE, a função interrompe a tentativa.

Resolvendo reCAPTCHA v2 no Selenium

Fluxo completo: detectar, resolver, gravar o token e enviar

from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
import re

def solve_recaptcha_v2_selenium(driver, url):
    """Complete reCAPTCHA v2 solve in Selenium."""
    driver.get(url)

    # Wait for page to load
    WebDriverWait(driver, 10).until(
        EC.presence_of_element_located((By.TAG_NAME, "body"))
    )

    # Extract sitekey
    page_source = driver.page_source
    match = re.search(r'data-sitekey=["\']([A-Za-z0-9_-]{40})["\']', page_source)
    if not match:
        raise ValueError("reCAPTCHA sitekey not found")
    sitekey = match.group(1)
    print(f"Sitekey: {sitekey}")

    # Solve via CaptchaAI
    token = solve_captcha(
        "userrecaptcha",
        googlekey=sitekey,
        pageurl=url,
    )
    print(f"Token received: {token[:50]}...")

    # Inject token into the page
    driver.execute_script(f"""
        document.getElementById('g-recaptcha-response').value = '{token}';
        document.getElementById('g-recaptcha-response').style.display = 'block';
    """)

    # If there's a callback function, call it
    driver.execute_script(f"""
        if (typeof ___grecaptcha_cfg !== 'undefined') {{
            var clients = ___grecaptcha_cfg.clients;
            for (var key in clients) {{
                var client = clients[key];
                if (client.rr && client.rr.l) {{
                    client.rr.l.callback('{token}');
                }}
            }}
        }}
    """)

    # Submit the form
    submit_button = driver.find_element(By.CSS_SELECTOR, "button[type='submit'], input[type='submit']")
    submit_button.click()

    return token


# Usage
driver = create_driver()
try:
    solve_recaptcha_v2_selenium(driver, "https://staging.example.com/qa-login")
    print(f"Current URL: {driver.current_url}")
finally:
    driver.quit()

O fluxo busca a sitekey no HTML, chama solve_captcha() com o método userrecaptcha, grava o token no campo g-recaptcha-response e, quando o widget expõe um callback JavaScript, chama esse callback diretamente. Muitos formulários só liberam o envio depois que o callback dispara — pular essa etapa é a causa mais comum de token aceito, mas formulário que não avança.

Resolvendo Cloudflare Turnstile no Selenium

def solve_turnstile_selenium(driver, url):
    """Complete Turnstile solve in Selenium."""
    driver.get(url)

    WebDriverWait(driver, 10).until(
        EC.presence_of_element_located((By.TAG_NAME, "body"))
    )

    # Extract sitekey
    page_source = driver.page_source
    match = re.search(r'data-sitekey=["\']([0-9x][A-Za-z0-9_-]+)["\']', page_source)
    if not match:
        # Try JavaScript API pattern
        match = re.search(r"sitekey\s*:\s*['\"]([0-9x][A-Za-z0-9_-]+)['\"]", page_source)
    if not match:
        raise ValueError("Turnstile sitekey not found")

    sitekey = match.group(1)
    print(f"Turnstile sitekey: {sitekey}")

    # Solve via CaptchaAI
    token = solve_captcha(
        "turnstile",
        sitekey=sitekey,
        pageurl=url,
    )
    print(f"Turnstile token: {token[:50]}...")

    # Inject token
    driver.execute_script(f"""
        // Set the hidden input value
        var inputs = document.querySelectorAll('[name="cf-turnstile-response"]');
        inputs.forEach(function(input) {{ input.value = '{token}'; }});

        // Also try the callback approach
        if (typeof turnstile !== 'undefined' && turnstile.getResponse) {{
            // Widget already rendered
        }}
    """)

    # Submit form
    submit_button = driver.find_element(By.CSS_SELECTOR, "button[type='submit'], input[type='submit']")
    submit_button.click()

    return token

A extração da sitekey do Turnstile testa dois padrões: primeiro o atributo data-sitekey, depois a chamada JavaScript sitekey: '...' — porque alguns sites renderizam o widget em HTML estático e outros via turnstile.render(). O restante do fluxo é igual ao do reCAPTCHA: resolver com o método turnstile, preencher o campo oculto cf-turnstile-response e enviar o formulário.

CAPTCHA de imagem com Selenium (OCR)

Para CAPTCHAs tradicionais de imagem/texto — aqueles em que o usuário digita as letras exibidas —, capture o elemento como imagem, envie em base64 para a CaptchaAI e digite a resposta no campo correspondente:

import base64

def solve_image_captcha_selenium(driver, captcha_selector):
    """Solve image CAPTCHA visible in the browser."""
    # Find the CAPTCHA image element
    captcha_img = driver.find_element(By.CSS_SELECTOR, captcha_selector)

    # Get image as base64
    img_base64 = captcha_img.screenshot_as_base64

    # Solve via CaptchaAI
    answer = solve_captcha("base64", body=img_base64)
    print(f"CAPTCHA answer: {answer}")

    # Type the answer into the input field
    captcha_input = driver.find_element(
        By.CSS_SELECTOR, "input[name='captcha'], input[name='code'], input.captcha-input"
    )
    captcha_input.clear()
    captcha_input.send_keys(answer)

    return answer

Esse padrão dispensa qualquer extração de sitekey: a CaptchaAI recebe o screenshot_as_base64 do próprio elemento e devolve o texto lido diretamente, pronto para preencher o campo de resposta.

Resolvendo reCAPTCHA v3 no Selenium (baseado em score)

def solve_recaptcha_v3_selenium(driver, url, sitekey, action="verify"):
    """Solve reCAPTCHA v3 in Selenium."""
    driver.get(url)

    # Solve via CaptchaAI
    token = solve_captcha(
        "userrecaptcha",
        googlekey=sitekey,
        pageurl=url,
        version="v3",
        action=action,
        score_qa="0.7",
    )

    # Inject token
    driver.execute_script(f"""
        // Set reCAPTCHA response
        var textarea = document.getElementById('g-recaptcha-response');
        if (textarea) {{
            textarea.value = '{token}';
            textarea.style.display = 'block';
        }}

        // Set any hidden input fields
        var inputs = document.querySelectorAll('input[name="g-recaptcha-response"]');
        inputs.forEach(function(input) {{ input.value = '{token}'; }});
    """)

    return token

O reCAPTCHA v3 não exibe desafio visual — ele roda em segundo plano e retorna um score. A chamada para solve_captcha() recebe version="v3", a action configurada no site (geralmente verify ou submit) e o score mínimo aceitável para o seu formulário; o token retornado vai para o mesmo campo g-recaptcha-response usado no v2.

Classe completa: detectar e resolver qualquer tipo automaticamente

A classe abaixo reúne os quatro fluxos anteriores em um único caminho de detecção automática: ela examina o HTML da página, decide qual tipo de CAPTCHA está presente e chama o resolvedor certo antes de preencher e enviar o formulário.

from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
import re
import time
import requests

API_KEY = "YOUR_API_KEY"


class SeleniumCaptchaSolver:
    """Complete Selenium + CaptchaAI automation class."""

    def __init__(self, api_key):
        self.api_key = api_key
        self.driver = None

    def start(self):
        """Initialize the browser."""
        options = webdriver.ChromeOptions()
        options.add_argument("--disable-blink-features=AutomationControlled")
        options.add_experimental_option("excludeSwitches", ["enable-automation"])
        self.driver = webdriver.Chrome(options=options)
        self.driver.execute_cdp_cmd("Page.addScriptToEvaluateOnNewDocument", {
            "source": "Object.defineProperty(navigator, 'webdriver', {get: () => undefined})"
        })

    def stop(self):
        """Close the browser."""
        if self.driver:
            self.driver.quit()

    def navigate(self, url):
        """Navigate to URL and wait for load."""
        self.driver.get(url)
        WebDriverWait(self.driver, 15).until(
            lambda d: d.execute_script("return document.readyState") == "complete"
        )

    def detect_captcha(self):
        """Detect which CAPTCHA type is on the page."""
        source = self.driver.page_source

        if re.search(r'data-sitekey=["\'][A-Za-z0-9_-]{40}["\']', source):
            if "recaptcha/api.js" in source or "grecaptcha" in source:
                return "recaptcha_v2"

        if "cf-turnstile" in source or "challenges.cloudflare.com/turnstile" in source:
            return "turnstile"

        if re.search(r'recaptcha.*v3|render=[A-Za-z0-9_-]{40}', source):
            return "recaptcha_v3"

        captcha_imgs = self.driver.find_elements(
            By.CSS_SELECTOR, "img.captcha, img[alt*='captcha'], img[src*='captcha']"
        )
        if captcha_imgs:
            return "image"

        return None

    def solve_and_submit(self, url, form_data=None):
        """Navigate, solve CAPTCHA, fill form, and submit."""
        self.navigate(url)
        captcha_type = self.detect_captcha()

        if not captcha_type:
            print("No CAPTCHA detected")
            return self._fill_and_submit(form_data)

        print(f"Detected: {captcha_type}")

        if captcha_type == "recaptcha_v2":
            self._solve_recaptcha_v2()
        elif captcha_type == "turnstile":
            self._solve_turnstile()
        elif captcha_type == "image":
            self._solve_image()

        return self._fill_and_submit(form_data)

    def _solve_recaptcha_v2(self):
        source = self.driver.page_source
        match = re.search(r'data-sitekey=["\']([A-Za-z0-9_-]{40})["\']', source)
        sitekey = match.group(1)

        token = self._api_solve("userrecaptcha", googlekey=sitekey, pageurl=self.driver.current_url)

        self.driver.execute_script(f"""
            document.getElementById('g-recaptcha-response').value = '{token}';
        """)

    def _solve_turnstile(self):
        source = self.driver.page_source
        match = re.search(r'data-sitekey=["\']([0-9x][A-Za-z0-9_-]+)["\']', source)
        sitekey = match.group(1)

        token = self._api_solve("turnstile", sitekey=sitekey, pageurl=self.driver.current_url)

        self.driver.execute_script(f"""
            document.querySelectorAll('[name="cf-turnstile-response"]')
                .forEach(function(el) {{ el.value = '{token}'; }});
        """)

    def _solve_image(self):
        img = self.driver.find_element(
            By.CSS_SELECTOR, "img.captcha, img[alt*='captcha'], img[src*='captcha']"
        )
        answer = self._api_solve("base64", body=img.screenshot_as_base64)

        captcha_input = self.driver.find_element(
            By.CSS_SELECTOR, "input[name='captcha'], input[name='code']"
        )
        captcha_input.clear()
        captcha_input.send_keys(answer)

    def _fill_and_submit(self, form_data):
        if form_data:
            for name, value in form_data.items():
                try:
                    field = self.driver.find_element(By.NAME, name)
                    field.clear()
                    field.send_keys(value)
                except Exception:
                    pass

        submit = self.driver.find_element(
            By.CSS_SELECTOR, "button[type='submit'], input[type='submit']"
        )
        submit.click()
        time.sleep(3)
        return self.driver.current_url

    def _api_solve(self, method, **params):
        submit = requests.post("https://ocr.captchaai.com/in.php", data={
            "key": self.api_key, "method": method, "json": 1, **params,
        }, timeout=30)
        data = submit.json()
        if data.get("status") != 1:
            raise Exception(f"Submit error: {data.get('request')}")

        task_id = data["request"]
        for _ in range(30):
            time.sleep(5)
            result = requests.get("https://ocr.captchaai.com/res.php", params={
                "key": self.api_key, "action": "get", "id": task_id, "json": 1,
            }, timeout=30).json()
            if result.get("status") == 1:
                return result["request"]
        raise TimeoutError("Solve timed out")


# Usage
solver = SeleniumCaptchaSolver(API_KEY)
solver.start()
try:
    result_url = solver.solve_and_submit(
        "https://staging.example.com/qa-login",
        form_data={"username": "[email protected]", "password": "pass123"},
    )
    print(f"Result: {result_url}")
finally:
    solver.stop()

Em QA distribuído — workers rodando na região sa-east-1 da AWS, em São Paulo, por exemplo — o tempo de rede até a API da CaptchaAI se soma ao tempo de resolução do desafio. Meça os dois separadamente antes de definir o timeout do pipeline; um valor curto demais derruba tarefas que só estavam esperando a rede.

Solução de problemas

Na prática, a maioria desses erros tem a mesma causa raiz: o token foi resolvido corretamente pela CaptchaAI, mas o JavaScript da página não foi avisado de que ele existe. Confirme sempre o valor do campo com driver.execute_script("return document.getElementById('g-recaptcha-response').value") antes de investigar o resto do fluxo.

Perguntas frequentes

Devo resolver o CAPTCHA antes ou depois de preencher o restante do formulário?

De preferência por último. O token da CaptchaAI tem validade curta — normalmente poucos minutos — então preencha os demais campos primeiro e resolva o CAPTCHA como a etapa final antes do clique em enviar.

Como extraio a sitekey quando o reCAPTCHA está dentro de um iframe?

Troque para o iframe do reCAPTCHA antes de ler o HTML: driver.switch_to.frame(driver.find_element(By.CSS_SELECTOR, "iframe[src*='recaptcha']")). Extraia a sitekey e volte com driver.switch_to.default_content() antes de continuar o fluxo.

O que acontece se a CaptchaAI não conseguir resolver o desafio?

A função solve_captcha() levanta uma exceção quando a API retorna ERROR_CAPTCHA_UNSOLVABLE, e um TimeoutError se o polling ultrapassar 150 segundos sem resposta. Trate as duas exceções no seu script para decidir entre tentar de novo ou registrar a falha.

O Selenium em modo headless funciona com CaptchaAI?

Sim. A resolução acontece nos servidores da CaptchaAI, não no navegador local — o modo headless não interfere no resultado. Use --headless=new e mantenha as assinaturas do navegador (WebGL, Canvas) consistentes com um navegador real, para reduzir bloqueios do próprio site antes mesmo do CAPTCHA aparecer.

Dá para usar a mesma função solve_captcha() para outros tipos de CAPTCHA?

Sim — é por isso que ela recebe method como parâmetro. Troque userrecaptcha por turnstile, geetest ou base64 conforme o desafio, mantendo os campos key, json e o restante da lógica de polling exatamente como estão.

Resumo

Selenium em Python, combinado com a CaptchaAI, cobre qualquer CAPTCHA dentro de um fluxo de automação de navegador: detecte o tipo pelo HTML da página, resolva pela API da CaptchaAI, grave o token via JavaScript e envie o formulário. A classe SeleniumCaptchaSolver deste guia automatiza as quatro etapas — detecção, resolução, gravação do token e envio — em um único método, pronta para adaptar ao seu fluxo de QA ou de coleta de dados.

Artigos relacionados

• Comparação entre GeeTest e Cloudflare Turnstile
• Como integrar a CaptchaAI ao Google Cloud Functions
• Guia completo de Playwright em Python com a CaptchaAI