Skylab Studio Ruby Client

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

For all payload options, consult the API documentation.

Requirements

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

• Libvips documentation

Installation

$ gem install skylab_studio

or with Bundler:

$ gem 'skylab_studio'
$ bundle install

Usage

General

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)

Rails

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

Example usage

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

List all Jobs

• page - integer - The page of results to return

client.list_jobs()

Create a Job

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

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

Get a Job

• id - integer - The ID of the job

client.get_job(123)

Get a Job by name

• options - hash - The hash with job name

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

Update a 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 })

Queue a Job

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

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

Fetch Jobs in front

• job_id - hash - The ID of the job

client.fetch_jobs_in_front(123)

Delete a Job

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

client.delete_job(123)

Cancel a Job

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

client.cancel_job(123)

List all Profiles

• page - integer - The page of results to return

client.list_profiles()

Create a Profile

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

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

Get a Profile

• id - integer - The ID of the profile

client.get_profile(123)

Update a Profile

• 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 })

Upload Job Photo

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)

Upload Profile Photo

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)

Get a Photo

• id - integer - The ID of the photo

client.get_photo(123)

Delete a Photo

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

client.delete_photo(123)

Get job photos

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

client.get_job_photos(123)

Download photo(s)

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

Validate hmac headers

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)

Errors

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

Troubleshooting

General Troubleshooting

• 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

Enable Debug Mode

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)

Response Ranges

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

Build gem with

gem build skylab_studio.gemspec

Tests

Use rspec to run the tests:

$ rspec