API Tutorials

Bash Script + cURL + CaptchaAI: Automação Shell CAPTCHA

Automação Cloudflare Turnstile reCAPTCHA v2 Image OCR cURL
Por Equipe CaptchaAI Brasil
Publicado em May 03, 2026
Bash Script + cURL + CaptchaAI: Automação Shell CAPTCHA
Imagem em destaque indisponível

Não, você não precisa instalar Python nem Node.js para resolver um CAPTCHA num cron job. Se a imagem já tem bash, curl e jq — quase toda imagem Linux tem — dá para chamar a API HTTP da CaptchaAI direto do shell.

É o cenário típico de um worker Ubuntu na região sa-east-1 (São Paulo) da AWS, disparado por cron às 8h para preencher um formulário com reCAPTCHA antes de baixar um relatório. Este guia traz as funções Bash prontas para reCAPTCHA v2/v3, Cloudflare Turnstile e CAPTCHA de imagem, e como encaixá-las em cron, CI/CD e Docker.

Quando vale a pena resolver CAPTCHA só com Bash e cURL

  • Zero dependências — bash e curl já vêm em praticamente todo Linux/macOS
  • Imagem enxuta — sem runtime, sem gerenciador de pacotes, sem etapa de build extra
  • Nativo do cron — agenda com o cron padrão do sistema, sem wrapper
  • Pronto para CI/CD — roda em Docker, GitHub Actions, Jenkins, GitLab CI sem ajuste
  • Encadeável — combine a resolução com jq, grep, awk e o resto da caixa de ferramentas Unix

O que você precisa antes de começar

Basta Bash 4.0+ e cURL — já instalados por padrão em qualquer Linux/macOS — mais jq para interpretar JSON (apt install jq ou brew install jq) e uma chave de API CaptchaAI (pegue a sua aqui).

As duas funções que sustentam o script

Tudo daqui em diante é uma camada fina sobre duas funções: uma envia a tarefa, a outra consulta o resultado.

Enviando a tarefa

#!/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"
}

Consultando o resultado (polling)

A tarefa é assíncrona — a função abaixo consulta res.php até o status virar 1 ou o max_wait estourar.

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
}

Resolvendo reCAPTCHA v2 e Cloudflare Turnstile via cURL

Com submit_task e poll_result prontas, resolver cada tipo é só trocar o method e os parâmetros da chamada.

reCAPTCHA v2

Junta as duas funções num só fluxo e devolve o token pronto para o 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}..."

Cloudflare Turnstile

Mesma lógica do reCAPTCHA v2, mas com method=turnstile e key no lugar de googlekey. O Turnstile normalmente resolve em menos de 10 segundos.

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...")

Adaptando o script para reCAPTCHA v3 e CAPTCHA de imagem

Dois casos que fogem do padrão sitekey + pageurl: o v3 não tem desafio visual, e a imagem não tem sitekey nenhum.

reCAPTCHA v3

O v3 não tem desafio visual — só uma action (ex.: verify) e um score_qa mínimo, passados como parâmetro extra.

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

    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}" \
        -d "score_qa=${score_qa}")

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

    poll_result "$api_key" "$task_id"
}

CAPTCHA de imagem (OCR) com base64

Sem sitekey aqui — a própria imagem vai em base64 com method=base64, seja de um arquivo local ou baixada de uma URL.

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"

Montando a biblioteca completa: captchaai.sh

Junte as funções soltas num único captchaai.sh e dê source nele sempre que precisar, em vez de copiar e colar em cada script novo.

#!/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"
}

Como usar a biblioteca em outro 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}..."

Do token ao formulário: envio e execução paralela

Com o token em mãos, falta enviar o formulário — e, se forem vários sites, decidir se vale resolver em série ou em paralelo.

Enviando o formulário depois de resolver o token

O token vai no campo g-recaptcha-response do POST — o resto é um curl comum.

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"

Resolvendo vários CAPTCHAs em paralelo

Dispare cada resolução como job de segundo plano (& + wait) em vez de esperar uma de cada vez. Cada job ocupa uma thread do plano até o token sair — estourar o limite só coloca o excedente na fila.

#!/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"

Retentativas com backoff exponencial

ERROR_NO_SLOT_AVAILABLE e ERROR_CAPTCHA_UNSOLVABLE são transitórios e valem retentativa com atraso crescente; os demais (chave inválida, saldo zerado) são definitivos.

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
}

Rodando em produção: cron e Docker

Sem runtime para instalar, colocar isso em produção é só cron ou uma imagem Docker enxuta.

Agendando execuções com cron

Sem etapa de setup antes de rodar, o crontab fica direto ao ponto:

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

Script de exemplo para produção

#!/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

Rodando em containers Docker/Alpine

Só bash, curl e jq — sem camada extra de Python, pip ou node_modules.

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"]

Erros comuns e como resolver

Erro Causa Correção
ERROR_WRONG_USER_KEY Chave de API inválida Verifique a chave no painel
ERROR_ZERO_BALANCE Sem fundos Conta de recarga
curl: (60) SSL certificate Pacote CA ausente Adicione --cacert /path/to/ca-bundle.crt ou -k para teste
jq: command not found jq não instalado apt install jq ou brew install jq
base64: invalid option -- 'w' Sintaxe base64 do macOS Use base64 file em vez de base64 -w 0 file
Resposta vazia Problema de rede Adicione o sinalizador -v ao curl para depuração

Perguntas frequentes

Preciso instalar Python ou Node.js para isso funcionar?

Não. Só bash, curl e jq — sem runtime nem pip/npm.

Como evito estourar o limite de threads do meu plano ao resolver em paralelo?

Cada job em paralelo ocupa uma thread até o token sair; o excedente só espera na fila. Limite os jobs simultâneos ao teto do plano (BASIC — US$ 15/mês, 5 threads — ou ADVANCE — US$ 90/mês, 50 threads).

É seguro guardar a chave de API dentro do crontab?

Evite. Exporte a chave num arquivo separado (source /etc/captchaai.env) com chmod 600, fora do crontab -e — o crontab costuma ser legível por outros processos.

O que fazer quando o polling estoura o tempo limite?

poll_result devolve ERROR: Timeout after ${max_wait}s. Geralmente é fila cheia ou sitekey/pageurl errados — confira com captchaai_balance antes de aumentar o max_wait.

jq é realmente obrigatório para interpretar o JSON de resposta?

Na prática, sim: dá para usar grep/sed, mas jq -r '.status' é bem mais confiável do que casar regex contra JSON.

Guias relacionados

Resolva CAPTCHA na linha de comando com as suas próprias funções Bash — obtenha sua chave de API e automatize com cron, CI/CD ou Docker.

Os comentários estão desativados para este artigo.