Overview

With the Slyce API you have the ability to integrate Slyce's Visual Search, Reference Image Matching, Barcode Detection & Lookup service, and more into your application through secure and direct access to the same underlying processing engine that powers Slyce’s native and web SDK offerings.  This allows you to provide a consistent experience across a number of platforms in a way that best fits your application needs.

Getting Started

The Slyce API exposes authenticated RESTful endpoints that enable you to execute one or more of Slyce’s core processing services or workflows that have been tuned to service your particular implementation needs.  In order to access these endpoints you will first need to obtain your API credentials and ensure that your data has been properly loaded into Slyce’s processing platform.

Getting your Credentials

Slyce API credentials will be provided to you by a Slyce solutions engineer during your account creation. To successfully call the Slyce API you will ultimately need a Slyce API Key, your Account ID, a Space ID, and a Workflow ID that has been prepared for you to perform a particular processing task. During the initial setup of your account, a Slyce solutions engineer will assist you with preparing and obtaining these items.

Slyce API Keys are created following the principle of least privilege thus helping limit access beyond what is required to perform only the essential operations necessary to powering your particular workflows.

Importing Data

Many of the core services offered by the Slyce API requires access to some sort of custom data.  A Slyce solutions engineer will work with you during the account creation phase to ensure that the proper information needed to support these services has been provided.   

Furthermore, a Slyce solutions engineer will assist you with the data ingestion into the system so that you can focus more time on integrating the pieces that matter most to your Slyce API implementation.

Calling the API

Once you have obtained your Slyce API credentials and your data has been properly loaded into Slyce’s processing platform, you are ready to start calling the Slyce API.

Executing a workflow

Workflows are the core processing pipelines behind many of the services exposed through the Slyce API.  Executing a workflow requires issuing an HTTP POST request to an endpoint of the form below; substituting in your own IDs as provided to you by a Slyce solutions engineer:

https://api.slyce.it/v2/accounts/account_id/spaces/space_id/workflows/workflow_id/execute

In addition, for all requests issued to the Slyce API you will need to set the proper authentication request header, slyce-api-key. This header should be set to the same Slyce API Key that was provided to you by a Slyce solutions engineer.  If any of this information is missing or incorrect then you will receive a 401, 403, or a 404 HTTP response code depending on the operation being performed.

Once you have successfully acquired and set all of the information above, you will now want to execute the workflow by submitting an image to the server for processing.  There are two methods for accomplishing this, both of which require passing information through the HTTP request’s form data.

The first option allows you to submit a valid JPEG or PNG file directly to the server via the image form data field.  The second option allows you to submit a remote image via the image_url form data field.  This field will be ignored if an image value has been specified.

To quickly test your workflow you can issue the following cURL command:

curl -X POST \
 -H "slyce-api-key: ${SLYCE_API_KEY}" \
 -F "image=@${IMAGE_PATH}" \
 "https://api.slyce.it/v2/accounts/${ACCOUNT_ID}/spaces/${SPACE_ID}/workflows/${WORKFLOW_ID}/execute"

If everything executes successfully then you will receive a 200 HTTP response code and an object with the following structure:

{
   # The dataset that produced the results
   “dataset_id”: "",

   # A list of keywords that were uncovered during the
   # workflow execution process.
   “keywords”: [],   
                   
   # A list of the raw data items, contained in the dataset,
   # that correspond to the workflow results.
   “items”: [{}],    
                    
   # A list of result objects, ranked by descending
   # match score, where each entry in the list corresponds
   # to a matching item in the “items” list at the same
   # ordinal
   “results”: [{
       
       # The item_id or the matched data item from the dataset.
       “item_id”: “”,    

       # A number between 0 and 1 representing the match score.
       # Higher scores should be considered “better” results.
       “score”: 0.00,

       # Information about the image that was matched.
       “image”: {
          # The original URL of the image that produced this match.
          “url”: “”
       }
   }]              
}

Additional API Options

Workflows can be constructed that may require additional information to be provided in order to run properly.  A Slyce solutions engineer will help determine what is necessary during the account and workflow creation phase, but some combination of the following will likely be used:

Additional Parameters

Certain workflows allow you to specify special options that are capable of being used in dynamic ways by the server to assist in producing results.  These workflow options can be provided to the Slyce API as standard query string values:

https://api.slyce.it/v2/accounts/account_id/spaces/space_id/workflows/workflow_id/execute?opt=val

Additional Headers

Additional Form Data