Solve captchas from Ruby with one function

Step 1

Add the helper

Save this file next to your code. It wraps the whole task lifecycle in one call, Bypass.solve(type, params), so the rest of your project never deals with polling.

• createTask: sends your key, the task type and its fields as one flat JSON object.
• Fast path: if the answer is already ready, it returns at once.
• Polling: otherwise it checks /getTaskResult/{taskId} every two seconds until the result is ready or the timeout runs out.
• Errors: any reply with a non-zero errorId, including a failed task, becomes an error carrying the errorCode, so you can branch on it.
• taskId: kept with the solution, so you can report a wrong answer later.

require "json"
require "net/http"
require "uri"

module Bypass
  API_URL = "https://bypass.so"

  # Raised for every API reply with a non-zero errorId.
  class Error < StandardError
    attr_reader :code, :task_id

    def initialize(code, description = "", task_id = nil)
      super("#{code}: #{description}")
      @code = code
      @task_id = task_id
    end
  end

  NETWORK_ERRORS = [SocketError, Timeout::Error, SystemCallError, OpenSSL::SSL::SSLError, EOFError].freeze

  module_function

  def key
    ENV.fetch("BYPASS_API_KEY", "")
  end

  # Creates a task and polls every poll_every seconds until it is ready.
  # Returns the solution hash plus "taskId".
  def solve(type, params, timeout: 120, poll_every: 2)
    client_key = key
    raise Error.new("ERROR_KEY_INVALID", "set the BYPASS_API_KEY environment variable") if client_key.empty?

    data = call(:post, "/createTask", body: { clientKey: client_key, type: type }.merge(params))
    task_id = data["taskId"]
    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
    poll = "/getTaskResult/#{URI.encode_www_form_component(task_id)}?clientKey=#{URI.encode_www_form_component(client_key)}"

    until data["status"] == "ready"
      raise Error.new("ERROR_CAPTCHA_UNSOLVABLE", "task failed", task_id) if data["status"] == "failed"
      if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
        raise Error.new("CLIENT_TIMEOUT", "task #{task_id} was not ready after #{timeout}s", task_id)
      end

      sleep poll_every
      data = call(:get, poll)
    end
    (data["solution"] || {}).merge("taskId" => task_id)
  end

  # The token for widget types, or the text for recognition types.
  def answer(solution)
    solution["gRecaptchaResponse"] || solution["token"] || solution["text"]
  end

  def balance
    call(:get, "/balance", bearer: true)
  end

  def report_bad(task_id)
    call(:post, "/reportBad?task_id=#{URI.encode_www_form_component(task_id)}", bearer: true)
  end

  def call(method, path, body: nil, bearer: false)
    uri = URI(API_URL + path)
    req = method == :post ? Net::HTTP::Post.new(uri) : Net::HTTP::Get.new(uri)
    req["Content-Type"] = "application/json" if method == :post
    req.body = body ? JSON.generate(body) : "" if method == :post
    req["Authorization"] = "Bearer #{key}" if bearer

    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 30) do |http|
      http.request(req)
    end
    data = begin
      JSON.parse(res.body.to_s)
    rescue JSON::ParserError
      nil
    end
    raise Error.new("HTTP_ERROR", "HTTP #{res.code} without a JSON body") unless data.is_a?(Hash)
    if data["errorId"].to_i != 0
      raise Error.new(data["errorCode"] || "ERROR_UNKNOWN", data["errorDescription"].to_s, data["taskId"])
    end

    data
  rescue *NETWORK_ERRORS => e
    raise Error.new("HTTP_ERROR", e.message)
  end
end

Project layout used below:

bypass-demo/
  bypass.rb         the helper (step 1)
  solve_math.rb     your script (step 2)

Step 2

Solve any supported type

Every task type uses the same call. Only the type name and its fields change. Pick a tab to see a complete, runnable file, then run it with ruby solve_math.rb (rename to match the tab). Tabs marked soon are ready for launch day, but those types are not live yet.

require_relative "bypass"

solution = Bypass.solve("MathCaptchaTask", { captchaText: "12 + 30 = ?" })
puts solution["text"]

ruby solve_math.rb

Step 3

Handle errors and retries

Some failures are worth a second try and some are not. A missing balance or a wrong key will fail again, so stop and fix it. An unsolvable task, a timeout or a network hiccup is worth one or two more attempts with a short pause. Bypass::Error carries the API code in e.code, and network errors are wrapped as HTTP_ERROR. Ruby’s retry keyword reruns the block for the codes worth another try.

require_relative "bypass"

RETRYABLE = %w[ERROR_CAPTCHA_UNSOLVABLE ERROR_INTERNAL HTTP_ERROR CLIENT_TIMEOUT].freeze

def solve_with_retry(type, params, attempts: 3)
  attempt = 0
  begin
    attempt += 1
    Bypass.solve(type, params)
  rescue Bypass::Error => e
    raise if !RETRYABLE.include?(e.code) || attempt >= attempts

    warn "attempt #{attempt}: #{e.code}, retrying"
    sleep 2 * attempt
    retry
  end
end

puts solve_with_retry("MathCaptchaTask", { captchaText: "12 + 30 = ?" })["text"]

Step 4

Check your balance and flag wrong answers

GET /balance and POST /reportBad use your key as a Bearer token. Report a task only when the target site actually rejected its answer. The refund is applied once per task, and the task is closed afterwards.

require_relative "bypass"

def flag_wrong_answer(solution)
  result = Bypass.report_bad(solution["taskId"])
  puts "refunded units: #{result['refunded']} balance now: #{result['balanceUsd']}"
end

info = Bypass.balance
puts format("balance: $%.2f", info["balanceUsd"])

Scale

Solve many tasks in parallel

Each task is independent, so throughput grows with concurrency. Eight threads pull file names from a closed Queue. Each solve spends most of its time waiting on the network, so threads work well here despite the global interpreter lock. Start with a limit of 8 and adjust while you watch error rates and spend.

require_relative "bypass"

files = Dir.glob("captchas/*.png").sort
queue = Queue.new
files.each { |path| queue << path }
queue.close

workers = Array.new(8) do # at most 8 tasks in flight
  Thread.new do
    while (path = queue.pop)
      image_base64 = [File.binread(path)].pack("m0") # strict Base64
      begin
        text = Bypass.solve("ImageToTextTask", { imageBase64: image_base64 })["text"]
        puts "#{File.basename(path)}: #{text}"
      rescue Bypass::Error => e
        puts "#{File.basename(path)} failed: #{e.code}"
      end
    end
  end
end
workers.each(&:join)

Reference

Task type reference

What each type expects and returns. Prices are per 1,000 solved tasks; larger top-ups add bonus credit (see pricing).

Errors

Troubleshooting

Every error body has the same shape: {"errorId":1,"errorCode":"…","errorDescription":"…"}. Full list in the API reference.

Production

Best practices

• Keep the key out of code

  Read it from an environment variable or your secret store. Never commit it or ship it to a web page.

• Solve right before submit

  Tokens are short-lived. Fill the form first, then request the token and submit at once.

• Cap your concurrency

  Start with 5–10 parallel tasks and raise it while you watch error rates and spend.

• Log every taskId

  It is the only thing you need to debug a result or report a wrong answer.

• Match the page exactly

  Send the URL where the widget renders and the sitekey from that page, not from a different form.

• Report wrong answers

  If a site rejects a solved result, call reportBad with its taskId. The price returns to your balance once.

FAQ

Questions

Policy

Responsible use

Keep going

Next steps

• API referenceEvery endpoint, field and error code
• PricingPer-task prices and top-up bonuses
• PyPython guideScripts, backends and data jobs
• JSNode.js guideServices, CLIs and serverless functions
• GoGo guideServices and workers on the standard library
• PHPPHP guideWeb apps, cron jobs and CLI scripts
• JvJava guideJVM backends on Java 17+, no libraries
• C#C# / .NET guideAsync .NET 8 services and tools
• SeSelenium guideQA suites and WebDriver flows
• PwPlaywright guideEnd-to-end tests in Node.js or Python
• PpPuppeteer guideChrome automation scripts
• ScScrapy guideCrawls that run into captcha pages