cURL + CaptchaAI: Solve CAPTCHA via CLI

Tidak semua orang perlu SDK cuma untuk memvalidasi satu endpoint reCAPTCHA di CI runner. Kalau API-nya sudah bisa dipanggil lewat HTTP biasa, cURL saja cukup — dan REST API CaptchaAI memang dirancang seperti itu: kirim task ke in.php, polling res.php, dan Anda dapat token tanpa install apa pun selain cURL, yang sudah tersedia di hampir semua image Linux, macOS, dan bahkan runner Windows.

Panduan ini berisi perintah dasarnya, skrip Bash siap pakai untuk polling otomatis, versi PowerShell untuk yang kerja di Windows, sampai cara menghitung berapa thread yang dibutuhkan kalau Anda menjalankan banyak proses curl sekaligus.

Kapan cURL Lebih Praktis daripada SDK

cURL menang di tiga situasi yang sering ditemui automation developer di Indonesia:

• Testing cepat — validasi sitekey atau API key tanpa bikin project baru, cukup satu baris di terminal.
• CI runner minim dependency — image Docker yang ramping sering tidak punya Python atau Node.js terpasang, tapi cURL hampir selalu ada.
• Skrip cron atau monitoring ringan — kalau kebutuhannya cuma kirim task, polling, lalu simpan token, menambah bahasa pemrograman baru cuma menambah beban maintenance.

Kalau proyek Anda sudah punya codebase Python atau Node.js yang jalan, SDK bawaan bahasa itu tetap lebih nyaman untuk logic yang kompleks. cURL cocok untuk bagian yang berdiri sendiri: validasi, health check, atau skrip operasional yang harus tetap jalan walau runtime lain gagal deploy.

Yang Diperlukan

Perintah Dasar via curl

Tiga panggilan ini menutupi hampir semua kebutuhan harian: cek saldo, kirim task, dan ambil hasilnya.

Cek Saldo

curl -s "https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=getbalance"

Output: 1.234

Submit reCAPTCHA v2

curl -s "https://ocr.captchaai.com/in.php?key=YOUR_API_KEY&method=userrecaptcha&googlekey=6Le-wvkS...&pageurl=https://example.com"

Output: OK|73548291 — angka setelah OK| adalah task ID yang Anda pakai untuk polling.

Polling untuk Hasil

curl -s "https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=get&id=73548291"

Output: OK|03AGdBq24PBCbw... atau CAPCHA_NOT_READY selama token belum siap.

Bikin Script Solver Bash Otomatis

Tiga perintah manual di atas cukup untuk testing, tapi produksi butuh loop polling dan penanganan error. Simpan sebagai solve_captcha.sh:

#!/bin/bash
set -euo pipefail

API_KEY="${CAPTCHAAI_API_KEY:?Set CAPTCHAAI_API_KEY environment variable}"
BASE_URL="https://ocr.captchaai.com"

solve_recaptcha() {
    local site_key="$1"
    local page_url="$2"
    local timeout="${3:-300}"

    # Submit
    local response
    response=$(curl -s "${BASE_URL}/in.php?key=${API_KEY}&method=userrecaptcha&googlekey=${site_key}&pageurl=${page_url}")

    if [[ ! "$response" == OK|* ]]; then
        echo "ERROR: Submit failed: $response" >&2
        return 1
    fi

    local task_id="${response#OK|}"
    echo "Submitted task: $task_id" >&2

    # Poll
    local deadline=$((SECONDS + timeout))
    while (( SECONDS < deadline )); do
        sleep 5
        local result
        result=$(curl -s "${BASE_URL}/res.php?key=${API_KEY}&action=get&id=${task_id}")

        if [[ "$result" == "CAPCHA_NOT_READY" ]]; then
            echo "Waiting..." >&2
            continue
        fi

        if [[ "$result" == OK|* ]]; then
            echo "${result#OK|}"
            return 0
        fi

        echo "ERROR: Solve failed: $result" >&2
        return 1
    done

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

# Usage: ./solve_captcha.sh SITE_KEY PAGE_URL
if [[ $# -ge 2 ]]; then
    solve_recaptcha "$1" "$2"
fi

Default timeout 300 detik sengaja longgar: reCAPTCHA v2 biasanya rampung di bawah 60 detik, jadi ada banyak ruang untuk antrean di jam sibuk tanpa skrip berhenti prematur.

Jadikan executable:

chmod +x solve_captcha.sh

Jalankan:

export CAPTCHAAI_API_KEY="your_key_here"
./solve_captcha.sh "6Le-wvkS..." "https://example.com"

Menyelesaikan Cloudflare Turnstile via curl

Beda method saja, sisanya sama persis — Turnstile biasanya selesai di bawah 10 detik, jauh lebih cepat dibanding reCAPTCHA v2:

curl -s "https://ocr.captchaai.com/in.php?key=${CAPTCHAAI_API_KEY}&method=turnstile&sitekey=0x4AAAAA...&pageurl=https://example.com"

Menyelesaikan CAPTCHA Gambar via curl

Untuk CAPTCHA gambar, encode dulu ke base64 sebelum dikirim sebagai parameter body:

# Encode image to base64
IMAGE_B64=$(base64 -w 0 captcha.png)

# Submit
curl -s "https://ocr.captchaai.com/in.php?key=${CAPTCHAAI_API_KEY}&method=base64&body=${IMAGE_B64}"

Untuk gambar besar, base64 di query string gampang melebihi batas URL. Gunakan multipart POST supaya file dikirim langsung, bukan di-encode di URL:

curl -s -X POST "https://ocr.captchaai.com/in.php" \
  -F "key=${CAPTCHAAI_API_KEY}" \
  -F "method=post" \
  -F "file=@captcha.png"

Gabungkan Solve dan Submit Token dalam Satu Pipeline

Untuk QA otomatis — misalnya tim yang menguji alur login sendiri sebelum rilis — solve dan submit token bisa digabung jadi satu skrip:

#!/bin/bash
# Solve CAPTCHA and submit form in one pipeline

API_KEY="${CAPTCHAAI_API_KEY}"
SITE_KEY="6Le-wvkS..."
TARGET_URL="https://staging.example.com/qa-login"

# Solve
TOKEN=$(./solve_captcha.sh "$SITE_KEY" "$TARGET_URL")

if [[ -z "$TOKEN" ]]; then
    echo "Failed to solve CAPTCHA"
    exit 1
fi

# Submit form with token
curl -s -X POST "$TARGET_URL" \
  -d "username=user" \
  -d "password=pass" \
  -d "g-recaptcha-response=${TOKEN}"

Ganti TARGET_URL dengan endpoint staging Anda sendiri — pola ini untuk memvalidasi form yang Anda uji, bukan untuk menembus proteksi milik pihak lain.

Proses Batch dari Daftar URL

Skrip ini cocok untuk agensi price-monitoring atau tim data yang perlu memvalidasi ratusan halaman dalam satu jalan cron:

#!/bin/bash
# Input file: urls.txt (one URL per line)

while IFS= read -r url; do
    echo "Processing: $url"
    TOKEN=$(./solve_captcha.sh "6Le-wvkS..." "$url")
    if [[ -n "$TOKEN" ]]; then
        echo "$url,$TOKEN" >> results.csv
        echo "  Solved ✓"
    else
        echo "  Failed ✗"
    fi
done < urls.txt

Hasilnya tersimpan rapi di results.csv, siap diimpor ke spreadsheet atau dashboard internal tanpa parsing tambahan.

Jalankan dari PowerShell (Windows)

Buat tim yang deploy dari mesin Windows atau runner Windows di CI, logic-nya identik — cuma sintaksnya PowerShell:

$ApiKey = $env:CAPTCHAAI_API_KEY
$BaseUrl = "https://ocr.captchaai.com"

# Submit
$response = Invoke-RestMethod "${BaseUrl}/in.php?key=${ApiKey}&method=userrecaptcha&googlekey=6Le-wvkS...&pageurl=https://example.com"

if ($response -match '^OK\|(.+)$') {
    $taskId = $Matches[1]
    Write-Host "Task: $taskId"
} else {
    Write-Error "Submit failed: $response"
    exit 1
}

# Poll
do {
    Start-Sleep -Seconds 5
    $result = Invoke-RestMethod "${BaseUrl}/res.php?key=${ApiKey}&action=get&id=${taskId}"
} while ($result -eq 'CAPCHA_NOT_READY')

if ($result -match '^OK\|(.+)$') {
    $token = $Matches[1]
    Write-Host "Token: $token"
} else {
    Write-Error "Solve failed: $result"
}

Berapa Thread yang Dibutuhkan untuk curl Paralel

CaptchaAI menagih per thread, bukan per solve — jadi setiap proses curl yang sedang menunggu hasil (dari task dikirim sampai token didapat) memakai satu thread selama itu berlangsung, dan bebas dipakai ulang begitu selesai.

Ini penting kalau skrip batch di atas dijalankan paralel, bukan satu per satu. Sebagai patokan kasar:

• 5–10 proses curl paralel untuk testing atau monitoring skala kecil masih muat di BASIC ($15/bulan, 5 thread) kalau antreannya pendek, tapi STANDARD ($30/bulan, 15 thread) memberi ruang gerak lebih aman.
• Puluhan proses paralel — misalnya validasi ratusan halaman produk tiap jam dari VPS di region ap-southeast-1 (Singapura) atau asia-southeast2 (Jakarta) — lebih cocok di ADVANCE ($90/bulan, 50 thread), dengan solve tanpa batas per thread di dalam paket itu.

Kalau tim Anda mengolah data publik untuk keperluan riset harga atau pemantauan pasar, ingat UU Pelindungan Data Pribadi (UU 27/2022) tetap berlaku — batasi scraping pada data yang memang berhak Anda proses.

Pemecahan Masalah

Pertanyaan Umum

Bagaimana cara menjadwalkan solve_captcha.sh agar berjalan otomatis?

Pakai cron di Linux/macOS atau Task Scheduler di Windows, panggil skrip dengan argumen sitekey dan page URL, lalu redirect output ke log. Untuk runner CI seperti GitHub Actions atau GitLab CI, simpan CAPTCHAAI_API_KEY sebagai secret dan jalankan skrip yang sama di salah satu step pipeline.

Perlukah install SDK Python atau Node.js kalau sudah pakai cURL?

Tidak. cURL bawaan sistem operasi sudah cukup untuk memanggil in.php dan res.php — tidak ada overhead HTTP tambahan dibanding HTTP client Python atau Node.js. SDK baru relevan kalau Anda butuh parsing respons otomatis atau retry logic bawaan; untuk skrip Bash sederhana, cURL plus jq (opsional) sudah cukup.

Kenapa polling saya sering timeout di koneksi mobile yang lambat?

Kalau jaringan sering putus-nyambung, naikkan interval polling dan tambahkan retry di layer HTTP, bukan cuma di layer aplikasi. Tambahkan --connect-timeout 30 --retry 3 ke setiap panggilan curl, dan pertimbangkan menaikkan timeout default skrip dari 300 detik supaya polling reCAPTCHA v2 yang lebih lambat tidak terpotong.

Berapa banyak thread yang saya butuhkan untuk beberapa proses curl paralel?

Setiap proses curl yang sedang menunggu hasil memakai satu thread selama solve berlangsung. Untuk 10 proses paralel, BASIC (5 thread) biasanya sudah pas-pasan — STANDARD ($30/bulan, 15 thread) lebih realistis untuk skala ini. ADVANCE ($90/bulan, 50 thread) baru relevan kalau jumlah proses paralelnya naik ke puluhan.

Bagaimana cara encode karakter khusus di parameter URL cURL?

Gunakan --data-urlencode pada cURL POST, atau curl -G --data-urlencode "pageurl=..." untuk request GET, supaya karakter seperti & atau spasi di URL halaman target tidak merusak parameter lain.

Panduan Terkait

• axios + CaptchaAI tanpa browser
• Setup dan autentikasi API key
• Format respons API CaptchaAI