NAV
shell python javascript

Introduction

The MachineTutors API (MT API) is organized around REST. Our API has task-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

You can use our API to analyze your image and audio data in real time.

We have given example queries in Shell, Python, and JavaScript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

To authorize, use this code:

import requests
import json

YOUR_API_KEY = 'your_api_key'
HOST = 'api.machinetutors.com'
PORT = 8020
url = f"https://{HOST}:{PORT}/v1/auth"

headers = {"key": YOUR_API_KEY}
rr = requests.post(url, headers=headers)

ret = rr.content
# parse y:
y = json.loads(ret)
auth_status = y['status']
# With shell, you can just pass the correct header with each request
curl "https://api.machinetutors.com:8020/v1/auth" \
  -H "key: YOUR_API_KEY"
var API_HOST = 'api.machinetutors.com';
var API_PORT = 8020;
var API_VERSION = 'v1';

var YOUR_API_KEY = 'your_api_key';

var path = 'auth';
var post_url = `https://${API_HOST}:{API_PORT}/${API_VERSION}/${path}`;

var post_obj = {
    url: post_url,
    type: 'POST',       // needed if using jquery < 1.9.0.
    method: 'POST',
    context: document.body,
    headers: {
        "key": YOUR_API_KEY
    },
    dataType: "json"
}

var ajaxRequest = $.ajax(post_obj);

ajaxRequest.done((data) => {
    // console.log(`-- succ`);
    handle success
  })
  .fail((jqXHR, textStatus, errorThrown) => {
    // handle failure
  })
  .always((data) => {
    // in any case
  });

Make sure to replace YOUR_API_KEY with your API key.

MT API uses API keys to allow access to the API. You can register a new API key at our developer portal.

MT API expects for the API key to be included in all API requests to the server in a header that looks like the following:

key: YOUR_API_KEY

We also provide a generic API key to test our API end points. This key has a maximum limit of 100 queries.

TEST_API_KEY: QKY_Dp0dRrGe3kZ_uR1AAlpONWsGICSIto06818iEiTGLOeFwD3c_8mnCQ_rwm5X0rg3AgS8olQRf0c_P_68CA

MT Image API

MT Image API has several models to analyze image data.

All image end points expect base64 encoded data in the body of the request with the keyword image.

Alternatively, you can also give url of an image in the header of the request with the keyword url.

Classification

This endpoint classifies a given image into four possible classes namely food, sport, nature and architecture.

import requests
import json

YOUR_API_KEY = 'your_api_key'
HOST = 'api.machinetutors.com'
PORT = 8020
url = f"https://{HOST}:{PORT}/v1/image/classification"

# Option 1: base64 image in the body
base64_encoded_image = 'your_base64_encoded_image'
headers = {"key": YOUR_API_KEY}
payload = {"image": base64_encoded_image}
rr = requests.post(url, data=payload, headers=headers)

# Option 2: image url in the header
image_url = "url_of_the_image"  # https://image.shutterstock.com/image-photo/mountains-during-sunset-beautiful-natural-260nw-407021107.jpg
headers = {"key": YOUR_API_KEY, "url": image_url}
rr = requests.post(url, headers=headers)

ret = rr.content
# parse y:
y = json.loads(ret)
image_class = y['image_class']
curl -X POST "https://api.machinetutors.com:8020/v1/image/classification" \
-H "key: YOUR_API_KEY" \
--data-raw "{"image": "your_base64_encoded_image"}"
var API_HOST = 'api.machinetutors.com';
var API_PORT = 8020;
var API_VERSION = 'v1';

var YOUR_API_KEY = 'your_api_key';
var base64_encoded_image = 'your_base64_encoded_image';

var path = 'image/classification';
var post_url = `https://${API_HOST}:{API_PORT}/${API_VERSION}/${path}`;

var post_obj = {
    url: post_url,
    type: 'POST',       // needed if using jquery < 1.9.0.
    method: 'POST',
    context: document.body,
    headers: {
        "key": YOUR_API_KEY
    },
    data: { "image": base64_encoded_image },
    dataType: "json"
}

var ajaxRequest = $.ajax(post_obj);

ajaxRequest.done((data) => {
    // console.log(`-- succ`);
    handle success
  })
  .fail((jqXHR, textStatus, errorThrown) => {
    // handle failure
  })
  .always((data) => {
    // in any case
  });

The above calls return JSON structured like this:

{
  "image_class": "nature"
}

Tagging

This endpoint returns a list of tags that defines the content of the given image.

import requests
import json

YOUR_API_KEY = 'your_api_key'
HOST = 'api.machinetutors.com'
PORT = 8020
url = f"https://{HOST}:{PORT}/v1/image/tagging"

base64_encoded_image = 'your_base64_encoded_image'
headers = {"key": YOUR_API_KEY}
payload = {"image": base64_encoded_image}
rr = requests.post(url, data=payload, headers=headers)

ret = rr.content
# parse y:
y = json.loads(ret)
image_tags = y['image_tags']
curl -X POST "https://api.machinetutors.com:8020/v1/image/tagging" \
-H "key: YOUR_API_KEY" \
--data-raw "{"image": "your_base64_encoded_image"}"
var API_HOST = 'api.machinetutors.com';
var API_PORT = 8020;
var API_VERSION = 'v1';

var YOUR_API_KEY = 'your_api_key';
var base64_encoded_image = 'your_base64_encoded_image';

var path = 'image/tagging';
var post_url = `https://${API_HOST}:{API_PORT}/${API_VERSION}/${path}`;

var post_obj = {
    url: post_url,
    type: 'POST',       // needed if using jquery < 1.9.0.
    method: 'POST',
    context: document.body,
    headers: {
        "key": YOUR_API_KEY
    },
    data: { "image": base64_encoded_image },
    dataType: "json"
}

var ajaxRequest = $.ajax(post_obj);

ajaxRequest.done((data) => {
    // console.log(`-- succ`);
    handle success
  })
  .fail((jqXHR, textStatus, errorThrown) => {
    // handle failure
  })
  .always((data) => {
    // in any case
  });

The above command returns JSON structured like this:

{
    "image_tags": [
        "tie",
        "person"
    ]
}

Person Counter

This endpoint counts number of visible people in a given image.

import requests
import json

YOUR_API_KEY = 'your_api_key'
HOST = 'api.machinetutors.com'
PORT = 8020
url = f"https://{HOST}:{PORT}/v1/image/person_count"

base64_encoded_image = 'your_base64_encoded_image'
headers = {"key": YOUR_API_KEY}
payload = {"image": base64_encoded_image}
rr = requests.post(url, data=payload, headers=headers)

ret = rr.content
# parse y:
y = json.loads(ret)
person_count = y['person_count']
curl -X POST "https://api.machinetutors.com:8020/v1/image/person_count" \
-H "key: YOUR_API_KEY" \
--data-raw "{"image": "your_base64_encoded_image"}"
var API_HOST = 'api.machinetutors.com';
var API_PORT = 8020;
var API_VERSION = 'v1';

var YOUR_API_KEY = 'your_api_key';
var base64_encoded_image = 'your_base64_encoded_image';

var path = 'image/person_count';
var post_url = `https://${API_HOST}:{API_PORT}/${API_VERSION}/${path}`;

var post_obj = {
    url: post_url,
    type: 'POST',       // needed if using jquery < 1.9.0.
    method: 'POST',
    context: document.body,
    headers: {
        "key": YOUR_API_KEY
    },
    data: { "image": base64_encoded_image },
    dataType: "json"
}

var ajaxRequest = $.ajax(post_obj);

ajaxRequest.done((data) => {
    // console.log(`-- succ`);
    handle success
  })
  .fail((jqXHR, textStatus, errorThrown) => {
    // handle failure
  })
  .always((data) => {
    // in any case
  });

The above command returns JSON structured like this:

{
    "person_count": "1"
}

Not Safe For Work

This endpoint determines a given image is whether safe or nsfw.

import requests
import json

YOUR_API_KEY = 'your_api_key'
HOST = 'api.machinetutors.com'
PORT = 8020
url = f"https://{HOST}:{PORT}/v1/image/nsfw"

base64_encoded_image = 'your_base64_encoded_image'
headers = {"key": YOUR_API_KEY}
payload = {"image": base64_encoded_image}
rr = requests.post(url, data=payload, headers=headers)

ret = rr.content
# parse y:
y = json.loads(ret)
nsfw_status = y['nsfw_status']
curl -X POST "https://api.machinetutors.com:8020/v1/image/nsfw" \
-H "key: YOUR_API_KEY" \
--data-raw "{"image": "your_base64_encoded_image"}"
var API_HOST = 'api.machinetutors.com';
var API_PORT = 8020;
var API_VERSION = 'v1';

var YOUR_API_KEY = 'your_api_key';
var base64_encoded_image = 'your_base64_encoded_image';

var path = 'image/nsfw';
var post_url = `https://${API_HOST}:{API_PORT}/${API_VERSION}/${path}`;

var post_obj = {
    url: post_url,
    type: 'POST',       // needed if using jquery < 1.9.0.
    method: 'POST',
    context: document.body,
    headers: {
        "key": YOUR_API_KEY
    },
    data: { "image": base64_encoded_image },
    dataType: "json"
}

var ajaxRequest = $.ajax(post_obj);

ajaxRequest.done((data) => {
    // console.log(`-- succ`);
    handle success
  })
  .fail((jqXHR, textStatus, errorThrown) => {
    // handle failure
  })
  .always((data) => {
    // in any case
  });

The above command returns JSON structured like this:

{
    "nsfw_status": "Safe"
}

This endpoint searches visually similar images in an image pool and returns their names and base64 encoded versions. This image pool contains 25K images from various domains.

import requests
import json

YOUR_API_KEY = 'your_api_key'
HOST = 'api.machinetutors.com'
PORT = 8020
url = f"https://{HOST}:{PORT}/v1/image/visual_search"

base64_encoded_image = 'your_base64_encoded_image'
headers = {"key": YOUR_API_KEY}
payload = {"image": base64_encoded_image}
rr = requests.post(url, data=payload, headers=headers)

ret = rr.content
# parse y:
y = json.loads(ret)
similar_images = y['similar_images']
curl -X POST "https://api.machinetutors.com:8020/v1/image/visual_search" \
-H "key: YOUR_API_KEY" \
--data-raw "{"image": "your_base64_encoded_image"}"
var API_HOST = 'api.machinetutors.com';
var API_PORT = 8020;
var API_VERSION = 'v1';

var YOUR_API_KEY = 'your_api_key';
var base64_encoded_image = 'your_base64_encoded_image';

var path = 'image/visual_search';
var post_url = `https://${API_HOST}:{API_PORT}/${API_VERSION}/${path}`;

var post_obj = {
    url: post_url,
    type: 'POST',       // needed if using jquery < 1.9.0.
    method: 'POST',
    context: document.body,
    headers: {
        "key": YOUR_API_KEY
    },
    data: { "image": base64_encoded_image },
    dataType: "json"
}

var ajaxRequest = $.ajax(post_obj);

ajaxRequest.done((data) => {
    // console.log(`-- succ`);
    handle success
  })
  .fail((jqXHR, textStatus, errorThrown) => {
    // handle failure
  })
  .always((data) => {
    // in any case
  });

The above command returns JSON structured like this:

{
  "similar_images": ["uOnxXwB3KNE.jpg", "vCZFKRZes_0.jpg", "4i7JbYNVEdc.jpg", "bgXihebRRSo.jpg", "4leb57mSMYE.jpg", "RiD-wabAD3E.jpg", "4Lh-4xE5_Js.jpg", "iiQ-mmG2NxI.jpg", "88Sx1H991w0.jpg", "-GsEJuUdzqk.jpg", "2c8uI47Lwxo.jpg", "mdbmLTJF9kY.jpg", "wYJLHqe1r8U.jpg", "cVWqlb4HtH8.jpg", "ci-Lit-OEnY.jpg", "J95m2xJR9YQ.jpg", "yzRs2WCYPy8.jpg", "X8s4HMKO9GI.jpg", "rQaRcEdLc9c.jpg", "uRcl64R-D-A.jpg", "eLg61SidxVw.jpg", "DRf_4EMERXo.jpg", "5AeWY1scy-Q.jpg", "WkRKRoBzKZk.jpg", "ava0qkuTJ1g.jpg"],
  "image_1": "base64_image1", "image_2": "base64_image2",  .... , "image_25": "base64_image25"
}

Photo vs Cartoon

This endpoint checks a given image contains real human images and/or synthetic/cartoon human images.

import requests
import json

YOUR_API_KEY = 'your_api_key'
HOST = 'api.machinetutors.com'
PORT = 8020
url = f"https://{HOST}:{PORT}/v1/image/photo_cartoon"

base64_encoded_image = 'your_base64_encoded_image'
headers = {"key": YOUR_API_KEY}
payload = {"image": base64_encoded_image}
rr = requests.post(url, data=payload, headers=headers)

ret = rr.content
# parse y:
y = json.loads(ret)
photo_vs_cartoon = y['photo_vs_cartoon']
curl -X POST "https://api.machinetutors.com:8020/v1/image/photo_cartoon" \
-H "key: YOUR_API_KEY" \
--data-raw "{"image": "your_base64_encoded_image"}"
var API_HOST = 'api.machinetutors.com';
var API_PORT = 8020;
var API_VERSION = 'v1';

var YOUR_API_KEY = 'your_api_key';
var base64_encoded_image = 'your_base64_encoded_image';

var path = 'image/photo_cartoon';
var post_url = `https://${API_HOST}:{API_PORT}/${API_VERSION}/${path}`;

var post_obj = {
    url: post_url,
    type: 'POST',       // needed if using jquery < 1.9.0.
    method: 'POST',
    context: document.body,
    headers: {
        "key": YOUR_API_KEY
    },
    data: { "image": base64_encoded_image },
    dataType: "json"
}

var ajaxRequest = $.ajax(post_obj);

ajaxRequest.done((data) => {
    // console.log(`-- succ`);
    handle success
  })
  .fail((jqXHR, textStatus, errorThrown) => {
    // handle failure
  })
  .always((data) => {
    // in any case
  });

The above command returns JSON structured like this:

{
  "photo_vs_cartoon": {"photographic_people": false, "synth_or_cartoonish_people": true}
}

Super Resolution

This endpoint up samples a given image by a factor of four. This results in much better looking images.

import requests
import json

YOUR_API_KEY = 'your_api_key'
HOST = 'api.machinetutors.com'
PORT = 8020
url = f"https://{HOST}:{PORT}/v1/image/super_resolution"

base64_encoded_image = 'your_base64_encoded_image'
headers = {"key": YOUR_API_KEY}
payload = {"image": base64_encoded_image}
rr = requests.post(url, data=payload, headers=headers)

ret = rr.content
# parse y:
y = json.loads(ret)
similar_images = y['image']
curl -X POST "https://api.machinetutors.com:8020/v1/image/super_resolution" \
-H "key: YOUR_API_KEY" \
--data-raw "{"image": "your_base64_encoded_image"}"
var API_HOST = 'api.machinetutors.com';
var API_PORT = 8020;
var API_VERSION = 'v1';

var YOUR_API_KEY = 'your_api_key';
var base64_encoded_image = 'your_base64_encoded_image';

var path = 'image/super_resolution';
var post_url = `https://${API_HOST}:{API_PORT}/${API_VERSION}/${path}`;

var post_obj = {
    url: post_url,
    type: 'POST',       // needed if using jquery < 1.9.0.
    method: 'POST',
    context: document.body,
    headers: {
        "key": YOUR_API_KEY
    },
    data: { "image": base64_encoded_image },
    dataType: "json"
}

var ajaxRequest = $.ajax(post_obj);

ajaxRequest.done((data) => {
    // console.log(`-- succ`);
    handle success
  })
  .fail((jqXHR, textStatus, errorThrown) => {
    // handle failure
  })
  .always((data) => {
    // in any case
  });

The above command returns JSON structured like this:

{
   "image": "base64_image"
}

Facial Analysis

Our facial analysis solution is able to instantly and accurately detect gender, give an age estimation and identify emotion in an image. It perceives a range of emotions, such as happiness, sadness, neutrality, fear, disgust, anger and contempt.

import requests
import json

YOUR_API_KEY = 'your_api_key'
HOST = 'https://api.machinetutors.com'
PORT = 8020
url = f"https://{HOST}:{PORT}/v1/image/facial_analysis"

base64_encoded_image = 'your_base64_encoded_image'
headers = {"key": YOUR_API_KEY}
payload = {"image": base64_encoded_image}
rr = requests.post(url, data=payload, headers=headers)

ret = rr.content
# parse y:
y = json.loads(ret)
# iterate all faces and print information
for kk, ppl in y.items():
    try:
        age = ppl["age"]
        gender = ppl["gender"]
        emotion = ppl['emotion']
        info_text = f"Age: {age}, Gender: {gender}, Emotion: {emotion}"
    except:
        pass
curl -X POST "https://api.machinetutors.com:8020/v1/image/facial_anaylsis" \
-H "key: YOUR_API_KEY" \
--data-raw "{"image": "your_base64_encoded_image"}"
var API_HOST = 'api.machinetutors.com';
var API_PORT = 8020;
var API_VERSION = 'v1';

var YOUR_API_KEY = 'your_api_key';
var base64_encoded_image = 'your_base64_encoded_image';

var path = 'image/facial_anaylsis';
var post_url = `https://${API_HOST}:{API_PORT}/${API_VERSION}/${path}`;

var post_obj = {
    url: post_url,
    type: 'POST',       // needed if using jquery < 1.9.0.
    method: 'POST',
    context: document.body,
    headers: {
        "key": YOUR_API_KEY
    },
    data: { "image": base64_encoded_image },
    dataType: "json"
}

var ajaxRequest = $.ajax(post_obj);

ajaxRequest.done((data) => {
    // console.log(`-- succ`);
    handle success
  })
  .fail((jqXHR, textStatus, errorThrown) => {
    // handle failure
  })
  .always((data) => {
    // in any case
  });

The above command returns JSON structured like this:

{
  "0": {"face_box": [436, 228, 475, 289], "age": "4-13", "gender": "F", "emotion": "happy"},
  "1": {"face_box": [545, 249, 582, 308], "age": "20-60", "gender": "F", "emotion": "sad"},
  "2": {"face_box": [666, 235, 713, 299], "age": "20-60", "gender": "M", "emotion": "neutral"},
  "3": {"face_box": [1005, 65, 1023, 88], "age": "20-60", "gender": "M", "emotion": "neutral"},
  "4": {"face_box": [298, 280, 347, 354], "age": "20-60", "gender": "F", "emotion": "anger"},
  "5": {"face_box": [927, 70, 947, 92], "age": "20-60", "gender": "M", "emotion": "surprise"},
  "6": {"face_box": [850, 56, 869, 83], "age": "20-60", "gender": "M", "emotion": "neutral"}
}

Bar Chart Analyzer

This endpoint analyzes a given bar chart and extracts useful information such as values and definitions of each bar, chart caption and source info.

import requests
import json

YOUR_API_KEY = 'your_api_key'
HOST = 'https://api.machinetutors.com'
PORT = 8020
url = f"https://{HOST}:{PORT}/v1/image/charter"

base64_encoded_image = 'your_base64_encoded_image'
headers = {"key": YOUR_API_KEY}
payload = {"image": base64_encoded_image}
rr = requests.post(url, data=payload, headers=headers)

ret = rr.content
# parse y:
y = json.loads(ret)
image_class = y['image_class']
curl -X POST "https://api.machinetutors.com:8020/v1/image/charter" \
-H "key: YOUR_API_KEY" \
--data-raw "{"image": "your_base64_encoded_image"}"
var API_HOST = 'api.machinetutors.com';
var API_PORT = 8020;
var API_VERSION = 'v1';

var YOUR_API_KEY = 'your_api_key';
var base64_encoded_image = 'your_base64_encoded_image';

var path = 'image/charter';
var post_url = `https://${API_HOST}:{API_PORT}/${API_VERSION}/${path}`;

var post_obj = {
    url: post_url,
    type: 'POST',       // needed if using jquery < 1.9.0.
    method: 'POST',
    context: document.body,
    headers: {
        "key": YOUR_API_KEY
    },
    data: { "image": base64_encoded_image },
    dataType: "json"
}

var ajaxRequest = $.ajax(post_obj);

ajaxRequest.done((data) => {
    // console.log(`-- succ`);
    handle success
  })
  .fail((jqXHR, textStatus, errorThrown) => {
    // handle failure
  })
  .always((data) => {
    // in any case
  });

The above command returns JSON structured like this:

{
  "chart_analysis": [{"hVal": "2009", "hIndex": "[26]", "vVal": 0.6523809523809524, "vIndex": "-1", "bar_box": "[39, 560, 114, 971]", "horizontal_box": "[46, 983, 111, 1004]"},
    {"hVal": "2010", "hIndex": "[27]", "vVal": 0.9936507936507937, "vIndex": "-1", "bar_box": "[144, 345, 219, 971]", "horizontal_box": "[150, 984, 215, 1004]"},
    {"hVal": "2011", "hIndex": "[28]", "vVal": 1.0, "vIndex": "-1", "bar_box": "[249, 341, 326, 971]", "horizontal_box": "[254, 984, 314, 1004]"},
    {"hVal": "2011", "hIndex": "[28]", "vVal": 0.6825396825396826, "vIndex": "-1", "bar_box": "[352, 543, 427, 973]", "horizontal_box": "[254, 984, 314, 1004]"},
    {"hVal": "2013", "hIndex": "[30]", "vVal": 0.6111111111111112, "vIndex": "-1", "bar_box": "[459, 586, 534, 971]", "horizontal_box": "[463, 984, 527, 1004]"},
    {"hVal": "2014", "hIndex": "[31]", "vVal": 0.6841269841269841, "vIndex": "-1", "bar_box": "[560, 540, 635, 971]", "horizontal_box": "[567, 983, 633, 1005]"},
    {"hVal": "2015", "hIndex": "[32]", "vVal": 0.6349206349206349, "vIndex": "-1", "bar_box": "[665, 573, 742, 973]", "horizontal_box": "[671, 984, 736, 1004]"},
    {"hVal": "2016", "hIndex": "[33]", "vVal": 0.7888888888888889, "vIndex": "-1", "bar_box": "[770, 476, 847, 973]", "horizontal_box": "[776, 983, 840, 1005]"},
    {"hVal": "2017", "hIndex": "[34]", "vVal": 0.7111111111111111, "vIndex": "-1", "bar_box": "[873, 523, 948, 971]", "horizontal_box": "[880, 984, 945, 1004]"},
    {"hVal": "2018", "hIndex": "[35]", "vVal": 0.5841269841269842, "vIndex": "-1", "bar_box": "[978, 603, 1055, 971]", "horizontal_box": "[984, 984, 1049, 1004]"},
    {"hVal": "2019", "hIndex": "[36]", "vVal": -0.39365079365079364, "vIndex": "-1", "bar_box": "[1081, 723, 1156, 971]", "horizontal_box": "[1088, 984, 1153, 1005]"},
    {"title": "Drought Down Under"}, {"subtitle": "The Average Annual Rainfall In Australia From 2009 To In Millimeters"}, {"source": "Bureau Of Meterology"},
    {"scale": 1426.5112437810944},
    [{"color": "#fc2003", "label": "Title"}, {"color": "#fca103", "label": "Subtitle"}, {"color": "#f8fc03", "label": "Source"}, {"color": "#6bfc03", "label": "Y Values"}, {"color": "#03dbfc", "label": "X Values"}, {"color": "#0345fc", "label": "Bars"}]]
}

Icon Tagging

This endpoint returns a list of tags that defines the content of the given icon image.

import requests
import json

YOUR_API_KEY = 'your_api_key'
HOST = 'api.machinetutors.com'
PORT = 8020
url = f"https://{HOST}:{PORT}/v1/image/icon_tagging"

base64_encoded_icon_image = 'your_base64_encoded_icon_image'
headers = {"key": YOUR_API_KEY}
payload = {"image": base64_encoded_icon_image}
rr = requests.post(url, data=payload, headers=headers)

ret = rr.content
# parse y:
y = json.loads(ret)
icon_tags = y['icon_tags']
curl -X POST "https://api.machinetutors.com:8020/v1/image/icon_tagging" \
-H "key: YOUR_API_KEY" \
--data-raw "{"image": "base64_encoded_icon_image"}"
var API_HOST = 'api.machinetutors.com';
var API_PORT = 8020;
var API_VERSION = 'v1';

var YOUR_API_KEY = 'your_api_key';
var base64_encoded_icon_image = 'base64_encoded_icon_image';

var path = 'image/icon_tagging';
var post_url = `https://${API_HOST}:{API_PORT}/${API_VERSION}/${path}`;

var post_obj = {
    url: post_url,
    type: 'POST',       // needed if using jquery < 1.9.0.
    method: 'POST',
    context: document.body,
    headers: {
        "key": YOUR_API_KEY
    },
    data: { "image": base64_encoded_icon_image },
    dataType: "json"
}

var ajaxRequest = $.ajax(post_obj);

ajaxRequest.done((data) => {
    // console.log(`-- succ`);
    handle success
  })
  .fail((jqXHR, textStatus, errorThrown) => {
    // handle failure
  })
  .always((data) => {
    // in any case
  });

The above command returns JSON structured like this:

{
  "icon_tags": ["currency", "finance", "money", "bank", "coin", "business"]
}

MT Audio API

MT Audio API has several models to analyze audio data.

All audio end points expect base64 encoded data in the body of the request with the keyword audio.

Alternatively, you can also give url of an audio in the header of the request with the keyword url.

Tagging

This endpoint returns a dictionary of tags with associated probability for each tag that defines the content of the given audio.

import requests
import json

YOUR_API_KEY = 'your_api_key'
HOST = 'api.machinetutors.com'
PORT = 8020
url = f"https://{HOST}:{PORT}/v1/audio/tagging"

base64_encoded_audio = 'your_base64_encoded_audio'
headers = {"key": YOUR_API_KEY}
payload = {"audio": base64_encoded_audio}
rr = requests.post(url, data=payload, headers=headers)

ret = rr.content
# parse y:
y = json.loads(ret)
audio_tags = y['audio_tags']
curl -X POST "https://api.machinetutors.com:8020/v1/audio/tagging" \
-H "key: YOUR_API_KEY" \
--data-raw "{"audio": "your_base64_encoded_audio"}"
var API_HOST = 'api.machinetutors.com';
var API_PORT = 8020;
var API_VERSION = 'v1';

var YOUR_API_KEY = 'your_api_key';
var base64_encoded_audio = 'your_base64_encoded_audio';

var path = 'audio/tagging';
var post_url = `https://${API_HOST}:{API_PORT}/${API_VERSION}/${path}`;

var post_obj = {
    url: post_url,
    type: 'POST',       // needed if using jquery < 1.9.0.
    method: 'POST',
    context: document.body,
    headers: {
        "key": YOUR_API_KEY
    },
    data: { "audio": base64_encoded_audio },
    dataType: "json"
}

var ajaxRequest = $.ajax(post_obj);

ajaxRequest.done((data) => {
    // console.log(`-- succ`);
    handle success
  })
  .fail((jqXHR, textStatus, errorThrown) => {
    // handle failure
  })
  .always((data) => {
    // in any case
  });

The above command returns JSON structured like this:

{
  "audio_tags": {
    "Breathing": "0.07020457",
    "Gasp": "0.01991755",
    "Inside, small room": "0.019466694",
    "Music": "0.010942534",
    "Sigh": "0.23969577",
    "Snoring": "0.06476523",
    "Snort": "0.039491646",
    "Sound effect": "0.017498633",
    "Speech": "0.013258014",
    "Wheeze": "0.03056742"
  }
}

Sound Event Detection

This endpoint returns a json which has key image with base64 encoded plot for the events in the given audio.

import requests
import json

YOUR_API_KEY = 'your_api_key'
HOST = 'api.machinetutors.com'
PORT = 8020
url = f"https://{HOST}:{PORT}/v1/audio/sound_event_detection"

base64_encoded_audio = 'your_base64_encoded_audio'
headers = {"key": YOUR_API_KEY}
payload = {"audio": base64_encoded_audio}
rr = requests.post(url, data=payload, headers=headers)

ret = rr.content
# parse y:
y = json.loads(ret)
event_plot = y['image']
curl -X POST "https://api.machinetutors.com:8020/v1/audio/sound_event_detection" \
-H "key: YOUR_API_KEY" \
--data-raw "{"audio": "your_base64_encoded_audio"}"
var API_HOST = 'api.machinetutors.com';
var API_PORT = 8020;
var API_VERSION = 'v1';

var YOUR_API_KEY = 'your_api_key';
var base64_encoded_audio = 'your_base64_encoded_audio';

var path = 'audio/sound_evet_detection';
var post_url = `https://${API_HOST}:{API_PORT}/${API_VERSION}/${path}`;

var post_obj = {
    url: post_url,
    type: 'POST',       // needed if using jquery < 1.9.0.
    method: 'POST',
    context: document.body,
    headers: {
        "key": YOUR_API_KEY
    },
    data: { "audio": base64_encoded_audio },
    dataType: "json"
}

var ajaxRequest = $.ajax(post_obj);

ajaxRequest.done((data) => {
    // console.log(`-- succ`);
    handle success
  })
  .fail((jqXHR, textStatus, errorThrown) => {
    // handle failure
  })
  .always((data) => {
    // in any case
  });

The above command returns JSON structured like this:

{
  "image_encoded": True,
  "image": "base64_string_of_the_plot"
}

Plot of the events over time in the given audio

Audio Retrieval

With this end point you can retrieve audio files from Librispeech dev-clean data set by giving a textual query. The returned dictionary includes information for the retrieved audio files.

import requests
import json

YOUR_API_KEY = 'your_api_key'
HOST = 'api.machinetutors.com'
PORT = 8020
url = f"https://{HOST}:{PORT}/v1/audio/retrieval"

your_query = "Mister Quilter" # this your query text for instance, memory, love, romance.
headers = {"key": YOUR_API_KEY}
payload = {"query": your_query}
rr = requests.post(url, data=payload, headers=headers)

ret = rr.content
# parse y:
y = json.loads(ret)
results = y['result']
curl -X POST "https://api.machinetutors.com:8020/v1/audio/retrieval" \
-H "key: YOUR_API_KEY" \
--data-raw "{"query": "your query"}"
var API_HOST = 'api.machinetutors.com';
var API_PORT = 8020;
var API_VERSION = 'v1';

var YOUR_API_KEY = 'your_api_key';

var path = 'audio/retrieval';
var post_url = `https://${API_HOST}:{API_PORT}/${API_VERSION}/${path}`;

var query_text = 'Mister Quilter'
var post_obj = {
    url: post_url,
    type: 'POST',       // needed if using jquery < 1.9.0.
    method: 'POST',
    context: document.body,
    headers: {
        "key": YOUR_API_KEY
    },
    data: { "query": query_text },
    dataType: "json"
}

var ajaxRequest = $.ajax(post_obj);

ajaxRequest.done((data) => {
    // console.log(`-- succ`);
    handle success
  })
  .fail((jqXHR, textStatus, errorThrown) => {
    // handle failure
  })
  .always((data) => {
    // in any case
  });

The above command returns JSON structured like this:

{'result': [{'book': 'Reviews',
             'chapter': "A 'Jolly' Art Critic",
             'id': 0,
             'link': '1272/128104/1272-128104-0000.flac',
             'pos': '0.53-1.29',
             'reader': '1272'},
            {'book': 'Reviews',
             'chapter': "A 'Jolly' Art Critic",
             'id': 1,
             'link': '1272/128104/1272-128104-0006.flac',
             'pos': '2.25-3.16',
             'reader': '1272'},
            {'book': 'Reviews',
             'chapter': "A 'Jolly' Art Critic",
             'id': 2,
             'link': '1272/128104/1272-128104-0013.flac',
             'pos': '0.49-1.24',
             'reader': '1272'},
            {'book': 'Reviews',
             'chapter': "A 'Jolly' Art Critic",
             'id': 3,
             'link': '1272/128104/1272-128104-0001.flac',
             'pos': '1.08-1.75',
             'reader': '1272'}],
 'success': 1}

Here book is where the utterance occur, chapter is the chapter of the book, id is just an enumeration, reader is the reader id by Librespeech convention, Link is relative path to the audio file in the Librespeech/dev-clean folder

Errors

The MT API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The requested method is hidden for administrators only.
404 Not Found -- The specified endpoint could not be found.
405 Method Not Allowed -- You tried to access the API with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
429 Too Many Requests -- You're sending too many requests too fast!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Changelog

Version 1.0.0

May 19, 2021