cURL + CaptchaAI: CLI CAPTCHA Çözme

Bir CI/CD ardışık düzeninde, uzak bir sunucuda ya da tek satırlık bir kabuk betiğinde CAPTCHA çözmeniz gerektiğinde ekstra bir kütüphane kurmanız gerekmez: curl ile doğrudan CaptchaAI REST API'sine bağlanabilirsiniz. İhtiyacınız olan tek şey API anahtarınız ve iki uç nokta — görev gönderdiğiniz in.php ile sonucu aldığınız res.php. Bu rehber, bakiye kontrolünden token'ı bir forma göndermeye kadar akışın tamamını terminalden gösterir.

cURL yaklaşımı özellikle Türkiye'deki serbest otomasyon geliştiricileri ve e-ticaret QA ekipleri için pratiktir: Python veya Node.js kurmadan, mevcut bir Bash betiğine ya da GitHub Actions iş akışına birkaç satırda entegrasyon yapabilirsiniz. Bağımlılık yönetmek yok, sürüm çakışması yok — sadece HTTP.

Bu yaklaşım özellikle şu durumlarda öne çıkar:

• SDK kuramadığınız minimal sunucu veya konteyner ortamları.
• CI/CD adımlarında hızlı bir doğrulama gerektiğinde.
• Farklı dillerdeki betiklerden ortak bir çözüm mantığını çağırmak istediğinizde.

Başlamadan önce: gereksinimler

API anahtarınızı panelden alıp CAPTCHAAI_API_KEY ortam değişkenine atarsanız, aşağıdaki tüm komutları anahtarınızı düz metin olarak koda yazmadan çalıştırabilirsiniz.

Temel API çağrıları: in.php ve res.php

Tüm akış üç adıma indirgenir:

1. Bakiyeyi kontrol ederek anahtarınızı doğrulayın.
2. Görevi in.php'ye gönderin ve görev kimliğini alın.
3. Token hazır olana kadar res.php'yi sorgulayın.

Bakiyenizi kontrol edin

res.php uç noktası getbalance eylemiyle hesabınızdaki bakiyeyi USD cinsinden döndürür — betiğe başlamadan anahtarınızın geçerli olduğunu doğrulamanın en hızlı yolu:

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

Çıktı: 1.234

reCAPTCHA v2 görevi gönderin

Görev göndermek için in.php uç noktasına sitenin googlekey (sitekey) ve pageurl değerlerini iletirsiniz. Yanıt, sonucu sorgulamak için kullanacağınız görev kimliğini içerir:

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

Çıktı: OK|73548291

Sonucu sorgulayın

Görev kimliğini res.php'ye action=get ile gönderip token hazır olana kadar periyodik olarak sorgularsınız. Çözüm tamamlanmadıysa API CAPCHA_NOT_READY döndürür; birkaç saniye bekleyip tekrar deneyin:

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

Çıktı: OK|03AGdBq24PBCbw... veya CAPCHA_NOT_READY

Yeniden kullanılabilir bir Bash çözüm betiği

Aynı curl komutlarını her seferinde elle yazmak yerine, gönderme ve sorgulama döngüsünü tek bir fonksiyonda toplayın. Aşağıdaki solve_captcha.sh betiği görevi gönderir, CAPCHA_NOT_READY yanıtı geldikçe beş saniyede bir tekrar sorgular ve zaman aşımına ulaşmadan token'ı stdout'a yazar — böylece başka betiklerden çağırabilirsiniz.

solve_captcha.sh'yi oluşturun:

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

Betiği çalıştırılabilir hale getirin:

chmod +x solve_captcha.sh

Anahtarınızı dışa aktarıp çağırın:

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

İpucu: Betik durum mesajlarını stderr'e, yalnızca token'ı stdout'a yazar. Bu ayrım, çözülen token'ı temiz biçimde bir değişkene almanızı sağlar — bir sonraki bölümde bunu kullanacağız.

Cloudflare Turnstile'ı çözün

reCAPTCHA akışına göre yalnızca iki nokta değişir:

• method=userrecaptcha yerine method=turnstile kullanın.
• Site anahtarını googlekey yerine sitekey parametresiyle geçin.

Görevi gönderdikten sonra sonucu sorgulama adımı reCAPTCHA ile birebir aynıdır:

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

Resim (OCR) CAPTCHA'sını çözün

Klasik resim tabanlı CAPTCHA'lar için görüntüyü base64'e kodlayıp method=base64 ile gönderin:

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

Base64 dizesinin çok uzadığı büyük görüntülerde URL uzunluğu sınırına takılmamak için dosyayı POST ile çok parçalı (multipart) gönderin:

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

Token'ı çözüp tek adımda forma gönderin

Gerçek bir iş akışında token'ı çözmek yalnızca ilk adımdır; asıl amaç onu bir isteğe eklemektir. Aşağıdaki betik solve_captcha.sh'yi çağırıp dönen token'ı bir QA giriş formuna g-recaptcha-response alanı olarak gönderir. Hedef adresin bir üretim sitesi değil, kendi staging ortamınız olduğuna dikkat edin:

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

Toplu işlem: dosyadan çoklu CAPTCHA çözme

Bir regresyon testi paketinde onlarca sayfayı sırayla doğrulamanız gerekebilir. Aşağıdaki döngü, her satırında bir URL bulunan bir dosyayı okur, her biri için token çözer ve sonuçları bir CSV'ye yazar:

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

Bu betik görevleri sırayla işler. Daha yüksek hacimde paralel çözüm için planınızdaki thread sayısı belirleyicidir: CaptchaAI thread tabanlı faturalandırır ve her thread için sınırsız çözüm sunar, dolayısıyla aynı anda kaç görevin havada olduğunu thread kapasiteniz belirler.

PowerShell ile Windows'ta çözme

Bash yerine Windows üzerinde çalışıyorsanız aynı akışı Invoke-RestMethod ile kurabilirsiniz. Gönderme ve sorgulama mantığı birebir aynıdır:

$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"
}

Sorun giderme

Terminalden çalışırken en sık karşılaşılan hatalar ve çözümleri:

Not: KVKK kapsamında, kazınan ya da otomasyonla işlenen kişisel veriler yasal yükümlülük doğurur. cURL entegrasyonunuzu yalnızca yetkili olduğunuz QA ve veri toplama akışlarında kullanın.

Sık sorulan sorular

cURL ile hangi CAPTCHA türlerini çözebilirim?

method parametresini değiştirerek reCAPTCHA v2/v3 (Enterprise dahil), Cloudflare Turnstile ve Challenge, GeeTest v3, resim/OCR, grid ve BLS türlerini çözebilirsiniz. hCaptcha ve FunCaptcha desteklenmiyor; GeeTest v4 desteği çok yakında geliyor. CaptchaFox, Friendly Captcha ve Lemin ise beta aşamasındadır.

API anahtarımı CI/CD ortamında nasıl güvende tutarım?

Anahtarı asla depoya ya da betiğe düz metin olarak yazmayın. CAPTCHAAI_API_KEY'yi GitHub Actions, GitLab CI veya Jenkins'te şifreli bir ortam değişkeni (secret) olarak tanımlayın ve betiği bu değişkenle çağırın.

cURL çözümü için hangi plan yeterli?

Planlar thread tabanlıdır ve her thread için sınırsız çözüm içerir. Tek betikle sıralı çözümler için BASIC ($15/ay, 5 thread) çoğu durumda yeterlidir; paralel toplu işlemde daha fazla thread'e ihtiyacınız olur.

Yanıtı jq ile nasıl ayrıştırırım?

İsteğe json=1 parametresini ekleyip yanıtı JSON formatında alın, ardından curl -s "..." | jq -r '.request' ile token'ı çıkarın. jq, kabuk betiklerinde OK|... dizesini elle bölmekten daha güvenilirdir.

cURL, Python veya Node.js SDK'sından daha mı yavaş?

Hayır. HTTP ek yükü aynıdır; toplam süreyi CAPTCHA'nın çözüm süresi belirler, taşıma katmanı değil. cURL, HTTP istemcilerine kıyasla ölçülebilir bir gecikme eklemez.

İlgili kılavuzlar

• Tarayıcısız Axios + CaptchaAI entegrasyonu
• API anahtarı kurulumu ve kimlik doğrulama
• API yanıt formatları başvurusu