Official Anti-Captcha.com Ruby gem
Official anti-captcha.com Ruby gem for solving images with text, Recaptcha v2/v3 Enterprise/non-Enterprise, Funcaptcha, GeeTest, HCaptcha Enterprise/non-Enterprise, Turnstile, Amazon WAF, Prosopo, Friendly Captcha and Altcha.
Anti-captcha is an oldest and cheapest web service dedicated to solving captchas by human workers from around the world. By solving captchas with us you help people in poorest regions of the world to earn money, which not only cover their basic needs, but also gives them ability to financially help their families, study and avoid jobs where they're simply not happy.
To use the service you need to register and topup your balance. Prices start from $0.0005 per image captcha and $0.002 for Recaptcha. That's $0.5 per 1000 for images and $2 for 1000 Recaptchas.
For more technical information and articles visit our documentation page.
Install the gem:
gem install anticaptchaofficialor add it to your Gemfile:
gem "anticaptchaofficial"The gem is called anticaptchaofficial, what you require is anticaptcha:
require "anticaptcha"Requires Ruby 3.0 or newer and has no runtime dependencies — everything comes from the standard library.
Examples how to solve:
- Image Captcha
- Recaptcha V2
- Recaptcha V2 Enterprise
- Recaptcha V3
- hCaptcha
- FunCaptcha
- GeeTest
- Turnstile
- Image to coordinates
- AntiGate (custom tasks)
- AntiBot cookies
- Prosopo
- Friendly Captcha
- Amazon WAF
- Altcha
Solve image captcha
require "anticaptcha"
# Create the API client and set the API key
ac = Anticaptcha.new("API_KEY_HERE")
# Specify a soft id to earn 10% commission with your app.
# Get yours at https://anti-captcha.com/clients/tools/devcenter
ac.soft_id = 0
# Set to false to turn the debug output off
ac.verbose = true
# Make sure the API key funds balance is positive
balance = ac.balance
if balance <= 0
# Stop here to make sure you don't DDoS the API while having empty balance
abort "Empty balance"
end
puts "Balance: #{balance}"
solution = ac.solve_image_file(
"captcha.jpg",
# Optional settings, see https://anti-captcha.com/apidoc/task-types/ImageToTextTask
# phrase: true, # the image has 2 or more words
# case_sensitive: true, # the answer is case sensitive
# numeric: 1, # 1 - digits only, 2 - no digits
# math_operation: true, # the answer is the result of 50+5
# min_length: 1,
# max_length: 10,
language_pool: "en", # "en" or "rn"
comment: "Type in green characters"
)
# OR ac.solve_image(body: "image-encoded-in-base64", ...)
puts "Captcha Solution: #{solution.text}"
# If the answer turns out to be wrong:
# ac.report_incorrect_image_captcha(solution.task_id)
Solve Recaptcha V2
solution = ac.solve_recaptcha_v2(
website_url: "https://www.website.com/",
website_key: "6Lcyu8UZAAAAACwSh6Xf58WrNXTu0LLu4F85xf20",
is_invisible: false, # set to true if you are solving an invisible Recaptcha V2
data_s_value: nil # fill this for a Recaptcha V2 with the "data-s" parameter,
# typically found at google.com websites
)
puts "Recaptcha g-response token: #{solution.g_recaptcha_response}"
# In case you need the worker's user-agent
puts "User-Agent: #{solution.user_agent}"Also with proxy:
solution = ac.solve_recaptcha_v2_proxy_on(
website_url: "https://www.website.com/",
website_key: "6Lcyu8UZAAAAACwSh6Xf58WrNXTu0LLu4F85xf20",
user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " \
"(KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
proxy: {
type: "http", # "http", "socks4" or "socks5", defaults to "http"
address: "1.2.3.4",
port: 1234,
login: "login-optional",
password: "pass-optional"
}
)
Solve Recaptcha V2 Enterprise
The same method, is_enterprise switches the task type:
solution = ac.solve_recaptcha_v2(
website_url: "https://store.steampowered.com/join",
website_key: "6LdIFr0ZAAAAAO3vz0O0OQrtAefzdJcWQM2TMYQH",
is_enterprise: true,
# Additional parameters passed to the grecaptcha.enterprise.render call
enterprise_payload: { "s" => "SOME_ADDITIONAL_TOKEN" }
# api_domain: "recaptcha.net" # only for a non-google.com script domain
)
puts solution.g_recaptcha_responseUse solve_recaptcha_v2_proxy_on for the proxy-on version.
Solve Recaptcha V3
solution = ac.solve_recaptcha_v3(
website_url: "https://www.website.com/",
website_key: "6LcvNcwdAAAAAMWAuNRXH74u3QePsEzTm6GEjx0J",
page_action: "somefun",
min_score: 0.9 # one of 0.3, 0.7, 0.9
# is_enterprise: true # set to true for a Recaptcha V3 Enterprise
)
puts "Recaptcha g-response token: #{solution.g_recaptcha_response}"Recaptcha V3 has no proxy-on version.
Solve Hcaptcha
solution = ac.solve_hcaptcha(
website_url: "https://www.website.com/",
website_key: "00000000-1111-2222-3333-444444444444"
# is_invisible: true,
# is_enterprise: true,
# hCaptcha Enterprise parameters like rqdata, sentry, apiEndpoint, endpoint,
# reportapi, assethost, imghost:
# enterprise_payload: { "rqdata" => "rqdata value from the target website" }
)
puts "Hcaptcha Token: #{solution.g_recaptcha_response}"
# Use this user-agent for the form submission
puts "User-Agent: #{solution.user_agent}"
# Optional "respkey" value, you may need it too
puts "respkey: #{solution.resp_key}"Also with proxy — solve_hcaptcha_proxy_on with a proxy: hash.
Solve FunCaptcha
solution = ac.solve_funcaptcha(
website_url: "https://www.website.com/",
website_public_key: "00000000-1111-2222-3333-444444444444",
# Make sure to find and set this correctly, look for a URL like
# https://somewebsite-api.arkoselabs.com/v2/00000000-1111-2222-3333-444444444444/api.js
api_subdomain: "somewebsite-api.arkoselabs.com",
data_blob: '{"blob":"HERE_COMES_THE_blob_VALUE"}'
)
puts "Funcaptcha Token: #{solution.token}"Also with proxy — solve_funcaptcha_proxy_on.
Solve Turnstile
solution = ac.solve_turnstile(
website_url: "https://www.website.com/",
website_key: "0x4AAAAAAABD2Inoxs-yJ8bz"
# action: "optional page action",
# c_data: "cdata token for cloudflare",
# chl_page_data: "chlPageData token for cloudflare"
)
puts "Turnstile Token: #{solution.token}"
# In case you need the worker's user-agent
puts "User-Agent: #{solution.user_agent}"Also with proxy — solve_turnstile_proxy_on.
Solve GeeTest
GeeTest has 2 versions, number 3 and 4. Number 3 requires the parameter challenge. Number 4 has the optional setting init_parameters.
solution = ac.solve_geetest(
website_url: "https://bitget.com/",
gt: "e9ca9c9ca19ad540a8017f5c107b2d0f",
# Solve GeeTest 4:
version: 4,
init_parameters: { "riskType" => "slide" }
# Solve GeeTest 3:
# version: 3,
# challenge: "1234567890abcdef1234567890abcdef"
)
# GeeTest v4
puts "captcha_id: #{solution.captcha_id}"
puts "lot_number: #{solution.lot_number}"
puts "pass_token: #{solution.pass_token}"
puts "gen_time: #{solution.gen_time}"
puts "captcha_output: #{solution.captcha_output}"
# GeeTest v3
# puts "#{solution.challenge} #{solution.seccode} #{solution.validate}"Also with proxy — solve_geetest_proxy_on.
Image to coordinates
solution = ac.solve_image_to_coordinates_file(
"coordinates.jpg",
mode: "points", # "points" or "rectangles"
comment: "Select objects in the specified order"
)
# OR ac.solve_image_to_coordinates(body: "image-encoded-in-base64", ...)
puts "Objects X,Y coordinates: #{solution.coordinates.inspect}"
Solve AntiGate (custom tasks)
solution = ac.solve_antigate(
website_url: "http://antigate.com/logintest.php",
template_name: "Sign-in and wait for control text",
variables: {
"login_input_css" => "#login",
"login_input_value" => "the login",
"password_input_css" => "#password",
"password_input_value" => "the password",
"control_text" => "You have been logged successfully"
},
# The proxy is optional for AntiGate tasks
proxy: { address: "1.2.3.4", port: 1234, login: "login-optional", password: "pass-optional" }
# domains_of_interest: ["some-other-domain.com"]
)
puts "cookies: #{solution.cookies.inspect}"
puts "localStorage: #{solution.local_storage.inspect}"
puts "fingerprint: #{solution.fingerprint.inspect}"
puts "url: #{solution.url}"
Get AntiBot cookies
Makes a worker open the page through your proxy and hands you back the anti-bot cookies, so you can reuse them in your own requests. The proxy is required — the cookies are only valid for the IP address they were issued to.
solution = ac.solve_antibot_cookie(
website_url: "https://www.somewebsite.com/",
proxy: { address: "1.2.3.4", port: 3128, login: "login", password: "password" }
)
# Ready to be sent as a Cookie header
puts "Cookie: #{solution.cookie_header}"
puts "User-Agent: #{solution.fingerprint_user_agent}"
Solve Prosopo
solution = ac.solve_prosopo(
website_url: "https://www.website.com/",
website_key: "sitekey-here"
)
puts "Prosopo Token: #{solution.token}"Also with proxy — solve_prosopo_proxy_on.
Solve Friendly Captcha
solution = ac.solve_friendly_captcha(
website_url: "https://www.website.com/",
website_key: "sitekey-here"
)
puts "Friendly Captcha Token: #{solution.token}"Also with proxy — solve_friendly_captcha_proxy_on.
Solve Amazon WAF
Two options here:
- When the captcha is at the bot filtering page and you need the
aws-waf-tokencookie:
solution = ac.solve_amazon(
website_url: "https://www.website.com/",
website_key: "key_value_from_window.gokuProps_object",
iv: "iv_value_from_window.gokuProps_object",
context: "context_value_from_window.gokuProps_object"
# captcha_script: "optional_captcha.js_script_url",
# challenge_script: "optional_challenge.js_script_url"
)
puts "aws-waf-token: #{solution.token}"- When the captcha is a standalone widget triggered by a user's action:
solution = ac.solve_amazon(
website_url: "https://www.website.com/",
# Captcha widget's API key from the AwsWafCaptcha.renderCaptcha function
website_key: "captcha_key_value",
waf_type: "widget",
# Full URL to jsapi.js
jsapi_script: "https://164cb210e333.edge.captcha-sdk.awswaf.com/164cb210e333/jsapi.js"
)Both options have a proxy-on version — solve_amazon_proxy_on.
Solve Altcha
solution = ac.solve_altcha(
website_url: "https://www.website.com/",
# Option 1: use the challenge URL (use one of the options!)
challenge_url: "/some/path/to/challenge/url"
# Option 2: use the challenge JSON
# challenge_json: '{"algorithm":"SHA-256","challenge":"1a40f7ba3393f9513016879de41c7221f14e563856de2f647233a00accf9c28b","salt":"0887f273d79df143355b9e5f","signature":"1de2bbf282420aef6ca0a84c38c85e2b1e40023d28bef72278d735555a8f47fb"}'
)
puts "Altcha Token: #{solution.token}"Also with proxy — solve_altcha_proxy_on.
Error handling
Every method raises on failure. All errors descend from Anticaptcha::Error, which descends from StandardError:
| Class | When |
|---|---|
Anticaptcha::InvalidTaskError |
a required parameter is missing or out of range, nothing was sent |
Anticaptcha::NetworkError |
the API could not be reached |
Anticaptcha::BadResponseError |
the API answered with something unexpected, see #raw
|
Anticaptcha::ApiError |
the API answered with a non-zero errorId, see #error_code
|
Anticaptcha::TimeoutError |
the task was still unsolved when the waiting limit ran out |
begin
solution = ac.solve_recaptcha_v2(website_url: url, website_key: key)
puts solution.g_recaptcha_response
rescue Anticaptcha::ApiError => e
# https://anti-captcha.com/apidoc/errors
retry if e.retryable?
warn "#{e.error_code}: #{e.description}"
rescue Anticaptcha::Error => e
warn e.message
endReading the solution
Solution wraps the API's solution object. Readers for fields a task type does not fill return nil:
solution.text # image captchas
solution.token # FunCaptcha, Turnstile, Prosopo, Friendly Captcha, Altcha, Amazon
solution.g_recaptcha_response # Recaptcha, hCaptcha
solution.user_agent # worker's user-agent
solution.cookies # AntiGate, AntiBotCookie
solution.cookie_header # the same cookies as a ready "name=value; ..." string
solution.coordinates # ImageToCoordinates
solution.task_id # for the report_* methods
solution.cost # what the task cost, in US dollars
solution.raw # the whole hash, for anything not listed above
solution["someNewField"] # any field by its API nameOther settings
ac = Anticaptcha.new("API_KEY_HERE", soft_id: 1187, verbose: false)
ac.connection_timeout = 30 # seconds per HTTP call to the API
ac.first_attempt_waiting_interval = 5 # seconds before the first status request
ac.normal_waiting_interval = 5 # seconds between the following ones
ac.max_waiting_time = 300 # seconds before giving up on the task
ac.last_task_info # full getTaskResult response of the last taskA task type this gem does not wrap yet can still be sent by hand:
solution = ac.solve_task(
"type" => "SomeNewTaskProxyless",
"websiteURL" => "https://www.website.com/"
)Running the examples and tests
git clone https://github.com/anti-captcha/anticaptcha-ruby.git
cd anticaptcha-ruby
# unit tests, they need no API key and no network
rake test
# put your API key into examples/solve.rb first
ruby examples/solve.rb imageRun the example without an argument to see the full list.