A Ruby client for accessing the Skylab Studio service: http://studio.skylabtech.ai

For all payload options, consult the API documentation.

libvips is required to be installed on your machine in order to install skylab-studio (for pyvips).

• Libvips documentation

$ gem install skylab_studio

or with Bundler:

$ gem 'skylab_studio'
$ bundle install

Create a new instance of the client using your API key.

require 'rubygems'
require 'skylab_studio'

client = SkylabStudio::Client.new(api_key: 'YOUR API KEY', debug: true)

For a Rails app, create skylab_studio.rb in /config/initializers/ with the following:

SkylabStudio::Client.configure do |config|
  config.api_key = 'YOUR API KEY'
  config.debug = true
end

In your application code where you want to access Skylab API:

begin
  result = SkylabStudio::Client.new.create_job({ profile_id: 123 })
  puts result
rescue => e
  puts "Error - #{e.class.name}: #{e.message}"
end

require skylab_studio

client = SkylabStudio::Client.new()
client = SkylabStudio::Client.new({ max_download_concurrency: 5 }) # to set download concurrency (default: 5)

# CREATE PROFILE
profile = client.create_profile({ name: "Test Profile", enable_crop: false, enable_color: false, enable_extract: true })

# CREATE JOB
job_name = "test-job-#{random_uuid}";
job = client.create_job({ name: job_name, profile_id: profile['id'] });

# UPLOAD PHOTO
file_path = "/path/to/photo.jpg";
client.upload_job_photo(file_path, job['id']);

# QUEUE JOB
queued_job = client.queue_job({ id: job['id'], callback_url: "http://server.callback.here/" });

# NOTE: Once the job is queued, it will get queued, processed, and then complete
# We will send a response to the specified callback_url with the output photo download urls

# OPTIONAL: If you want this SDK to handle photo downloads to a specified output folder

# FETCH COMPLETED JOB (wait until job status is completed)
completed_job = client.get_job(queued_job['id']);

# DOWNLOAD COMPLETED JOB PHOTOS
photos_list = completed_job['photos'];
client.download_all_photos(photos_list, completed_job['profile'], "photos/output/");

# OR, download single photo
client.download_photo(photos_list[0]["id"], "/output/folder/"); # keep original filename
client.download_photo(photos_list[0]["id"], "/output/folder/new_name.jpg"); # rename output image

• page - integer - The page of results to return

client.list_jobs()

• job - hash - The attributes of the job to create

client.create_job({ name: "TEST JOB", profile_id: 123 })

• id - integer - The ID of the job

client.get_job(123)

• options - hash - The hash with job name

client.get_job({ name: "TEST JOB" })

• id - integer - The ID of the job to update
• options - hash - The attributes of the job to update

client.update_job(id: 123, { name: "new job name", profile_id: 456 })

• options - hash - The attributes of the job to queue

client.queue_job({ id: 123, callback_url: "http://callback.url.here/ })

• job_id - hash - The ID of the job

client.fetch_jobs_in_front(123)

• id - integer - The ID of the job to delete

client.delete_job(123)

• id - integer - The ID of the job to cancel

client.cancel_job(123)

• page - integer - The page of results to return

client.list_profiles()

• options - hash - The attributes of the profile to create

client.create_profile({ name: "New profile", enable_crop: false, enable_color: false, enable_extract: true })

• id - integer - The ID of the profile

client.get_profile(123)

• profile_id - integer - The ID of the profile to update
• options - hash - The attributes of the profile to update

client.update_profile(123, { name: "new profile name", enable_color: true })

This method handles validating a photo, creating a photo object and uploading it to your job/profile's s3 bucket. If the bucket upload process fails, it retries 3 times and if failures persist, the photo object is deleted.

• photo_path - string - The current local file path of the image file
• job_id - integer - The ID of the job to associate the image file upload to

client.upload_job_photo('/path/to/photo.jpg', 123)

This function handles validating a background photo for a profile. Note: enable_extract and replace_background (profile attributes) MUST be true in order to create background photos. Follows the same upload process as upload_job_photo.

• photo_path - string - The current local file path of the image file
• profile_id - integer - The ID of the profile to associate the image file upload to

client.upload_profile_photo('/path/to/photo.jpg', 123)

• id - integer - The ID of the photo

client.get_photo(123)

• id - integer - The ID of the photo to delete

client.delete_photo(123)

• id - integer - The ID of the job to get photos from

client.get_job_photos(123)

This function handles downloading the output photos to a specified directory.

photos_list = completed_job['photos']

download_results = client.download_all_photos(photos_list, completed_job['profile'], "/output/folder/path")

Output:
{'success_photos': ['1.JPG'], 'errored_photos': []}

OR

client.download_photo(photo_id, "/output/folder/path") # download photo with original filename to a directory
client.download_photo(photo_id, "/output/folder/test.jpg") # download photo with new filename to a directory

Applicable if you utilize the job callback url. Use to validate the job payload integrity.

• secret_key (string): Obtain from Skylab

• job_json_string (string): Raw json string obtained from callback PATCH request body

• request_timestamp (string): Obtained from callback PATCH request header 'X-Skylab-Timestamp'

• signature (string): Signature generated by Skylab to compare. Obtained from callback PATCH request header 'X-Skylab-Signature'

Returns True or False based on whether or not the signatures match.

api.validate_hmac_headers(secret_key, job_json_string, request_timestamp, signature)

The following errors may be generated:

SkylabStudio::ClientInvalidEndpoint - the target URI is probably incorrect
SkylabStudio::ClientInvalidKey - the skylab client API key is invalid
SkylabStudio::ClientBadRequest - the API request is invalid
SkylabStudio::ClientConnectionRefused - the target URI is probably incorrect
SkylabStudio::ClientUnknownError - an unhandled HTTP error occurred

• Enable debug mode
• Make sure you're using the latest Ruby client
• Capture the response data and check your logs — often this will have the exact error

Debug mode prints out the underlying request information as well as the data payload that gets sent to Skylab API. You will most likely find this information in your logs. To enable it, simply put debug: true as a parameter when instantiating the API object.

client = SkylabStudio::Client.new(api_key: 'YOUR API KEY', debug: true)

Skylab API typically sends responses back in these ranges:

• 2xx – Successful Request
• 4xx – Failed Request (Client error)
• 5xx – Failed Request (Server error)

If you're receiving an error in the 400 response range follow these steps:

• Double check the data and ID's getting passed to Skylab Core
• Ensure your API key is correct
• Log and check the body of the response

Build gem with

gem build skylab_studio.gemspec

Use rspec to run the tests:

$ rspec