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).
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