Getting Started

The ScopeMedia API offers advanced image search capabilities.

Before you will be able to use the API you will need to register. Once you register you can log in and create a new application. You can have multiple apps and an app can be shared by several users. As part of the app creation process you will receive your client ID and client secret which are required to authenticate API requests, so please do that before continuing.

Authentication

Authentication to the API is done via a pair of keys. When you create an application, you will be supplied with a unique client ID and client secret which you will use to authorize API requests. You must include them in the request headers in 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 Search request finds images in the database that are similar to a specified image.

Add Image

POST https://api.scopemedia.com/search/v2/medias
This API adds image(s) to your image set.

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

GET https://api.scopemedia.com/search/v2/medias?page=0&size=20
This API returns all images in your image set.

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

POST https://api.scopemedia.com/search/v2/similar
This API returns images in your image set that are similar to the provided image.

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

Prediction

The Image Prediction request analyzes the image content and returns a list of tags, which includes a label and its relevance score.

Get Models

GET https://api.scopemedia.com/tagging/v2/models
This API returns a list of available models for image prediction.

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
        }
    ]
 }

POST https://api.scopemedia.com/tagging/v2/prediction
This API returns a list of predicted tags based on the provided image.

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