Inicio rápido de CaptchaAI: tu primera resolución de CAPTCHA en 5 minutos

Esta guía tiene un único objetivo: llevarte lo más rápido posible desde cero hasta una primera llamada exitosa al API y recibir el token resuelto. Sin teoría ni desvíos, sólo los pasos mínimos y código que funciona.

Todos los tipos de CAPTCHA que CaptchaAI soporta siguen el mismo patrón de cuatro pasos:

1. Enviar los datos del CAPTCHA a in.php
2. Guardar el ID de la tarea desde la respuesta
3. Sondear res.php cada 5 segundos hasta que el resultado esté listo
4. Usar el token — inyectarlo en la página o request de destino

Paso 0: consigue tu API key

1. Regístrate en captchaai.com
2. Abre tu panel
3. Copia tu API key de 32 caracteres

Tu cuenta necesita threads activos para enviar tareas. Si estás evaluando el servicio, contacta soporte para una prueba gratuita.

Paso 1: envía un CAPTCHA

Este ejemplo resuelve un Cloudflare Turnstile — uno de los tipos más comunes. Necesitas dos datos de la página de destino:

• sitekey — la clave pública del widget Turnstile (atributo data-sitekey o parámetros del script Turnstile, empieza con 0x)
• pageurl — la URL completa donde se carga el widget

cURL

curl -X POST "https://ocr.captchaai.com/in.php" \
  -d "key=YOUR_API_KEY" \
  -d "method=turnstile" \
  -d "sitekey=0x4AAAAAAAC3DHQFLr1GavNl" \
  -d "pageurl=https://staging.example.com/qa-login" \
  -d "json=1"

Python

import requests

response = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "turnstile",
    "sitekey": "0x4AAAAAAAC3DHQFLr1GavNl",
    "pageurl": "https://staging.example.com/qa-login",
    "json": 1,
})
print(response.json())

Node.js

const response = await fetch("https://ocr.captchaai.com/in.php", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    key: "YOUR_API_KEY",
    method: "turnstile",
    sitekey: "0x4AAAAAAAC3DHQFLr1GavNl",
    pageurl: "https://staging.example.com/qa-login",
    json: "1",
  }),
});
console.log(await response.json());

PHP

<?php
$response = file_get_contents("https://ocr.captchaai.com/in.php?" . http_build_query([
    "key"       => "YOUR_API_KEY",
    "method"    => "turnstile",
    "sitekey"   => "0x4AAAAAAAC3DHQFLr1GavNl",
    "pageurl"   => "https://staging.example.com/qa-login",
    "json"      => 1,
]));
echo $response;

Paso 2: guarda el ID de la tarea

Respuesta exitosa:

{
  "status": 1,
  "request": "71823469"
}

El campo request es el ID de tu tarea — lo necesitarás para obtener el resultado.

Si status es 0, algo salió mal. Revisa el código de error en request:

Paso 3: sondea el resultado

Espera 15 segundos, luego sondea cada 5 segundos hasta tener respuesta.

Python

import time

time.sleep(15)

while True:
    result = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": "YOUR_API_KEY",
        "action": "get",
        "id": "71823469",
        "json": 1,
    }).json()

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

    if result.get("status") == 1:
        token = result["request"]
        print(f"Solved! Token: {token[:60]}...")
        break

    raise RuntimeError(result)

Node.js

await new Promise((r) => setTimeout(r, 15000));

while (true) {
  const r = await fetch(
    `https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=get&id=71823469&json=1`,
  );
  const data = await r.json();
  if (data.request === "CAPCHA_NOT_READY") {
    await new Promise((r) => setTimeout(r, 5000));
    continue;
  }
  if (data.status === 1) {
    console.log("Solved:", data.request.slice(0, 60));
    break;
  }
  throw new Error(JSON.stringify(data));
}

Paso 4: usa el token

La forma de inyectarlo depende del tipo de CAPTCHA:

• Turnstile / reCAPTCHA: escribir en cf-turnstile-response o g-recaptcha-response, o llamar al callback de la página.
• OCR de imagen: poner el texto reconocido en el input de respuesta.
• GeeTest / FunCaptcha: ensamblar los varios campos devueltos según el sitio.

Inyección mínima en navegador:

document.querySelector('[name="cf-turnstile-response"]').value = token;
document.querySelector("form").submit();

Errores frecuentes al empezar

• Espacio al copiar la API key — recórtalo.
• Falta el protocolo en pageurl — debe ser https://….
• Primer sondeo demasiado pronto — espera 15 segundos.
• Sondear muy seguido — cada 5 s es suficiente, no acelera nada.
• Sin threads disponibles — revisa los códigos de error del API y tu plan.

Siguientes pasos

• Cómo resolver reCAPTCHA v2 con la API: guía paso a paso
• Cómo resolver Cloudflare Turnstile con la API
• Cómo resolver GeeTest v3 usando API
• Image Captcha Solving Using Api

Configuración recomendada para su pipeline

Use exactamente la misma configuración de navegador en todos sus entornos de QA, staging y CI. Esto evita que un test funcione en local y falle en CI sin razón aparente.

from selenium import webdriver

def make_driver(headless: bool = True) -> webdriver.Chrome:
    options = webdriver.ChromeOptions()
    if headless:
        options.add_argument('--headless=new')
    options.add_argument('--window-size=1280,800')
    options.add_argument('--lang=es-ES')
    return webdriver.Chrome(options=options)

Mantener viewport, idioma y user-agent por defecto idénticos en todos los runners reduce la varianza y facilita comparar resultados entre ejecuciones de su propio QA.

Cómo se integra CaptchaAI en su pipeline propio

El patrón de integración con CaptchaAI siempre es el mismo, independientemente del lenguaje o framework de pruebas que use:

1. Su test detecta el widget de CAPTCHA en la página de su propia aplicación (formulario de QA, landing de staging, endpoint de preproducción).
2. Su test envía a CaptchaAI los datos públicos del widget (sitekey, URL de la página, tipo de CAPTCHA).
3. CaptchaAI devuelve un token válido para esa página.
4. Su test inyecta ese token en el campo correspondiente y envía el formulario.
5. Su backend verifica el token con el proveedor de CAPTCHA, exactamente igual que con un usuario real.

Este flujo se aplica únicamente a integraciones que usted controla. No se utiliza para sortear protecciones de sitios de terceros.

Métricas y observabilidad

Incluya métricas específicas para los pasos relacionados con CAPTCHA en sus pipelines de QA. Esto le permite detectar regresiones en su propia integración antes de que lleguen a producción:

• Tiempo de resolución por intento — desde la solicitud a CaptchaAI hasta la entrega del token.
• Tasa de éxito por endpoint propio — cuántas verificaciones backend pasan respecto al total de intentos.
• Distribución de errores — agrupados por código (ERROR_*, timeouts internos, fallos de red).
• Latencia extremo a extremo — incluyendo render de la página, resolución de CAPTCHA y respuesta de su backend.

Conserve trazas (logs, capturas, HAR) durante un período razonable para poder reproducir incidentes en su entorno QA cuando un test falle de forma intermitente.

Buenas prácticas en su entorno QA

• Pruebe siempre sobre su propia aplicación o sobre entornos explícitamente autorizados.
• Mantenga una API key de CaptchaAI separada para QA, distinta de la de producción, para no mezclar métricas.
• Defina timeouts y reintentos razonables (backoff exponencial) para no acumular trabajos pendientes en CaptchaAI durante caídas.
• Versione sus snapshots de configuración (sitekey, action, umbrales) junto al código de los tests.
• Revise periódicamente el changelog de su proveedor de CAPTCHA para anticipar cambios que afecten a su propia integración.

Preguntas frecuentes

¿Esta guía aplica a sitios de terceros?

No. Todo el contenido está pensado para su propia aplicación o para entornos explícitamente autorizados de QA, staging y preproducción. Resolver CAPTCHA en sitios que no controla puede infringir sus términos de servicio.

¿Funciona con todos los tipos de CAPTCHA?

CaptchaAI soporta los principales tipos de CAPTCHA en su pipeline propio: reCAPTCHA v2 / v3, Cloudflare Turnstile, hCaptcha, GeeTest, FunCaptcha, entre otros. Consulte la documentación oficial para la lista completa y los parámetros que necesita cada tipo.

¿Cómo manejo errores intermitentes en mi propio CI?

Aísle el paso de CAPTCHA en una función con reintentos controlados y backoff exponencial. Registre métricas por intento para poder diferenciar entre fallos de red, timeouts del proveedor y errores de configuración en su propia aplicación.

Solución de problemas

Valide sus integraciones CAPTCHA en entornos propios con CaptchaAI.