Como resolver reCAPTCHA v2 com a API: guia passo a passo

O reCAPTCHA v2 ainda é um dos desafios mais comuns em formulários de login, cadastro, checkout e envio de dados. Se a sua automação esbarra num checkbox ou desafio de imagem de reCAPTCHA v2, dá para resolver via API em quatro passos: extraia sitekey e pageurl da página, envie ao solver reCAPTCHA v2 do CaptchaAI, aguarde o resultado e injete o token no fluxo protegido.

Este guia é para devs que precisam de uma integração funcionando, não de uma visão teórica.

Não tem certeza de qual versão é? Leia antes Como identificar a versão do reCAPTCHA.

O que você precisa antes de começar

Passo 1: extraia sitekey e pageurl

pageurl é a URL completa da página onde a reCAPTCHA está. Sempre passe com https://.

Para o sitekey, três caminhos:

1. No HTML — procure <div class="g-recaptcha" data-sitekey="...">:

<div class="g-recaptcha" data-sitekey="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"></div>

2. Na URL do iframe — https://www.google.com/recaptcha/api2/anchor?ar=1&k=6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-&... — o parâmetro k= é o sitekey.

3. No tráfego de rede — DevTools → Network, filtre por recaptcha e veja o parâmetro k em qualquer requisição.

Passo 2: envie a tarefa

import requests

API_KEY = "YOUR_API_KEY"
SITEKEY = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
PAGEURL = "https://staging.example.com/qa-login"

submit = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": API_KEY,
    "method": "userrecaptcha",
    "googlekey": SITEKEY,
    "pageurl": PAGEURL,
    "json": 1,
}).json()

assert submit["status"] == 1, submit
task_id = submit["request"]
print("task id:", task_id)

Equivalente em Node.js:

const r = await fetch("https://ocr.captchaai.com/in.php", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    key: API_KEY,
    method: "userrecaptcha",
    googlekey: SITEKEY,
    pageurl: PAGEURL,
    json: "1",
  }),
});
const { status, request: taskId } = await r.json();
if (status !== 1) throw new Error(taskId);

reCAPTCHA invisível? Adicione invisible=1. Mais detalhes em Como funciona a reCAPTCHA invisível.

Passo 3: consulte o resultado

reCAPTCHA v2 normalmente leva 15–60 segundos. Espere 20 s e depois consulte a cada 5.

import time

time.sleep(20)
while True:
    res = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": API_KEY,
        "action": "get",
        "id": task_id,
        "json": 1,
    }).json()

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

    if res.get("status") == 1:
        token = res["request"]
        print("token:", token[:60], "…")
        break

    raise RuntimeError(res)

O token retornado é uma string longa que costuma começar com 03AGdBq25....

Passo 4: injete o token na página

Depende de como o site espera receber o token. O mais comum é o textarea g-recaptcha-response:

document.querySelector('textarea[name="g-recaptcha-response"]').value = token;
document.querySelector("form").submit();

Selenium:

driver.execute_script(
    "document.querySelector('[name=\"g-recaptcha-response\"]').value = arguments[0];",
    token,
)
driver.find_element(By.CSS_SELECTOR, "form").submit()

Playwright:

await page.evaluate((t) => {
  document.querySelector('[name="g-recaptcha-response"]').value = t;
}, token);
await page.click('button[type="submit"]');

Se o widget tiver data-callback, chame também a função:

const callback = document.querySelector(".g-recaptcha").dataset.callback;
if (callback && window[callback]) window[callback](token);

Exemplo completo (Python)

import time
import requests

API_KEY = "YOUR_API_KEY"
SITEKEY = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
PAGEURL = "https://staging.example.com/qa-login"

def solve_recaptcha_v2():
    submit = requests.post("https://ocr.captchaai.com/in.php", data={
        "key": API_KEY, "method": "userrecaptcha",
        "googlekey": SITEKEY, "pageurl": PAGEURL, "json": 1,
    }).json()
    if submit["status"] != 1:
        raise RuntimeError(submit)
    task_id = submit["request"]

    time.sleep(20)
    for _ in range(40):
        res = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": API_KEY, "action": "get", "id": task_id, "json": 1,
        }).json()
        if res.get("request") == "CAPCHA_NOT_READY":
            time.sleep(5)
            continue
        if res.get("status") == 1:
            return res["request"]
        raise RuntimeError(res)
    raise TimeoutError("solve timed out")

if __name__ == "__main__":
    token = solve_recaptcha_v2()
    print("token:", token[:80])

Erros frequentes e soluções

Quando algo dá errado

• Token volta mas o site continua bloqueando — o formulário tem handler próprio. Encontre o callback e chame em vez de só preencher o textarea.
• Precisa manter a mesma sinal de navegador — envie as mesmas cookies e User-Agent que estavam ativos quando você pediu o token.
• reCAPTCHA dependente de proxy — adicione proxy e proxytype no envio para o solver usar seu pool de IPs.

Próximos passos

• Início rápido do CaptchaAI: sua primeira resolução de CAPTCHA em 5 minutos
• How To Identify Recaptcha Version
• Como resolver Cloudflare Turnstile pela API
• Resolvendo erros e correções comuns do reCAPTCHA v2