Skip to content

Commit 387e573

Browse files
bshahinbshahin
committed
Add image CAPTCHA solving examples in Python, Ruby, and Rust
- Implemented Python solution for image CAPTCHA solving using CaptchaAI API. - Added Ruby solution for image CAPTCHA solving using CaptchaAI API. - Created Rust solution for image CAPTCHA solving using CaptchaAI API. - Introduced a script to generate a complete example pack for various CAPTCHA solvers. - Added requirements for Python dependencies in requirements.txt. - Updated documentation for usage instructions across all languages.
1 parent 9d3e1f8 commit 387e573

242 files changed

Lines changed: 27433 additions & 2 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,18 @@ CaptchaAI-Examples/
5252
| Example | CAPTCHA Type | Languages | Article |
5353
|---------|-------------|-----------|---------|
5454
| [captchaai-quickstart](articles/captchaai-quickstart/) | Cloudflare Turnstile | Python, Node.js, PHP, Go, Java, C#, Ruby, Rust, Kotlin, Bash | [Blog](https://blog.captchaai.com/captchaai-quickstart) |
55-
56-
_More examples are added as articles are published. Check back regularly._
55+
| [how-to-solve-recaptcha-v2-using-api](articles/how-to-solve-recaptcha-v2-using-api/) | reCAPTCHA v2 | Python, Node.js, PHP, Go, Java, C#, Ruby, Rust, Kotlin, Bash | [Blog](https://blog.captchaai.com/how-to-solve-recaptcha-v2-using-api) |
56+
| [how-to-solve-recaptcha-v3-automatically-using-api](articles/how-to-solve-recaptcha-v3-automatically-using-api/) | reCAPTCHA v3 | Python, Node.js, PHP, Go, Java, C#, Ruby, Rust, Kotlin, Bash | [Blog](https://blog.captchaai.com/how-to-solve-recaptcha-v3-automatically-using-api) |
57+
| [how-to-solve-recaptcha-v2-enterprise-using-api](articles/how-to-solve-recaptcha-v2-enterprise-using-api/) | reCAPTCHA v2 Enterprise | Python, Node.js, PHP, Go, Java, C#, Ruby, Rust, Kotlin, Bash | [Blog](https://blog.captchaai.com/how-to-solve-recaptcha-v2-enterprise-using-api) |
58+
| [how-to-solve-recaptcha-v3-enterprise-using-api](articles/how-to-solve-recaptcha-v3-enterprise-using-api/) | reCAPTCHA v3 Enterprise | Python, Node.js, PHP, Go, Java, C#, Ruby, Rust, Kotlin, Bash | [Blog](https://blog.captchaai.com/how-to-solve-recaptcha-v3-enterprise-using-api) |
59+
| [how-to-solve-recaptcha-invisible-using-api](articles/how-to-solve-recaptcha-invisible-using-api/) | reCAPTCHA Invisible | Python, Node.js, PHP, Go, Java, C#, Ruby, Rust, Kotlin, Bash | [Blog](https://blog.captchaai.com/how-to-solve-recaptcha-invisible-using-api) |
60+
| [how-to-solve-recaptcha-v2-callback-using-api](articles/how-to-solve-recaptcha-v2-callback-using-api/) | reCAPTCHA v2 (Callback) | Python, Node.js, PHP, Go, Java, C#, Ruby, Rust, Kotlin, Bash | [Blog](https://blog.captchaai.com/how-to-solve-recaptcha-v2-callback-using-api) |
61+
| [how-to-solve-cloudflare-turnstile-using-api](articles/how-to-solve-cloudflare-turnstile-using-api/) | Cloudflare Turnstile | Python, Node.js, PHP, Go, Java, C#, Ruby, Rust, Kotlin, Bash | [Blog](https://blog.captchaai.com/how-to-solve-cloudflare-turnstile-using-api) |
62+
| [how-to-solve-cloudflare-challenge-using-api](articles/how-to-solve-cloudflare-challenge-using-api/) | Cloudflare Challenge | Python, Node.js, PHP, Go, Java, C#, Ruby, Rust, Kotlin, Bash | [Blog](https://blog.captchaai.com/how-to-solve-cloudflare-challenge-using-api) |
63+
| [how-to-solve-geetest-v3-using-api](articles/how-to-solve-geetest-v3-using-api/) | GeeTest v3 | Python, Node.js, PHP, Go, Java, C#, Ruby, Rust, Kotlin, Bash | [Blog](https://blog.captchaai.com/how-to-solve-geetest-v3-using-api) |
64+
| [how-to-solve-bls-captcha-step-by-step](articles/how-to-solve-bls-captcha-step-by-step/) | BLS CAPTCHA | Python, Node.js, PHP, Go, Java, C#, Ruby, Rust, Kotlin, Bash | [Blog](https://blog.captchaai.com/how-to-solve-bls-captcha-step-by-step) |
65+
| [image-captcha-solving-using-api](articles/image-captcha-solving-using-api/) | Image/OCR CAPTCHA | Python, Node.js, PHP, Go, Java, C#, Ruby, Rust, Kotlin, Bash | [Blog](https://blog.captchaai.com/image-captcha-solving-using-api) |
66+
| [how-to-solve-grid-image-captcha-automatically](articles/how-to-solve-grid-image-captcha-automatically/) | Grid Image CAPTCHA | Python, Node.js, PHP, Go, Java, C#, Ruby, Rust, Kotlin, Bash | [Blog](https://blog.captchaai.com/how-to-solve-grid-image-captcha-automatically) |
5767

5868
## How each example works
5969

‎articles/how-to-solve-bls-captcha-step-by-step/.env.example‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# CaptchaAI API credentials
2+
# Get your API key from https://captchaai.com/dashboard (32 characters)
3+
CAPTCHAAI_API_KEY=YOUR_API_KEY
4+
5+
# BLS CAPTCHA configuration
6+
# Path to the CAPTCHA image file (PNG, JPG, etc.)
7+
CAPTCHA_IMAGE_FILE=captcha.png
8+
# Text instructions describing what to select (e.g. "Select all images with a car")
9+
CAPTCHA_INSTRUCTIONS=Select all images with a car
10+
11+
# Polling configuration (optional)
12+
POLL_INTERVAL=5
13+
MAX_TIMEOUT=120

‎articles/how-to-solve-bls-captcha-step-by-step/.gitignore‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
.env
2+
__pycache__/
3+
*.pyc
4+
node_modules/
5+
vendor/
6+
composer.lock
7+
package-lock.json
8+
.DS_Store
9+
Thumbs.db
10+
# Go
11+
go.sum
12+
# Java
13+
*.class
14+
# C#
15+
bin/
16+
obj/
17+
# Ruby
18+
Gemfile.lock
19+
# Rust
20+
target/
21+
Cargo.lock
22+
# Kotlin
23+
*.jar
24+
# Bash
25+
*.log

‎articles/how-to-solve-bls-captcha-step-by-step/README.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# BLS CAPTCHA — CaptchaAI Example Pack
2+
3+
Full working example for solving BLS CAPTCHA using the CaptchaAI API.
4+
5+
**Languages:** Python, Node.js, PHP, Go, Java, C#, Ruby, Rust, Kotlin, Bash
6+
7+
## Related article
8+
9+
This example accompanies the blog article:
10+
**[How to Solve BLS CAPTCHA Step by Step](https://blog.captchaai.com/how-to-solve-bls-captcha-step-by-step)**
11+
12+
## Prerequisites
13+
14+
- A CaptchaAI account with API key ([get one here](https://captchaai.com))
15+
- A CAPTCHA image file for testing (PNG, JPG, etc.)
16+
- One or more of: Python 3.8+, Node.js 16+, PHP 8.0+, Go 1.21+, Java 11+, .NET 8+, Ruby 3.0+, Rust 1.70+, Kotlin 1.9+, or Bash with curl and jq
17+
18+
## BLS CAPTCHA parameters
19+
20+
| Parameter | Required | Description |
21+
|-----------|----------|-------------|
22+
| `method` | Yes | Must be `bls` |
23+
| `body` | Yes | Base64-encoded CAPTCHA image data |
24+
| `textinstructions` | Yes | Text instructions describing what to select (e.g. "Select all images with a car") |
25+
26+
## Response
27+
28+
The API returns the selected cell indices in the `request` field (e.g. `"1,3,5"`).
29+
30+
## Setup
31+
32+
1. Clone the repository:
33+
```bash
34+
git clone https://github.com/CaptchaAI/CaptchaAI-Examples.git
35+
cd CaptchaAI-Examples/articles/how-to-solve-bls-captcha-step-by-step
36+
```
37+
38+
2. Copy the environment file and add your credentials:
39+
```bash
40+
cp .env.example .env
41+
```
42+
43+
3. Edit `.env` with your API key, image file path, and instructions.
44+
45+
4. Follow the language-specific setup below.
46+
47+
### Python
48+
49+
```bash
50+
cd python
51+
pip install -r requirements.txt
52+
python solve.py
53+
```
54+
55+
### Node.js
56+
57+
```bash
58+
cd node
59+
npm install
60+
node solve.js
61+
```
62+
63+
### PHP
64+
65+
```bash
66+
cd php
67+
composer install
68+
php solve.php
69+
```
70+
71+
### Go
72+
73+
```bash
74+
cd go
75+
go run solve.go
76+
```
77+
78+
### Java
79+
80+
```bash
81+
cd java
82+
javac Solve.java
83+
java Solve
84+
```
85+
86+
### C#
87+
88+
```bash
89+
cd csharp
90+
dotnet run
91+
```
92+
93+
### Ruby
94+
95+
```bash
96+
cd ruby
97+
ruby solve.rb
98+
```
99+
100+
### Rust
101+
102+
```bash
103+
cd rust
104+
cargo run
105+
```
106+
107+
### Kotlin
108+
109+
```bash
110+
cd kotlin
111+
kotlinc solve.kt -include-runtime -d solve.jar
112+
java -jar solve.jar
113+
```
114+
115+
### Bash
116+
117+
```bash
118+
cd bash
119+
chmod +x solve.sh
120+
bash solve.sh
121+
```
122+
123+
## How it works
124+
125+
1. The script loads the CAPTCHA image from the file specified in `CAPTCHA_IMAGE_FILE`.
126+
2. The image is base64-encoded and sent via **POST** to `in.php` with `method=bls` and `textinstructions`.
127+
3. The API returns a task ID.
128+
4. The script polls `res.php` until the solution is ready.
129+
5. The answer contains the selected cell indices (e.g. `"1,3,5"`).
130+
131+
## Notes
132+
133+
- The image file must exist and be readable.
134+
- Submission uses POST (not GET) because the base64-encoded image body is too large for a URL.
135+
- The `textinstructions` parameter tells the solver what to look for in the image grid.

‎articles/how-to-solve-bls-captcha-step-by-step/bash/solve.sh‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
#!/usr/bin/env bash
2+
# Solve BLS CAPTCHA using the CaptchaAI API.
3+
#
4+
# Usage:
5+
# chmod +x solve.sh
6+
# bash solve.sh
7+
8+
set -euo pipefail
9+
10+
SUBMIT_URL="https://ocr.captchaai.com/in.php"
11+
RESULT_URL="https://ocr.captchaai.com/res.php"
12+
13+
# Load .env
14+
ENV_FILE="$(dirname "$0")/../.env"
15+
if [[ -f "$ENV_FILE" ]]; then
16+
set -a
17+
# shellcheck disable=SC1090
18+
source "$ENV_FILE"
19+
set +a
20+
fi
21+
22+
API_KEY="${CAPTCHAAI_API_KEY:-}"
23+
IMAGE_FILE="${CAPTCHA_IMAGE_FILE:-}"
24+
INSTRUCTIONS="${CAPTCHA_INSTRUCTIONS:-}"
25+
POLL_INTERVAL="${POLL_INTERVAL:-5}"
26+
MAX_TIMEOUT="${MAX_TIMEOUT:-120}"
27+
28+
# Validate
29+
if [[ -z "$API_KEY" || "$API_KEY" == "YOUR_API_KEY" ]]; then
30+
echo "[!] ERROR: CAPTCHAAI_API_KEY is not set."
31+
echo " Copy .env.example to .env and add your real API key."
32+
exit 1
33+
fi
34+
if [[ -z "$IMAGE_FILE" ]]; then
35+
echo "[!] ERROR: CAPTCHA_IMAGE_FILE is not set."
36+
echo " Set the path to the CAPTCHA image file in .env."
37+
exit 1
38+
fi
39+
40+
# Resolve image path
41+
IMAGE_PATH="$(dirname "$0")/../$IMAGE_FILE"
42+
if [[ ! -f "$IMAGE_PATH" ]]; then
43+
IMAGE_PATH="$IMAGE_FILE"
44+
fi
45+
if [[ ! -f "$IMAGE_PATH" ]]; then
46+
echo "[!] ERROR: Image file not found: $IMAGE_FILE"
47+
echo " Make sure the file exists and the path is correct."
48+
exit 1
49+
fi
50+
51+
if [[ -z "$INSTRUCTIONS" ]]; then
52+
echo "[!] ERROR: CAPTCHA_INSTRUCTIONS is not set."
53+
echo " Provide text instructions (e.g. 'Select all images with a car')."
54+
exit 1
55+
fi
56+
57+
# JSON helpers
58+
json_str() {
59+
local json="$1" key="$2"
60+
echo "$json" | grep -oP "\"${key}\":\s*\"\\K[^\"]*" || echo ""
61+
}
62+
json_int() {
63+
local json="$1" key="$2"
64+
echo "$json" | grep -oP "\"${key}\":\s*\\K[0-9]+" || echo "0"
65+
}
66+
67+
# Error handler
68+
handle_error() {
69+
local error="$1"
70+
case "$error" in
71+
ERROR_WRONG_USER_KEY|ERROR_KEY_DOES_NOT_EXIST|IP_BANNED)
72+
echo "[!] Authentication error: $error"
73+
echo " Check your API key at https://captchaai.com/dashboard"
74+
;;
75+
ERROR_ZERO_BALANCE)
76+
echo "[!] Balance error: $error"
77+
echo " Top up your account at https://captchaai.com"
78+
;;
79+
ERROR_PAGEURL|ERROR_WRONG_GOOGLEKEY|ERROR_BAD_PARAMETERS|ERROR_BAD_TOKEN_OR_PAGEURL)
80+
echo "[!] Input error: $error"
81+
echo " Verify your image and instructions are correct."
82+
;;
83+
ERROR_BAD_PROXY|ERROR_PROXY_CONNECTION_FAILED)
84+
echo "[!] Proxy error: $error"
85+
echo " Check your proxy configuration or try a different proxy."
86+
;;
87+
*)
88+
echo "[!] Submission failed: $error"
89+
;;
90+
esac
91+
}
92+
93+
# Load image and base64-encode
94+
echo "[*] Loading image from $IMAGE_FILE..."
95+
IMAGE_B64=$(base64 -w 0 "$IMAGE_PATH" 2>/dev/null || base64 "$IMAGE_PATH" | tr -d '\n')
96+
97+
# Submit task via POST
98+
echo "[*] Submitting BLS CAPTCHA task..."
99+
SUBMIT_RESP=$(curl -sS --max-time 30 \
100+
-X POST \
101+
-d "key=${API_KEY}" \
102+
-d "method=bls" \
103+
-d "body=${IMAGE_B64}" \
104+
--data-urlencode "textinstructions=${INSTRUCTIONS}" \
105+
-d "json=1" \
106+
"$SUBMIT_URL")
107+
108+
if [[ -z "$SUBMIT_RESP" ]]; then
109+
echo "[!] Network error during submission."
110+
exit 1
111+
fi
112+
113+
SUBMIT_STATUS=$(json_int "$SUBMIT_RESP" "status")
114+
SUBMIT_REQUEST=$(json_str "$SUBMIT_RESP" "request")
115+
116+
if [[ "$SUBMIT_STATUS" -ne 1 ]]; then
117+
handle_error "$SUBMIT_REQUEST"
118+
exit 1
119+
fi
120+
121+
TASK_ID="$SUBMIT_REQUEST"
122+
echo "[+] Task submitted. ID: $TASK_ID"
123+
124+
# Poll for result
125+
echo "[*] Waiting 15s before first poll..."
126+
sleep 15
127+
128+
ELAPSED=15
129+
ATTEMPT=0
130+
BACKOFF="$POLL_INTERVAL"
131+
132+
ENCODED_KEY=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$API_KEY'))" 2>/dev/null || echo "$API_KEY")
133+
134+
while [[ "$ELAPSED" -lt "$MAX_TIMEOUT" ]]; do
135+
ATTEMPT=$((ATTEMPT + 1))
136+
echo "[*] Polling for result (attempt $ATTEMPT)..."
137+
138+
POLL_RESP=$(curl -sS --max-time 30 \
139+
"${RESULT_URL}?key=${ENCODED_KEY}&action=get&id=${TASK_ID}&json=1" 2>/dev/null || echo "")
140+
141+
if [[ -z "$POLL_RESP" ]]; then
142+
echo "[!] Network error during polling."
143+
sleep "$BACKOFF"
144+
ELAPSED=$((ELAPSED + BACKOFF))
145+
BACKOFF=$((BACKOFF * 2))
146+
[[ "$BACKOFF" -gt 30 ]] && BACKOFF=30
147+
continue
148+
fi
149+
150+
STATUS=$(json_int "$POLL_RESP" "status")
151+
152+
if [[ "$STATUS" -eq 1 ]]; then
153+
ANSWER=$(json_str "$POLL_RESP" "request")
154+
echo "[+] Solved! Answer: $ANSWER"
155+
echo
156+
echo "Next step: use these selected indices to click the"
157+
echo "corresponding images on the target page and submit."
158+
exit 0
159+
fi
160+
161+
REQUEST=$(json_str "$POLL_RESP" "request")
162+
163+
if [[ "$REQUEST" == "CAPCHA_NOT_READY" ]]; then
164+
echo "[*] Not ready yet, waiting ${POLL_INTERVAL}s..."
165+
sleep "$POLL_INTERVAL"
166+
ELAPSED=$((ELAPSED + POLL_INTERVAL))
167+
BACKOFF="$POLL_INTERVAL"
168+
continue
169+
fi
170+
171+
case "$REQUEST" in
172+
ERROR_SERVER_ERROR|ERROR_INTERNAL_SERVER_ERROR)
173+
echo "[!] Transient error: $REQUEST, retrying in ${BACKOFF}s..."
174+
sleep "$BACKOFF"
175+
ELAPSED=$((ELAPSED + BACKOFF))
176+
BACKOFF=$((BACKOFF * 2))
177+
[[ "$BACKOFF" -gt 30 ]] && BACKOFF=30
178+
continue
179+
;;
180+
ERROR_CAPTCHA_UNSOLVABLE)
181+
echo "[!] Solve error: $REQUEST"
182+
echo " The CAPTCHA could not be solved. Verify parameters and retry."
183+
exit 1
184+
;;
185+
esac
186+
187+
echo "[!] Unexpected error: $REQUEST"
188+
exit 1
189+
done
190+
191+
echo "[!] Timeout: no solution received within ${MAX_TIMEOUT} seconds."
192+
exit 1

0 commit comments

Comments
 (0)