Capsolver

Ruby client library for the Capsolver service API. This gem is a Ruby port of the popular python3-capsolver library, providing a clean, robust, and idiomatic interface to solve various CAPTCHAs.

Features

• Broad Captcha Support: ReCaptcha (V2/V3/Enterprise), Cloudflare (Turnstile/Challenge), DataDome Slider, GeeTest, MtCaptcha, AWS WAF, Yandex Captcha, Vision Engine, and standard Image-to-Text.
• Sync & Async Ready: Fully compatible with modern Ruby 3.x concurrency (Threads, Fibers, and Fiber Schedulers like the async gem).
• Parity with Python API: Includes aio_* method aliases and structure designed to feel familiar to developers migrating code from Python.
• Robust Connection Handling: Uses Faraday under the hood for clean, customizable HTTP request management.

---

Installation

Add this line to your application's Gemfile:

gem "capsolver"

And then execute:

bundle install

Or install it directly:

gem install capsolver

---

Usage

1. Control Client (Generic Operations)

The Capsolver::Control class allows checking your balance, submitting custom tasks, getting status, and providing feedback.

require "capsolver"

# Initialize control client
control = Capsolver::Control.new(api_key: "YOUR_CAPSOLVER_API_KEY")

# Check balance
balance_info = control.get_balance
puts "Balance: #{balance_info['balance']}"

# Create custom tasks and poll for results manually if needed
response = control.create_task({
  type: "AntiTurnstileTaskProxyLess",
  websiteURL: "https://example.com",
  websiteKey: "0x4AAAAAA..."
})
task_id = response["taskId"]

# Poll for result
result = control.get_task_result(task_id)
puts result

---

2. Solving Cloudflare Turnstile

Use the Capsolver::Cloudflare class for an automatic retry-and-polling resolver:

require "capsolver"

cloudflare = Capsolver::Cloudflare.new(api_key: "YOUR_API_KEY")

# Triggers createTask and automatically polls getTaskResult
result = cloudflare.captcha_handler({
  websiteURL: "https://example.com",
  websiteKey: "0x4AAAAAA..."
})

if result["status"] == "ready"
  token = result.dig("solution", "token")
  puts "Solved! Token: #{token}"
else
  puts "Failed to solve Turnstile: #{result['errorDescription']}"
end

---

3. Solving Image-to-Text Captchas

To solve classic image captchas, use Capsolver::ImageToText combined with the Capsolver::FileInstrument helper to handle base64 encoding:

require "capsolver"

# Read and encode local image file to base64
instrument = Capsolver::FileInstrument.new
base64_image = instrument.file_processing(captcha_file: "path/to/captcha.png")

image_solver = Capsolver::ImageToText.new(api_key: "YOUR_API_KEY")
result = image_solver.captcha_handler({
  body: base64_image,
  module: "common" # or specific capsolver module
})

if result["status"] == "ready"
  puts "Result: #{result.dig('solution', 'text')}"
end

---

4. Concurrency & Async Support

Since standard blocking I/O (like Faraday requests and sleep) in Ruby 3.x automatically becomes non-blocking when run within a Fiber Scheduler context, using this gem in async blocks is natively concurrent:

require "async"
require "capsolver"

Async do
  client = Capsolver::Cloudflare.new(api_key: "YOUR_API_KEY")
  
  # This poll-and-sleep loop runs concurrently without blocking other Fibers!
  task = Async { client.captcha_handler(websiteURL: "...", websiteKey: "...") }
  
  puts task.wait
end

For parity with Python codebases, the gem also exposes explicit aio_* method aliases (e.g. aio_captcha_handler, aio_get_balance, aio_create_task).

---

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bundle exec rake test to execute the Minitest test suite.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/eljarpo/capsolver.

License

The gem is available as open source under the terms of the MIT License.