Cómo resolver reCAPTCHA v2 con la API: guía paso a paso

reCAPTCHA v2 sigue siendo uno de los retos más comunes en formularios de login, registro, checkout y envío. Si tu flujo de automatización choca con un checkbox o reto de imagen de reCAPTCHA v2, puedes resolverlo vía API en cuatro pasos: extrae sitekey y pageurl de la página, envíalos al solver de reCAPTCHA v2 de CaptchaAI, espera el resultado e inyecta el token en el flujo protegido.

Esta guía está pensada para desarrolladores que necesitan una integración funcionando, no una visión teórica.

¿No sabes qué versión de reCAPTCHA es? Lee primero Cómo identificar la versión de reCAPTCHA.

Lo que necesitas antes de empezar

Paso 1: extrae sitekey y pageurl

pageurl es la URL de la página donde aparece la reCAPTCHA. Pásala completa, con https://.

Para obtener el sitekey tienes tres caminos:

1. En el HTML — busca <div class="g-recaptcha" data-sitekey="...">:

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

2. En la URL del iframe — https://www.google.com/recaptcha/api2/anchor?ar=1&k=6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-&... — el parámetro k= es el sitekey.

3. En el tráfico de red — abre DevTools → Network, filtra por recaptcha y verás el parámetro k en cualquier petición.

Paso 2: envía la tarea

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 en 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 invisible? Añade invisible=1 al payload. Más detalles en Cómo funciona la reCAPTCHA invisible.

Paso 3: sondea el resultado

Una reCAPTCHA v2 suele resolverse en 15–60 segundos. Espera 20 s, luego sondea 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)

El token devuelto es una cadena larga que suele empezar por 03AGdBq25....

Paso 4: inyecta el token en la página

La forma de aplicarlo depende del sitio. Lo más común: el 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"]');

Si el widget tiene data-callback, llama también a esa función:

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

Ejemplo 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])

Errores frecuentes y soluciones

Cuando algo falla

• Token devuelto pero el sitio sigue bloqueando — el formulario tiene su propio handler. Localiza el callback y llámalo en vez de rellenar el textarea sin más.
• Hay que mantener la misma huella — envía las mismas cookies y User-Agent que estaban activos al pedir el token.
• reCAPTCHA dependiente de proxy — añade proxy y proxytype en el envío para que el solver use tu pool de IPs.

Siguientes pasos

• Inicio rápido de CaptchaAI: tu primera resolución de CAPTCHA en 5 minutos
• How To Identify Recaptcha Version
• Cómo resolver Cloudflare Turnstile con la API
• Solución de errores y correcciones comunes de reCAPTCHA v2