
Aloísio Vítor
Image Processing Expert

Los agentes de navegador de IA están redefiniendo cómo los desarrolladores interactúan con la web. Desde la extracción de datos hasta la automatización de flujos de trabajo, estos agentes navegan por páginas, llenan formularios y extraen información sin intervención humana. Pero cuando aparece un CAPTCHA, el agente se detiene.
HyperBrowser ofrece una infraestructura de navegador basada en la nube diseñada específicamente para agentes de IA, con resolución nativa de CAPTCHA para Turnstile y reCAPTCHA. Pero la web tiene más de dos tipos de CAPTCHA. AWS WAF, GeeTest, variantes empresariales de reCAPTCHA y otros desafíos anti-bot permanecen sin resolver con solo la herramienta nativa.
CapSolver llena ese vacío. Al cargar directamente la extensión de CapSolver en HyperBrowser a través de su API de extensión, obtienes cobertura completa de CAPTCHA en cada sesión, cada tipo de CAPTCHA y a cualquier escala, sin cambiar tu código de automatización.
HyperBrowser es una plataforma de infraestructura de navegador en la nube diseñada específicamente para agentes de IA. Proporciona sesiones de navegador gestionadas con acceso nativo al Protocolo de herramientas de desarrollo de Chrome (CDP), soporte de proxy y capacidades de anti-detección listas para usar.
HyperBrowser elimina la carga operativa de la automatización del navegador. En lugar de gestionar binarios de Chromium, configuraciones headless, rotación de proxies y anti-fingerprinting, obtienes una API limpia que devuelve una URL de WebSocket. Conéctate a tu script de Playwright o Puppeteer y comienza a automatizar.
CapSolver es un servicio líder de resolución de CAPTCHA que proporciona soluciones impulsadas por IA para superar diversos desafíos de CAPTCHA. Con soporte para múltiples tipos de CAPTCHA y tiempos de respuesta rápidos, CapSolver se integra sin problemas en flujos de automatización.
Antes de configurar la integración, asegúrate de tener:
@hyperbrowser/sdk y playwright-core instaladosnpm install @hyperbrowser/sdk playwright-core
CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX)Descarga la extensión de CapSolver de Chrome y configúrala con tu clave de API:
CapSolver.Browser.Extension-chrome-vX.X.X.zipmkdir -p capsolver-extension
unzip CapSolver.Browser.Extension-chrome-v*.zip -d capsolver-extension/
capsolver-extension/assets/config.js y establece tu clave de API:export const defaultConfig = {
apiKey: 'CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', // tu clave aquí
useCapsolver: true,
// ... resto de configuración
};
ls capsolver-extension/manifest.json
# Debería existir
La API de carga de extensiones de HyperBrowser requiere un archivo ZIP. Empaqueta la extensión configurada:
cd capsolver-extension && zip -r ../capsolver-extension.zip . && cd ..
Esto crea capsolver-extension.zip en la raíz de tu proyecto, listo para cargar.
Usa el SDK de HyperBrowser para cargar el archivo ZIP de la extensión. Esto solo se debe hacer una vez: el extensionId devuelto se puede reutilizar en todas las sesiones.
import { Hyperbrowser } from "@hyperbrowser/sdk";
const client = new Hyperbrowser({
apiKey: process.env.HYPERBROWSER_API_KEY,
});
// Carga la extensión de CapSolver (operación única)
const ext = await client.extensions.create({
filePath: "capsolver-extension.zip",
});
console.log("ID de extensión:", ext.id);
// Guarda este ID: lo reutilizarás para cada sesión
Consejo: Almacena el
ext.iden tus variables de entorno o configuración. Solo necesitas volver a cargarla si cambias la versión de la extensión o la clave de API.
Crea una sesión de HyperBrowser que cargue la extensión de CapSolver:
const session = await client.sessions.create({
extensionIds: [ext.id],
useProxy: true, // Requiere plan pagado — omite para el plan gratuito
solveCaptchas: false, // Usando CapSolver en lugar de la resolución nativa
});
console.log("ID de sesión:", session.id);
console.log("URL de WebSocket:", session.wsEndpoint);
Nota: Establece solveCaptchas: false al usar CapSolver para evitar conflictos entre los mecanismos de resolución. Si deseas usar ambos como cadena de respaldo, consulta la sección "Cuándo usar resolución nativa frente a CapSolver" más abajo.
Conecta Playwright a la sesión de HyperBrowser a través de la URL de WebSocket:
import { chromium } from "playwright-core";
const browser = await chromium.connectOverCDP(session.wsEndpoint);
const context = browser.contexts()[0];
const page = context.pages()[0] || await context.newPage();
// Navega a una página protegida por CAPTCHA
await page.goto("https://www.google.com/recaptcha/api2/demo");
// Espera a que la extensión de CapSolver detecte y resuelva el CAPTCHA
await page.waitForTimeout(30000);
// Envía el formulario
await page.click("#recaptcha-demo-submit");
await page.waitForLoadState("networkidle");
// Verifica el éxito
const result = await page.textContent("body");
console.log("Resultado:", result);
// Esperado: contiene "Verification Success"
await browser.close();
await client.sessions.stop(session.id);
Aquí tienes un script completo de extremo a extremo que carga la extensión, crea una sesión, resuelve un CAPTCHA y verifica el resultado:
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { chromium } from "playwright-core";
const HYPERBROWSER_API_KEY = process.env.HYPERBROWSER_API_KEY!;
const CAPSOLVER_EXTENSION_ID = process.env.CAPSOLVER_EXTENSION_ID; // Opcional: reutilizar ID existente
async function main() {
const client = new Hyperbrowser({ apiKey: HYPERBROWSER_API_KEY });
// Paso 1: Cargar la extensión (o reutilizar ID existente)
let extensionId = CAPSOLVER_EXTENSION_ID;
if (!extensionId) {
const ext = await client.extensions.create({
filePath: "capsolver-extension.zip",
});
extensionId = ext.id;
console.log("Extensión cargada:", extensionId);
}
// Paso 2: Crear sesión con extensión de CapSolver
const session = await client.sessions.create({
extensionIds: [extensionId],
useProxy: true, // Requiere plan pagado — omite para el plan gratuito
solveCaptchas: false,
});
console.log("Sesión iniciada:", session.id);
// Paso 3: Conectar Playwright
const browser = await chromium.connectOverCDP(session.wsEndpoint);
const context = browser.contexts()[0];
const page = context.pages()[0] || await context.newPage();
try {
// Paso 4: Navegar a la página de demostración de reCAPTCHA
console.log("Navegando a la página de demostración de reCAPTCHA...");
await page.goto("https://www.google.com/recaptcha/api2/demo");
// Paso 5: Esperar a que CapSolver resuelva el CAPTCHA
console.log("Esperando a que CapSolver resuelva el CAPTCHA...");
await page.waitForTimeout(30000);
// Paso 6: Enviar el formulario
console.log("Enviando formulario...");
await page.click("#recaptcha-demo-submit");
await page.waitForLoadState("networkidle");
// Paso 7: Verificar el resultado
const bodyText = await page.textContent("body");
if (bodyText?.includes("Verification Success")) {
console.log("¡CAPTCHA resuelto con éxito!");
} else {
console.log("Resultado de verificación:", bodyText?.slice(0, 200));
}
} finally {
await browser.close();
await client.sessions.stop(session.id);
console.log("Sesión detenida.");
}
}
main().catch(console.error);
Ejecútalo:
HYPERBROWSER_API_KEY=your_key npx tsx captcha-test.ts
Este es el flujo completo desde la carga de la extensión hasta la resolución del CAPTCHA:
Configuración única
═══════════════════════════════════════════════════════
capsolver-extension/ HyperBrowser Cloud
├── manifest.json ──ZIP──► POST /extensions
├── assets/config.js │
└── background.js ▼
extensionId: "ext_abc123"
(almacenado, reutilizable)
Flujo por sesión
═══════════════════════════════════════════════════════
Tu script HyperBrowser Cloud
─────────────────────────────────────────────────────
sessions.create({ ──► Inicia Chromium en la nube
extensionIds: [id], │
useProxy: true ├── Carga la extensión de CapSolver
}) ├── Aplica proxy + stealth
▼
◄── wsEndpoint (URL de WebSocket)
playwright.connectOverCDP() Conecta al navegador en la nube
│
▼
page.goto(target_url) ──► Chromium carga la página
┌─────────────────────────────┐
│ Página con widget CAPTCHA │
│ │
│ Extensión de CapSolver: │
│ 1. Script de contenido detecta │
│ tipo de CAPTCHA en la página │
│ 2. El servicio de trabajo llama │
│ a la API de CapSolver │
│ 3. Se recibe el token de solución │
│ 4. El token se inyecta en un campo │
│ de formulario oculto │
└─────────────────────────────┘
│
page.waitForTimeout(30s) │ (la resolución ocurre aquí)
│ │
▼ ▼
page.click("Submit") ──► El formulario se envía CON token válido
│
◄── ▼
¡Éxito de verificación de Google!
El enfoque de la extensión de CapSolver tiene una ventaja clave frente a la resolución basada en API: la extensión se ejecuta dentro del contexto del navegador. Esto significa:
createTask() / getTaskResult() / lógica de inyección: todo se maneja por la extensión// Completo: extensión de CapSolver
const session = await client.sessions.create({
extensionIds: [capsolverExtId],
solveCaptchas: false,
useProxy: true, // Requiere plan pagado — omite para el plan gratuito
});
Para máxima fiabilidad, puedes habilitar ambos. La resolución nativa maneja Turnstile/reCAPTCHA sin costo adicional, y CapSolver captura todo lo demás:
// Seguro al 100%: ambos habilitados
const session = await client.sessions.create({
extensionIds: [capsolverExtId],
solveCaptchas: true, // La resolución nativa maneja Turnstile/reCAPTCHA
useProxy: true, // Requiere plan pagado — omite para el plan gratuito
// La extensión de CapSolver captura AWS WAF, GeeTest, etc.
});
Nota: Cuando ambos están habilitados para el mismo tipo de CAPTCHA (por ejemplo, reCAPTCHA), quien resuelva primero gana. En la práctica funciona bien: no hay conflictos.

Si prefieres no usar la extensión del navegador — o necesitas un control más preciso sobre el flujo de resolución — puedes usar directamente la API REST de CapSolver. Esto funciona con cualquier sesión de HyperBrowser, sin necesidad de cargar una extensión.
createTask en la API de CapSolvergetTaskResult hasta que el token esté listoimport { Hyperbrowser } from "@hyperbrowser/sdk";
import { chromium } from "playwright-core";
const HYPERBROWSER_API_KEY = process.env.HYPERBROWSER_API_KEY!;
const CAPSOLVER_API_KEY = process.env.CAPSOLVER_API_KEY!;
async function solveCaptchaViaAPI(
pageUrl: string,
siteKey: string
): Promise<string> {
// Crear tarea
const createRes = await fetch("https://api.capsolver.com/createTask", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
clientKey: CAPSOLVER_API_KEY,
task: {
type: "ReCaptchaV2TaskProxyLess",
websiteURL: pageUrl,
websiteKey: siteKey,
},
}),
});
const { taskId, errorDescription } = await createRes.json();
if (!taskId) throw new Error(`createTask falló: ${errorDescription}`);
// Consultar resultados
for (let i = 0; i < 40; i++) {
await new Promise((r) => setTimeout(r, 3000));
const resultRes = await fetch("https://api.capsolver.com/getTaskResult", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ clientKey: CAPSOLVER_API_KEY, taskId }),
});
const result = await resultRes.json();
if (result.status === "ready") {
return result.solution.gRecaptchaResponse;
}
}
throw new Error("Tiempo de solución agotado");
}
async function main() {
const client = new Hyperbrowser({ apiKey: HYPERBROWSER_API_KEY });
// No se necesita extensión — solo una sesión normal
const session = await client.sessions.create({
solveCaptchas: false,
});
const browser = await chromium.connectOverCDP(session.wsEndpoint);
const context = browser.contexts()[0];
const page = context.pages()[0] || await context.newPage();
try {
await page.goto("https://www.google.com/recaptcha/api2/demo");
// Detectar sitekey desde el DOM
const siteKey = await page.evaluate(() => {
const el = document.querySelector(".g-recaptcha[data-sitekey]");
return el?.getAttribute("data-sitekey") ?? "";
});
console.log("Sitekey:", siteKey);
// Resolver mediante la API de CapSolver
const token = await solveCaptchaViaAPI(page.url(), siteKey);
console.log("Token recibido, longitud:", token.length);
// Inyectar token
await page.evaluate((t) => {
const textarea = document.querySelector(
'textarea[name="g-recaptcha-response"]'
);
if (textarea) (textarea as HTMLTextAreaElement).value = t;
}, token);
// Enviar
await page.click("#recaptcha-demo-submit");
await page.waitForLoadState("networkidle");
const body = await page.textContent("body");
console.log(
body?.includes("Verification Success")
? "¡CAPTCHA resuelto mediante API!"
: body?.slice(0, 200)
);
} finally {
await browser.close();
await client.sessions.stop(session.id);
}
}
main().catch(console.error);
| Extensión | API | |
|---|---|---|
| Configuración | Subir ZIP una vez, reutilizar ID | Sin configuración — solo clave de API |
| Detección | Automática (script de contenido) | Manual (consultar DOM para sitekey) |
| Inyección de token | Automática | Manual (evaluar JS) |
| Control | Transparente — la extensión maneja todo | Control completo sobre cada paso |
| Mejor para | Automatización de "configurar y olvidar" | Lógica de resolución personalizada, estrategias de reintento |
Síntoma: CAPTCHA no resuelto; la página se comporta como si no hubiera extensión.
Posibles causas:
client.extensions.create() se esté pasando correctamentemanifest.json esté en la raíz del ZIP, no en una subcarpeta)assets/config.js tenga una clave de CapSolver válida antes de comprimirSolución:
# Verificar estructura del ZIP -- manifest.json debe estar en la raíz
unzip -l capsolver-extension.zip | head -20
# Debe mostrar: manifest.json (NO capsolver-extension/manifest.json)
Síntoma: La página carga, pero el CAPTCHA permanece sin resolver después de esperar.
Posibles causas:
waitForTimeout a 45-60 segundosSíntoma: chromium.connectOverCDP() lanza un error de conexión.
Solución: Asegúrese de que la sesión esté activa. Las sesiones tienen un tiempo de espera (por defecto varía según el plan). Crear una nueva sesión si la anterior expiró:
try {
const browser = await chromium.connectOverCDP(session.wsEndpoint);
} catch (err) {
console.log("Sesión expirada, creando una nueva...");
const newSession = await client.sessions.create({
extensionIds: [extensionId],
useProxy: true, // Requiere plan pagado — omitir para el plan gratuito
});
const browser = await chromium.connectOverCDP(newSession.wsEndpoint);
}
Síntoma: La extensión de CapSolver funciona cuando se carga localmente en Chrome, pero falla en sesiones de HyperBrowser.
Posibles causas:
config.js no incluido en el ZIP -- Verificar que el ZIP incluya el assets/config.js modificadoapi.capsolver.com. Asegúrese de que la red de la sesión de HyperBrowser permita HTTPS salienteLa subida de la extensión es una operación única. Almacene el extensionId devuelto y reutilícelo en todas las sesiones:
// Subir una vez
const ext = await client.extensions.create({ filePath: "capsolver-extension.zip" });
const CAPSOLVER_EXT_ID = ext.id;
// Reutilizar en cada sesión
for (const url of targetUrls) {
const session = await client.sessions.create({
extensionIds: [CAPSOLVER_EXT_ID],
useProxy: true, // Requiere plan pagado — omitir para el plan gratuito. Proxies residenciales reducen la frecuencia de CAPTCHA
});
// ... automatizar
await client.sessions.stop(session.id);
}
Los CAPTCHAS son más frecuentes (y más difíciles de resolver) cuando las solicitudes provienen de IPs de centros de datos. Los proxies integrados de HyperBrowser ayudan:
const session = await client.sessions.create({
extensionIds: [extensionId],
useProxy: true, // Requiere plan pagado — omitir para el plan gratuito. Proxies residenciales reducen la frecuencia de CAPTCHA
});
Los tipos de CAPTCHA diferentes toman tiempos diferentes para resolverse:
| Tipo de CAPTCHA | Tiempo de resolución típico | Tiempo de espera recomendado |
|---|---|---|
| reCAPTCHA v2 (casilla) | 5-15 segundos | 30 segundos |
| reCAPTCHA v2 (invisible) | 5-15 segundos | 25 segundos |
| reCAPTCHA v3 | 3-10 segundos | 20 segundos |
| Cloudflare Turnstile | 3-10 segundos | 20 segundos |
| AWS WAF | 5-15 segundos | 30 segundos |
| GeeTest v3/v4 | 5-20 segundos | 30 segundos |
Consejo: Si hay dudas, use 30 segundos. Es mejor esperar un poco más que enviar demasiado pronto.
Cada resolución de CAPTCHA cuesta créditos. Agregue verificación de saldo a su automatización para evitar interrupciones:
import axios from "axios";
async function checkBalance(apiKey: string): Promise<number> {
const response = await axios.post("https://api.capsolver.com/getBalance", {
clientKey: apiKey,
});
return response.data.balance || 0;
}
const balance = await checkBalance(process.env.CAPSOLVER_API_KEY!);
if (balance < 1) {
console.warn("Saldo de CapSolver bajo! Recargue en capsolver.com");
}
Siempre detenga sesiones cuando termine para evitar cargos innecesarios:
try {
// ... su código de automatización
} finally {
await browser.close();
await client.sessions.stop(session.id);
}
Si rota su clave de API de CapSolver, debe actualizar config.js, volver a comprimir y volver a subir:
# Actualizar la clave en config.js, luego:
cd capsolver-extension && zip -r ../capsolver-extension.zip . && cd ..
Luego suba el nuevo ZIP y actualice su extensionId almacenado.
HyperBrowser y CapSolver juntos proporcionan la configuración más completa para resolver CAPTCHA disponible para automatización de navegadores de IA:
La integración es sencilla: comprima la extensión de CapSolver, súbala una vez mediante el SDK de HyperBrowser y ájela a cualquier sesión. Sin detección de CAPTCHA a nivel de código, sin inyección de token, sin sondeo de API. La extensión maneja todo dentro del contexto del navegador.
Ya sea que esté construyendo raspadores web, agentes de IA o pipelines de pruebas automatizadas, esta combinación significa que los CAPTCHAS ya no son un obstáculo — independientemente del tipo.
¿Listo para comenzar? Regístrese en CapSolver y use el código de bonificación HYPERBROWSER para obtener un 6% adicional en su primer recarga!
HyperBrowser es una plataforma de infraestructura de navegador en la nube para agentes de IA. Proporciona sesiones de navegador gestionadas, aisladas con acceso nativo a CDP, para que pueda conectar Playwright, Puppeteer o Selenium a instancias de Chromium alojadas en la nube. Incluye proxies integrados, anti-detección y resolución nativa de CAPTCHA para Turnstile y reCAPTCHA.
HyperBrowser tiene una API de extensión de primer nivel. Comprime su directorio de extensión de Chrome, súbelo mediante client.extensions.create(), y recibe un extensionId. Pase este ID a client.sessions.create() y la extensión se carga automáticamente en la sesión del navegador en la nube.
CapSolver soporta reCAPTCHA v2 (casilla e invisible), reCAPTCHA v3, reCAPTCHA Enterprise, Cloudflare Turnstile, Cloudflare 5-second Challenge, AWS WAF, GeeTest v3/v4 y más. La extensión de Chrome detecta automáticamente el tipo de CAPTCHA y lo resuelve.
CapSolver ofrece precios competitivos según el tipo de CAPTCHA y el volumen. Visite capsolver.com para ver los precios actuales. Use el código HYPERBROWSER para obtener un 6% de bonificación en su primer recarga.
No. Suba la extensión una vez y reutilice el extensionId devuelto en todas las sesiones. Solo necesita volver a subirla si cambia la clave de API de CapSolver dentro de la extensión o actualiza la versión de la extensión.
Sí. HyperBrowser soporta Playwright, Puppeteer y Selenium. Reemplace la llamada a connectOverCDP de Playwright con el equivalente de Puppeteer:
import puppeteer from "puppeteer-core";
const browser = await puppeteer.connect({
browserWSEndpoint: session.wsEndpoint,
});
La extensión de CapSolver funciona igualmente independientemente del marco de automatización que use para conectarse.
HyperBrowser ofrece un plan gratuito con sesiones limitadas. Los planes pagados desbloquean más sesiones, tiempos de espera más largos y funciones adicionales. Visite hyperbrowser.ai para ver los precios actuales.
Descubre cómo la infraestructura de automatización de IA impulsada por LLM revoluciona el reconocimiento de CAPTCHA, mejorando la eficiencia de los procesos de negocio y reduciendo la intervención manual. Optimiza tus operaciones automatizadas con soluciones avanzadas de verificación.

Aprende a escalar la recopilación de datos para el entrenamiento de modelos de lenguaje grandes resolviendo CAPTCHAs a gran escala. Descubre estrategias automatizadas para construir conjuntos de datos de alta calidad para modelos de IA.
