humantone

Official Ruby SDK for the HumanTone API. Rewrites AI-generated text into natural-sounding prose. Adds an AI Likelihood Indicator that scores how AI-like any text reads.

Add to your Gemfile:

gem "humantone", "~> 0.0.1"

Then bundle install.

Or directly: gem install humantone.

Requires Ruby 3.3 or later. Zero runtime dependencies (uses stdlib net/http).

require "humantone"

client = HumanTone::Client.new(api_key: ENV.fetch("HUMANTONE_API_KEY"))

result = client.humanize(
  text: "Your AI-generated draft goes here. At least 30 words for the API to accept it."
)

puts result.text
puts "Credits used: #{result.credits_used}"

The client also picks up HUMANTONE_API_KEY from the environment automatically:

client = HumanTone::Client.new

Returns HumanTone::HumanizeResult Data with #text, #output_format, #credits_used, #request_id.

Returns DetectResult with #ai_score (0-100 integer). Free, but limited to 30 calls per day per account.

info = client.account.get
puts info.plan.name
puts info.credits.total
puts info.subscription.expires_at  # Time or nil

client = HumanTone::Client.new(
  api_key: "ht_...",                    # or HUMANTONE_API_KEY env
  base_url: "https://api.humantone.io", # or HUMANTONE_BASE_URL env, default
  timeout: 120,                          # seconds
  max_retries: 2,
  retry_on_post: false,                  # POST endpoints retry only when explicit
  user_agent: "my-app/1.0"               # appended to default UA after a single space
)

All errors inherit from HumanTone::Error.

begin
  result = client.humanize(text: "...")
rescue HumanTone::InsufficientCreditsError
  puts "Buy more credits at https://app.humantone.io/settings/credits"
rescue HumanTone::RateLimitError => e
  puts "Rate limited. Retry in #{e.retry_after_seconds}s."
rescue HumanTone::AuthenticationError
  puts "Check your API key."
rescue HumanTone::Error => e
  puts "HumanTone error (#{e.error_code}): #{e.message}"
  puts "Request ID: #{e.request_id}" if e.request_id
end

Error classes:

• AuthenticationError, PermissionError, RateLimitError
• InsufficientCreditsError, DailyLimitExceededError
• InvalidRequestError, NotFoundError
• APIError, TimeoutError, NetworkError

Common methods on every error:

• #message, #status_code, #request_id, #error_code, #details, #retryable?

Specific accessors: RateLimitError#retry_after_seconds: Integer, DailyLimitExceededError#time_to_next_renew: Integer | nil, InsufficientCreditsError#required_credits and #available_credits.

The SDK retries account.get on network errors, 5xx, and 429 (up to 2 retries). POST methods (humanize, detect) do not retry on network or 5xx by default. Humanize debits credits, so a retried request risks double-billing. Pass retry_on_post: true to opt in. 429 always retries on every method.

Retry-After headers are honored in both numeric (seconds) and HTTP-date formats.

• Per-request word limit. Basic 750, Standard 1000, Pro 1500. Inputs must be at least 30 words.
• Credits. Humanize consumes 1 credit per 100 words. Account checks and AI likelihood checks do not consume credits.
• AI likelihood quota. 30 checks per day per account, shared between the HumanTone web app and any API or SDK usage. Resets at midnight UTC.
• API access. Included on all paid plans. Free trial accounts cannot use the API.

Sign up at humantone.io. The HumanTone API is paid only.

MIT

• API docs: https://humantone.io/docs/api/
• RubyGems: https://rubygems.org/gems/humantone
• Issues: https://github.com/humantone/humantone-ruby/issues
• Support: help@humantone.io