Ruby SDK

Official Ruby SDK for TruthMark invisible watermarking.

Installation

Gem
gem install truthmark-sdk
Gemfile
gem 'truthmark-sdk'

Quick Example

require 'truthmark'

client = TruthMark::Client.new(
  api_key: 'tm_live_your_key',
  base_url: 'https://truthmark-api.onrender.com'
)

# Encode
result = client.encode('image.png', 'Copyright 2025')
puts "Download: #{result[:download_url]}"
puts "PSNR: #{result[:metadata][:psnr].round(1)} dB"

# Decode
decoded = client.decode('watermarked.png')
if decoded[:found]
  puts "Message: #{decoded[:message]}"
  puts "Confidence: #{(decoded[:confidence] * 100).round(1)}%"
end

API Reference

TruthMark::Client.new(options)

Create a new client with configuration.

  • api_key: (String) Your API key
  • base_url: (String) API base URL
  • timeout: (Integer) Request timeout in seconds

encode(image_path, message)

Embed an invisible watermark. Returns a Hash.

decode(image_path)

Extract watermark. Returns a Hash.

Error Handling

begin
  result = client.encode('image.png', 'message')
rescue TruthMark::RateLimitError => e
  puts "Rate limited. Retry after: #{e.retry_after}s"
rescue TruthMark::AuthenticationError
  puts "Invalid API key"
rescue TruthMark::APIError => e
  puts "Error (#{e.status_code}): #{e.message}"
end

Advanced Examples

Rails Controller

class WatermarksController < ApplicationController
  before_action :authenticate_user!

  def create
    file = params[:image]
    message = params[:message]

    client = TruthMark::Client.new(
      api_key: Rails.application.credentials.truthmark_api_key
    )

    result = client.encode(file.tempfile.path, message)
    render json: result
  rescue TruthMark::APIError => e
    render json: { error: e.message }, status: e.status_code
  end
end

Batch Processing with Threads

images = Dir.glob('./images/*.{png,jpg,jpeg}')
mutex = Mutex.new
results = []

threads = images.each_slice(5).flat_map do |batch|
  batch.map do |image|
    Thread.new do
      result = client.encode(image, '© 2025 My Company')
      mutex.synchronize { results << result }
      puts "✓ #{File.basename(image)}: PSNR=#{result[:metadata][:psnr].round(1)}dB"
    rescue TruthMark::APIError => e
      puts "✗ #{File.basename(image)}: #{e.message}"
    end
  end
end

threads.each(&:join)
puts "Watermarked #{results.size} images"

Best Practices

Use Rails credentials

Store API keys in config/credentials.yml.enc, not environment variables alone.

Use structured exception handling

Catch specific exceptions like RateLimitError before generic APIError.

Don't rescue Exception

Only rescue TruthMark::APIError and its subclasses, not Exception.

Need Help?

Check out the API reference or reach out to support.

API ReferenceContact Support