Getting Started

ScopeCheck provides two group of web services: Similar Image Search and Image Prediction. The web services are also packaged as open source SDKs for Java and JavaScript, making it easy to integrate the service into your applications. All SDKs and related sample code can be found in ScopeMedia’s GitHub repository here.

Create Account

You must create a free account before using ScopeCheck. Sign up or log in to create applications, organize image assets, and monitor your API usage.

Create Application

Each API call must be associated with an application. To create an application, navigate to the “Credentials” tab on the ScopeCheck dashboard and click on the “Create API Key” button. Select a unique name and an appropriate model for your application. Note: the model is only used for Image Prediction, not Similar Image Search. After creating an application, you will see your new credentials: application name, client ID, and client secret.

Authentication

All APIs requests must be authorized by a pair of keys (your client ID and client secret), which can be found on the ScopeCheck dashboard under the “Credentials/Your Applications” tab. You must include these keys in the request headers for all API calls, as shown below (replace [client-id] and [client-secret] with your client ID and secret):


Content-Type: application/json
Client-Id: [client-id]
Client-Secret: [client-secret]

The Similar Image Search service is a series of APIs that allow you to create and search an image collection for visually similar images, given an image as input. Note: the search is restricted to the dataset that you provide.

Create Image Set

Before you can use the Similar Image Search API, you must index the specific collection of images you wish to search. To create a new image collection, create an application from the “Credentials” tab (as above). You can then view and manage the image collections associated with each of your applications from the “Similar Search” tab.

Upload Image Data

There are two ways to add images to your collection:

1. To upload images from your local file, navigate to the “Similar Search” tab of the ScopeCheck dashboard. Select the image collection you wish to modify and click on the upload button. Drag and drop images from your local file to the pop up “Upload Images” dialog box.

2. To add images by URL, use the following API either directly or through one of the SDKs. The service will index the images in your application.

(Note: there may be a delay of up to 10 minutes for new images added into the collection.)

POST https://api.scopemedia.com/search/v2/medias

Request

Fields

Name Type Description
medias Media[] Array of medias

Media

Name Type Description
mediaUrl String Url of an image
{
    "medias": [
       {
           "mediaUrl": "http://example.com/image_1.jpg"
       },
       {
           "mediaUrl": "http://example.com/image_2.jpg"
       }
    ]
 }

Add “single-tab-hack” class to the old tabs element to show only the first tab

Response

Fields

Name Type Description
status String or Int See Result Status
error String Error message
medias Media[] Array of medias

Media

Name Type Description
mediaId long Media ID
mediaUrl String Media URL
{
    "status": "OK",
    "error": null,
    "medias": [
       {  
          "mediaId": 10001,
          "mediaUrl": "http://example.com/image_1.jpg"
       },
       {
          "mediaId": 10002,
          "mediaUrl": "http://example.com/image_2.jpg"
       }
    ] 
 }

Add “single-tab-hack” class to the old tabs element to show only the first tab

Get Image Set

To view the images in your collection, navigate to the “Similar Search” tab and select your application. You may also use the following API (directly or through the SDK) to retrieve the URLs and media IDs of the images within your collection.

GET https://api.scopemedia.com/search/v2/medias?page=0&size=20

Request

Parameter

Name Type Description
Page Int Page number (default 0)
Size Int Number of images per page (default 20)

Response

Fields

Name Type Description
status String or Int See Result Status
error String Error message
medias Media[] Array of medias

Media

Name Type Description
mediaId long Media ID
mediaUrl String Media URL
{
    "status": "OK",
    "error": null,
    "medias": [
       {  
          "mediaId": 10001,
          "mediaUrl": "http://example.com/image_1.jpg"
       },
       {
          "mediaId": 10002,
          "mediaUrl": "http://example.com/image_2.jpg"
       },
       {
          "mediaId": 10003,
          "mediaUrl": "http://example.com/image_3.jpg"
       }
    ] 
 }

Add “single-tab-hack” class to the old tabs element to show only the first tab

Search Similar Images

The Similar Image Search API compares the input image to all the images in your indexed image collection and returns the most visually similar images. There are two ways to perform a similar image search:

1. Use the ScopeCheck dashboard. Select an image from your collection or upload an image to compare by clicking the search button. You will see the search results immediately. The results are ordered by similarity to your query input.

2. Use the API (directly or through the SDK). The API supports three forms of image input: a media ID from your image collection, the media URL, or a base64 encoded image. Only one image format is required for each request. You may also define a rectangle within an image as the input for your query by specifying the origin, width, and height of your rectangle in the “area” parameter.

POST https://api.scopemedia.com/search/v2/similar

Request

Fields

Name Type Description
mediaId long Media ID
Media as ID, Base64 or as URL is required
mediaUrl String Media URL
Media as ID, Base64 or as URL is required
base64 String Base64 encoded media
Media as ID, Base64 or as URL is required
area Area Set an area which will be used for the similar images. See Area field

Area

Name Type Description
h Int Height
w Int Width
Int Start position x
Int Start position y
{
    "mediaUrl": "http://example.com/image.jpg",
    "area": {  
       "h": 100,
       "w": 100,
       "x": 10,
       "y": 10
    }
 }

Add “single-tab-hack” class to the old tabs element to show only the first tab

Response

Fields

Name Type Description
status String or Int See Result Status
error String Error message
medias Media[] Array of medias

Media

Name Type Description
mediaId long Media ID
mediaUrl String Media URL
{
    "status": "OK",
    "error": null,
    "medias": [
       {  
          "mediaId": 10001,
          "mediaUrl": "http://example.com/similar_1.jpg"
       },
       {
          "mediaId": 10005,
          "mediaUrl": "http://example.com/similar_5.jpg"
       }
    ] 
 }

Add “single-tab-hack” class to the old tabs element to show only the first tab

Image Prediction

The Image Prediction API analyzes image content and returns a list of tags, which includes a label and its relevance score. It can be used to detect concepts such as individual products, objects, detailed fashion attributes, or outfit style. Note: you must specify a model ID for each prediction request.

Get Models

ScopeMedia provides a few pre-trained models for different domains. Contact us if you need to train your own model. To request a list of the available models, use the following API:

GET https://api.scopemedia.com/tagging/v2/models

Response

Fields

Name Type Description
status String or Int See Result Status
error String Error message
models Models[] See Model field

Models

Name Type Description
modelId String Model ID
modelName String Model name
status String Model status
public Boolean Model public state
{
    "status": "OK",
    "error": null,
    "models": [
        {
            "modelId": "sample-model",
            "modelName": "Sample Model",
            "status": "IN_USE",
            "public": true
        }
    ]
 }

Predict Image

The Image Prediction API requires a model ID and an input (either the image URL or a base64 encoded image) as follows:

POST https://api.scopemedia.com/tagging/v2/prediction

Request

Fields

Name Type Description
modelId String The ID of the prediction model to use
mediaUrl String URL of an image
Media as Base64 or as URL is required
base64 String Base64 encoded image
Media as Base64 or as URL is required
area Area Set an area which will be used for prediction. See Area field

Area

Name Type Description
h Int Height
w Int Width
Int Start position x
Int Start position y
{
    "modelId": "sample-model",
    "mediaUrl": "http://example.com/image.jpg",
    "area": {  
       "h":100,
       "w":100,
       "x":10,
       "y":10
    }
 }

Response

Fields

Name Type Description
status String or Int See Result Status
error String Error message.
tags Tag[] See Tag field

Tag

Name Type Description
label String Prediction label based on the selected model
score String Accuracy based on the selected model
{
    "status": "OK",
    "error": null,
    "tags": [  
       {  
          "label": "example tag",
          "score": "0.0934"
       }
    ]
 }

Add “single-tab-hack” class to the old tabs element to show only the first tab

Result Status

Status/Code Description
OK Success  API call succeed
400 Bad Request  Incorrect request body or parameter
403 Forbidden  Incorrect client ID or secret
404 Not Found  Incorrect API url
405 Method Not Allowed  Incorrect request method
500 Internal Server Error Server error