Bash Script + cURL + CaptchaAI: Automatización CAPTCHA de Shell

Un script de Bash resuelve CAPTCHA con dos funciones y nada más: una hace el POST a in.php y devuelve el ID de la tarea, la otra consulta res.php en bucle hasta que el token está listo. Escríbelas una vez, guárdalas en un captchaai.sh y el resto del artículo son parámetros distintos sobre esas mismas dos funciones.

Ese es el motivo para quedarse en la shell cuando el trabajo vive en un servidor o en un runner de CI: no hay intérprete que instalar ni SDK que versionar. Desde ahí las llevamos a reCAPTCHA v2 y v3, Turnstile, CAPTCHA de imagen, paralelismo, reintentos, cron y Docker.

Qué necesitas y qué tipos cubre

• Bash 4.0 o superior y cURL, presentes por defecto en Linux y macOS.
• jq para leer el JSON de respuesta: apt install jq o brew install jq.
• Una API key de CaptchaAI (créala aquí). La facturación es por thread concurrente, con resoluciones ilimitadas dentro del plan: BASIC ($15/mes, 5 threads) le sobra a un script de cron; ADVANCE ($90/mes, 50 threads) es el escalón de los lotes en paralelo.

Cubre reCAPTCHA v2 y v3 (Enterprise e Invisible incluidos), Turnstile y Cloudflare Challenge, GeeTest v3, imagen/OCR, rejilla y BLS, además de CaptchaFox (beta), Friendly Captcha (beta) y Lemin (beta). hCaptcha y FunCaptcha (Arkose Labs) no son compatibles, y GeeTest v4 figura como próximamente.

Las dos funciones que sostienen el resto del script

Todo lo demás se apoya en dos funciones: una envía y otra espera. Los demás tipos de CAPTCHA solo cambian los parámetros.

Enviar la tarea a in.php

Acepta la clave y una lista variable de parámetros -d, así sirve para cualquier método. Devuelve el ID por stdout y los errores por stderr, la convención que permite encadenarla con $(...).

#!/bin/bash

CAPTCHAAI_URL="https://ocr.captchaai.com"

submit_task() {
    local api_key="$1"
    shift
    local params=("$@")

    local response
    response=$(curl -s -X POST "${CAPTCHAAI_URL}/in.php" \
        -d "key=${api_key}" \
        -d "json=1" \
        "${params[@]}")

    local status
    status=$(echo "$response" | jq -r '.status')
    local request
    request=$(echo "$response" | jq -r '.request')

    if [ "$status" != "1" ]; then
        echo "ERROR: Submit failed: $request" >&2
        return 1
    fi

    echo "$request"
}

Consultar el resultado en res.php

Aquí fallan los scripts caseros: consultan demasiado rápido, no distinguen CAPCHA_NOT_READY de un error real, o se quedan colgados. Esta versión espera un intervalo fijo y sale con código distinto de cero al agotar el margen.

poll_result() {
    local api_key="$1"
    local task_id="$2"
    local max_wait="${3:-300}"
    local interval="${4:-5}"

    local elapsed=0

    while [ "$elapsed" -lt "$max_wait" ]; do
        sleep "$interval"
        elapsed=$((elapsed + interval))

        local response
        response=$(curl -s "${CAPTCHAAI_URL}/res.php?key=${api_key}&action=get&id=${task_id}&json=1")

        local status
        status=$(echo "$response" | jq -r '.status')
        local request
        request=$(echo "$response" | jq -r '.request')

        if [ "$request" = "CAPCHA_NOT_READY" ]; then
            echo "Waiting... (${elapsed}s/${max_wait}s)" >&2
            continue
        fi

        if [ "$status" != "1" ]; then
            echo "ERROR: Solve failed: $request" >&2
            return 1
        fi

        echo "$request"
        return 0
    done

    echo "ERROR: Timeout after ${max_wait}s" >&2
    return 1
}

Los valores por defecto, 5 segundos entre consultas y 300 de tope, son un buen punto de partida: sondear cada segundo solo gasta peticiones.

Resolver reCAPTCHA v2 desde la terminal

Pasas method=userrecaptcha, el googlekey de la página y la URL del formulario. El token que vuelve es el valor que enviarás en el campo g-recaptcha-response.

solve_recaptcha_v2() {
    local api_key="$1"
    local site_url="$2"
    local sitekey="$3"

    echo "Submitting reCAPTCHA v2..." >&2
    local task_id
    task_id=$(submit_task "$api_key" \
        -d "method=userrecaptcha" \
        -d "googlekey=${sitekey}" \
        -d "pageurl=${site_url}")

    if [ $? -ne 0 ]; then return 1; fi
    echo "Task ID: $task_id" >&2

    echo "Polling for solution..." >&2
    local token
    token=$(poll_result "$api_key" "$task_id")

    if [ $? -ne 0 ]; then return 1; fi
    echo "$token"
}

# Usage
API_KEY="YOUR_API_KEY"
TOKEN=$(solve_recaptcha_v2 "$API_KEY" \
    "https://staging.example.com/qa-login" \
    "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-")

echo "Token: ${TOKEN:0:50}..."

El sitekey está en el atributo data-sitekey del widget. No cambia entre visitas, así que puedes guardarlo como constante.

Cloudflare Turnstile

Mismo patrón con method=turnstile. La diferencia llega al final: el token viaja en el campo cf-turnstile-response, no en g-recaptcha-response. Confundirlos es el error más habitual al migrar un script.

solve_turnstile() {
    local api_key="$1"
    local site_url="$2"
    local sitekey="$3"

    local task_id
    task_id=$(submit_task "$api_key" \
        -d "method=turnstile" \
        -d "key=${sitekey}" \
        -d "pageurl=${site_url}")

    if [ $? -ne 0 ]; then return 1; fi

    poll_result "$api_key" "$task_id"
}

# Usage
TOKEN=$(solve_turnstile "$API_KEY" \
    "https://example.com/form" \
    "0x4AAAAAAAB5...")

reCAPTCHA v3 y el parámetro action

La v3 no muestra widget: puntúa la sesión en segundo plano. Solo añades version=v3 y el action que declara el sitio, y ese action importa: si el formulario declara login y tú envías verify, la puntuación puede quedar bajo el umbral.

solve_recaptcha_v3() {
    local api_key="$1"
    local site_url="$2"
    local sitekey="$3"
    local action="${4:-verify}"

    local task_id
    task_id=$(submit_task "$api_key" \
        -d "method=userrecaptcha" \
        -d "googlekey=${sitekey}" \
        -d "pageurl=${site_url}" \
        -d "version=v3" \
        -d "action=${action}" \

    if [ $? -ne 0 ]; then return 1; fi

    poll_result "$api_key" "$task_id"
}

CAPTCHA de imagen y OCR

Los portales públicos siguen llenos del CAPTCHA clásico de caracteres deformados. Aquí no hay sitekey: envías la imagen en base64 con method=base64 y recibes el texto.

solve_image_captcha() {
    local api_key="$1"
    local image_path="$2"

    if [ ! -f "$image_path" ]; then
        echo "ERROR: File not found: $image_path" >&2
        return 1
    fi

    local base64_data
    base64_data=$(base64 -w 0 "$image_path" 2>/dev/null || base64 "$image_path")

    local task_id
    task_id=$(submit_task "$api_key" \
        -d "method=base64" \
        --data-urlencode "body=${base64_data}")

    if [ $? -ne 0 ]; then return 1; fi

    poll_result "$api_key" "$task_id"
}

# From URL
solve_image_from_url() {
    local api_key="$1"
    local image_url="$2"
    local tmp_file
    tmp_file=$(mktemp /tmp/captcha_XXXXXX.png)

    curl -s -o "$tmp_file" "$image_url"
    local result
    result=$(solve_image_captcha "$api_key" "$tmp_file")
    rm -f "$tmp_file"

    echo "$result"
}

# Usage
TEXT=$(solve_image_captcha "$API_KEY" "captcha.png")
echo "CAPTCHA text: $TEXT"

Ojo con base64 en macOS: la opción -w 0 es de GNU y BSD no la reconoce; la función lo cubre con un ||.

Empaquetar todo en una biblioteca reutilizable

Guarda este archivo como captchaai.sh y cárgalo con source: un único sitio donde ajustar el sondeo y el tiempo de espera.

#!/bin/bash
# CaptchaAI Solver Library
# Source this file: source ./captchaai.sh

CAPTCHAAI_URL="https://ocr.captchaai.com"
CAPTCHAAI_POLL_INTERVAL=5
CAPTCHAAI_MAX_WAIT=300

captchaai_submit() {
    local api_key="$1"; shift
    local response
    response=$(curl -s -X POST "${CAPTCHAAI_URL}/in.php" \
        -d "key=${api_key}" -d "json=1" "$@")
    local status=$(echo "$response" | jq -r '.status')
    local request=$(echo "$response" | jq -r '.request')
    [ "$status" = "1" ] && echo "$request" || { echo "Submit: $request" >&2; return 1; }
}

captchaai_poll() {
    local api_key="$1" task_id="$2" elapsed=0
    while [ "$elapsed" -lt "$CAPTCHAAI_MAX_WAIT" ]; do
        sleep "$CAPTCHAAI_POLL_INTERVAL"
        elapsed=$((elapsed + CAPTCHAAI_POLL_INTERVAL))
        local resp=$(curl -s "${CAPTCHAAI_URL}/res.php?key=${api_key}&action=get&id=${task_id}&json=1")
        local req=$(echo "$resp" | jq -r '.request')
        local st=$(echo "$resp" | jq -r '.status')
        [ "$req" = "CAPCHA_NOT_READY" ] && continue
        [ "$st" = "1" ] && { echo "$req"; return 0; }
        echo "Solve: $req" >&2; return 1
    done
    echo "Timeout" >&2; return 1
}

captchaai_balance() {
    local api_key="$1"
    curl -s "${CAPTCHAAI_URL}/res.php?key=${api_key}&action=getbalance&json=1" | jq -r '.request'
}

captchaai_recaptcha_v2() {
    local key="$1" url="$2" sk="$3"
    local tid=$(captchaai_submit "$key" -d "method=userrecaptcha" -d "googlekey=$sk" -d "pageurl=$url") || return 1
    captchaai_poll "$key" "$tid"
}

captchaai_turnstile() {
    local key="$1" url="$2" sk="$3"
    local tid=$(captchaai_submit "$key" -d "method=turnstile" -d "sitekey=$sk" -d "pageurl=$url") || return 1
    captchaai_poll "$key" "$tid"
}

captchaai_image() {
    local key="$1" path="$2"
    local b64=$(base64 -w 0 "$path" 2>/dev/null || base64 "$path")
    local tid=$(captchaai_submit "$key" -d "method=base64" --data-urlencode "body=$b64") || return 1
    captchaai_poll "$key" "$tid"
}

Fíjate en captchaai_balance: comprobar el saldo antes de un lote evita que un trabajo nocturno falle en silencio.

Cargar la biblioteca desde otro script

#!/bin/bash
source ./captchaai.sh

API_KEY="YOUR_API_KEY"

# Check balance
echo "Balance: $(captchaai_balance "$API_KEY")"

# Solve reCAPTCHA v2
TOKEN=$(captchaai_recaptcha_v2 "$API_KEY" \
    "https://staging.example.com/qa-login" \
    "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-")

echo "Token: ${TOKEN:0:50}..."

Del token al formulario

Resolver el CAPTCHA es la mitad del trabajo; la otra mitad es enviar el token en el mismo campo que habría rellenado el navegador.

submit_form_with_token() {
    local url="$1"
    local token="$2"
    shift 2

    curl -s -X POST "$url" \
        -d "g-recaptcha-response=${token}" \
        "$@"
}

# Usage: solve then submit
TOKEN=$(captchaai_recaptcha_v2 "$API_KEY" \
    "https://staging.example.com/qa-login" "SITEKEY")

RESPONSE=$(submit_form_with_token "https://staging.example.com/qa-login" \
    "$TOKEN" \
    -d "[email protected]" \
    -d "password=password")

echo "Response: $RESPONSE"

Un caso habitual en la región: los equipos que hacen QA sobre portales de trámites en línea, tan frecuentes en España y en Latinoamérica y casi siempre protegidos con CAPTCHA de imagen o reCAPTCHA, aplican este patrón contra su propio staging tras cada despliegue. Trabaja siempre sobre sistemas propios o entornos autorizados, y respeta los términos de servicio y la normativa de protección de datos aplicable (GDPR y LOPDGDD, LFPDPPP y equivalentes).

Resolver varios CAPTCHA a la vez

Como la facturación es por thread concurrente y no por resolución, el paralelismo no encarece nada: aprovechas los threads que ya pagas. En Bash son subshells en segundo plano y un directorio temporal donde cada proceso deja su resultado.

#!/bin/bash
source ./captchaai.sh

API_KEY="YOUR_API_KEY"
RESULTS_DIR=$(mktemp -d)

# Define tasks
declare -A TASKS
TASKS["site-a"]="https://site-a.com|SITEKEY_A"
TASKS["site-b"]="https://site-b.com|SITEKEY_B"
TASKS["site-c"]="https://site-c.com|SITEKEY_C"

# Launch parallel solves
pids=()
for name in "${!TASKS[@]}"; do
    IFS='|' read -r url sitekey <<< "${TASKS[$name]}"
    (
        token=$(captchaai_recaptcha_v2 "$API_KEY" "$url" "$sitekey" 2>/dev/null)
        if [ $? -eq 0 ]; then
            echo "$token" > "${RESULTS_DIR}/${name}.token"
        else
            echo "FAILED" > "${RESULTS_DIR}/${name}.token"
        fi
    ) &
    pids+=($!)
done

# Wait for all
for pid in "${pids[@]}"; do
    wait "$pid"
done

# Collect results
echo "=== Results ==="
for name in "${!TASKS[@]}"; do
    token=$(cat "${RESULTS_DIR}/${name}.token")
    if [ "$token" = "FAILED" ]; then
        echo "$name: FAILED"
    else
        echo "$name: ${token:0:50}..."
    fi
done

rm -rf "$RESULTS_DIR"

Ajusta el número de tareas simultáneas a tu plan: con los 5 threads de BASIC, lanzar treinta subshells solo hace que las sobrantes esperen turno.

Reintentos con retroceso exponencial

No todos los errores merecen un reintento: ERROR_NO_SLOT_AVAILABLE y ERROR_CAPTCHA_UNSOLVABLE son transitorios; ERROR_WRONG_USER_KEY o ERROR_ZERO_BALANCE no se arreglan solos. Esta función los distingue y espacia los intentos con retroceso exponencial más un margen aleatorio.

solve_with_retry() {
    local api_key="$1"
    local solve_cmd="$2"
    shift 2
    local max_retries="${1:-3}"

    local retryable_errors=("ERROR_NO_SLOT_AVAILABLE" "ERROR_CAPTCHA_UNSOLVABLE")
    local attempt=0

    while [ "$attempt" -le "$max_retries" ]; do
        if [ "$attempt" -gt 0 ]; then
            local delay=$((2 ** attempt + RANDOM % 3))
            echo "Retry $attempt/$max_retries after ${delay}s..." >&2
            sleep "$delay"
        fi

        local result
        result=$($solve_cmd "$api_key" "${@:2}")

        if [ $? -eq 0 ]; then
            echo "$result"
            return 0
        fi

        # Check if error is retryable
        local is_retryable=0
        for err in "${retryable_errors[@]}"; do
            if echo "$result" | grep -q "$err"; then
                is_retryable=1
                break
            fi
        done

        if [ "$is_retryable" -eq 0 ]; then
            echo "$result"
            return 1
        fi

        attempt=$((attempt + 1))
    done

    echo "Max retries exceeded" >&2
    return 1
}

Llevarlo a producción: cron y Docker

# Edit crontab: crontab -e
# Run daily at 8 AM
0 8 * * * /path/to/captcha-automation.sh >> /var/log/captcha.log 2>&1

Un trabajo cron sin registro es un trabajo del que nadie sabe si funciona. Este ejemplo escribe un log con marca de tiempo, comprueba el saldo y sale con código 1 si algo falla.

#!/bin/bash
source /path/to/captchaai.sh

API_KEY="YOUR_API_KEY"
LOG_FILE="/var/log/captcha-$(date +%Y%m%d).log"

log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" >> "$LOG_FILE"; }

# Check balance first
BALANCE=$(captchaai_balance "$API_KEY")
log "Balance: $BALANCE"

if (( $(echo "$BALANCE < 1.0" | bc -l) )); then
    log "WARNING: Low balance!"
    exit 1
fi

# Solve and process
TOKEN=$(captchaai_recaptcha_v2 "$API_KEY" \
    "https://portal.example.com" "SITEKEY")

if [ $? -eq 0 ]; then
    log "Solved successfully"
    # Submit form, download data, etc.
    curl -s "https://portal.example.com/data" \
        -d "g-recaptcha-response=$TOKEN" \
        -o "/data/export-$(date +%Y%m%d).csv"
    log "Data exported"
else
    log "ERROR: Failed to solve CAPTCHA"
    exit 1
fi

Para contenedores, Alpine con bash, curl y jq da una imagen de pocos megabytes, suficiente para un job de Kubernetes.

FROM alpine:3.19

RUN apk add --no-cache bash curl jq

COPY captchaai.sh /usr/local/lib/captchaai.sh
COPY automation.sh /app/automation.sh

RUN chmod +x /app/automation.sh

CMD ["/app/automation.sh"]

Errores frecuentes

Preguntas frecuentes

¿Cada cuánto conviene consultar res.php?

Cada 5 segundos, con un tope de 300. Sondear cada segundo no acelera la resolución: solo multiplica las peticiones y te acerca antes al límite de tu plan.

¿Cómo guardo la API key sin dejarla en el repositorio?

Con variables de entorno: export CAPTCHAAI_KEY="..." y referencia $CAPTCHAAI_KEY en el script. En cron, cárgala desde un archivo con permisos 600; en Docker, como variable de entorno o secreto del orquestador.

¿Sirve este mismo script para hCaptcha?

No. CaptchaAI no es compatible con hCaptcha ni con FunCaptcha (Arkose Labs), y GeeTest v4 figura como próximamente. El script cubre reCAPTCHA v2 y v3, Turnstile, Cloudflare Challenge, GeeTest v3, imagen y rejilla.

¿Funciona igual en macOS que en Linux?

Sí, con una salvedad: macOS trae las versiones BSD de base64, date y sed, cuyas opciones no siempre coinciden con las de GNU. Prueba cualquier utilidad nueva en la máquina donde correrá el cron.

Sigue por aquí

• Automatización con PowerShell en Windows
• Configurar tu API key y la autenticación

Dos comandos cURL y tienes el token: obtén tu API key y llévalo a tus scripts de Bash.