Class: TopazLabsClient

Inherits:
Object
  • Object
show all
Defined in:
app/services/topaz_labs_client.rb

Overview

Client for Topaz Labs Image Enhancement API

Provides AI-powered image upscaling, sharpening, denoising, and restoration
using industry-leading models from Topaz Labs.

All API calls are asynchronous:

  • Standard models use /enhance/async
  • Generative models use /enhance-gen/async

Examples:

Upscale an image

client = TopazLabsClient.new
result = client.upscale(image_path, model: 'standard_v2', output_width: 3840)
File.binwrite('upscaled.jpg', result)

Upscale low-resolution image

result = client.upscale(image_path, model: 'low_resolution_v2')

See Also:

Defined Under Namespace

Classes: AuthenticationError, Error, InvalidImageError, RateLimitError

Constant Summary collapse

BASE_URL = 
'https://api.topazlabs.com'
ENHANCE_MODELS =

Available upscaling models (Standard class - uses /enhance/async)
API model names must be exactly as documented

{
  'standard_v2' => {
    api_name: 'Standard V2',
    description: 'General-purpose model balancing detail, sharpness, and noise reduction',
    best_for: 'Most photos'
  },
  'low_resolution_v2' => {
    api_name: 'Low Resolution V2',
    description: 'Enhances clarity and detail in low-resolution images',
    best_for: 'Thumbnails, web graphics, small images'
  },
  'high_fidelity_v2' => {
    api_name: 'High Fidelity V2',
    description: 'Preserves intricate details in professional photography',
    best_for: 'High-quality source images'
  },
  'cgi' => {
    api_name: 'CGI',
    description: 'Optimized for CGI and digital illustrations',
    best_for: 'Digital art, illustrations, renders'
  },
  'text_refine' => {
    api_name: 'Text Refine',
    description: 'Enhances clarity of text and shapes',
    best_for: 'Documents, screenshots, graphics with text'
  }
}.freeze
GENERATIVE_MODELS =

Generative models (uses /enhance-gen/async - slower, higher quality)

{
  'recovery_v2' => {
    api_name: 'Recovery V2',
    description: 'High fidelity upscaling for extremely low-resolution images',
    best_for: 'Very small images needing maximum enhancement'
  },
  'standard_max' => {
    api_name: 'Standard MAX',
    description: 'Photorealistic detail with clean, natural feel',
    best_for: 'Low resolution inputs needing professional quality'
  },
  'wonder' => {
    api_name: 'Wonder',
    description: 'Cleans up low-res photos with small faces, heavy noise, or blurred backgrounds',
    best_for: 'Old images, social media, pixelated images'
  },
  'wonder_2' => {
    api_name: 'Wonder 2',
    description: 'High-accuracy upscale that restores fine detail in faces, textiles, text, and logos without oversharpening',
    best_for: 'Fine detail recovery, text/logo clarity, natural textures'
  },
  'redefine' => {
    api_name: 'Redefine',
    description: 'Advanced generative model for maximum quality',
    best_for: 'Best quality results, longer processing time'
  }
}.freeze
ALL_MODELS = 
ENHANCE_MODELS.merge(GENERATIVE_MODELS).freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key: nil) ⇒ TopazLabsClient

Returns a new instance of TopazLabsClient.

Raises:



92
93
94
95
 
# File 'app/services/topaz_labs_client.rb', line 92

def initialize(api_key: nil)
  @api_key = api_key || Rails.application.credentials.dig(:topazlabs, :api_key)
  raise AuthenticationError, 'Topaz Labs API key not configured' if @api_key.blank?
end

Class Method Details

.available? ⇒ Boolean

Check if Topaz Labs is configured and available

Returns:

  • (Boolean) 


136
137
138
 
# File 'app/services/topaz_labs_client.rb', line 136

def self.available?
  Rails.application.credentials.dig(:topazlabs, :api_key).present?
end

.model_options ⇒ Array<Array>

Get available models for dropdown

Returns:

  • (Array<Array>) —

    Array of [label, value] pairs for select



144
145
146
147
148
149
150
 
# File 'app/services/topaz_labs_client.rb', line 144

def self.model_options
  ENHANCE_MODELS.map do |key, info|
    ["#{info[:api_name]} - #{info[:best_for]}", key]
  end + [['--- Generative (slower, higher quality) ---', '']] + GENERATIVE_MODELS.map do |key, info|
    ["#{info[:api_name]} - #{info[:best_for]}", key]
  end
end

Instance Method Details

#upscale(image_source, model: 'standard_v2', output_width: nil, output_height: nil, output_format: 'jpeg') ⇒ String

Upscale an image using Topaz Labs enhance endpoint

All Topaz Labs API calls are asynchronous:

  • Standard models use POST /image/v1/enhance/async
  • Generative models use POST /image/v1/enhance-gen/async

Parameters:

  • image_source (String, File, Tempfile) —

    Path to image or file object

  • model (String) (defaults to: 'standard_v2') —

    Model key from ENHANCE_MODELS or GENERATIVE_MODELS

  • output_width (Integer, nil) (defaults to: nil) —

    Target width (auto-calculates if nil)

  • output_height (Integer, nil) (defaults to: nil) —

    Target height (auto-calculates if nil)

  • output_format (String) (defaults to: 'jpeg') —

    Output format: 'jpeg', 'png', 'tiff'

  • options (Hash) —

    Additional model-specific options

Returns:

  • (String) —

    Binary image data



111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'app/services/topaz_labs_client.rb', line 111

def upscale(image_source, model: 'standard_v2', output_width: nil, output_height: nil,
            output_format: 'jpeg', **)
  model_key = model.to_s.downcase.tr(' ', '_')
  model_info = ALL_MODELS[model_key]
  api_model_name = model_info&.dig(:api_name) || model

  # Determine if this is a generative model (uses different endpoint)
  is_generative = GENERATIVE_MODELS.key?(model_key)

  Rails.logger.info "[TopazLabsClient] Upscaling with model: #{api_model_name} " \
                    "(#{is_generative ? 'generative' : 'standard'}), format: #{output_format}"

  if is_generative
    enhance_generative(image_source, model_name: api_model_name, output_width: output_width,
                       output_height: output_height, output_format: output_format, **)
  else
    enhance_standard(image_source, model_name: api_model_name, output_width: output_width,
                     output_height: output_height, output_format: output_format, **)
  end
end