Getting Started

Welcome

API Torch provides endpoints for common computer vision tasks and is the easiest way to get started building, training, and deploying deep learning models.

Prerequisites

# install API Torch client via pip or requirements.txt
# $ echo "apitorch" >> requirements.txt
# $ pip install -r requirements.txt

# or install directly
# $ pip install apitorch

# Shell commands show up here. You can copy/paste this into your system terminal.

Having a background in programming is helpful but is not required. Commands that start with curl listed under the shell code tab can be run on any computer with an internet connection.

If you are using a Mac, you can run curl commands using the built-in Terminal app.
If you are using Windows, you can install curl here and use your command prompt (cmd.exe). You may also try out a more powerful command prompt alternative by installing Cygwin.
If you are using Linux, you can run curl commands using the built-in terminal.

Generate an API Key

API Torch uses API keys to authenticate requests. You can find your API key on your Account page. If you don't have an account, you may create a free account here. API Torch provides a generous free tier and does not require a credit card to sign up.

Be sure to keep your API keys secure.

Make your first request

from apitorch.ping import ping_api

response = ping_api()
assert response == True

# Note the trailing colon `:` (delimits username/password in basic auth, sets a blank password)
curl "https://www.apitorch.com/api/ping" \
  -u "YOUR_API_KEY:"

Sample response:

{
  "object": "ping",
  "message": "ok"
}

Send a request to /api/ping to test that your API key is working.

Authentication uses HTTP Basic Auth, with the username set to an API key and the password left blank.

You should see a JSON response that looks like:

{ "object": "ping", "message": "ok" }

If you received an error, it's likely due to an incorrect API key. Please check your request and try again.

Training Sets

Training sets organize groups of labeled images and can be used to train image classifiers.

The training set object

Example training set object:

{
  "object": "training_set",
  "id": 294,
  "description": "Distinguishes between different breed of zebra",
  "name": "Detect Zebra",
  "url": "https://www.apitorch.com/training-sets/294"
}

Attributes


`object` `string` "training_set"


`id` `number` Unique identifier for the training set.


`description` `string` Description of the training set.


`labels` `string[]` Array of strings representing the labels in the dataset.


`name` `string` Name of the training set.


`url` `string` Canonical URL for the training set.

List training sets

from apitorch.training_set import list_training_sets

training_sets = list_training_sets()

# list training sets
curl -u "YOUR_API_KEY:" \
  https://www.apitorch.com/api/training-sets

Example response:

{
  "object": "list",
  "data": [
    {
      "object": "training_set",
      "id": 294,
      "description": "Distinguishes between different breed of zebra",
      "name": "Zebra Breeds",
      "url": "https://www.apitorch.com/training-sets/294/zebra-breeds"
    },
    {
      "object": "training_set",
      "id": 419,
      "description": "Dataset of 7,000 images of original 151 pokemon.",
      "name": "Pokemon-151",
      "url": "https://www.apitorch.com/training-sets/419/pokemon-151"
    }
  ]
}

Returns a list of training sets you have created.

Endpoint

GET /api/training-sets

Returns


`object` `string` "list"


`data` `training_set[]` Array of training set objects.

Upload an image

# Upload a local file
curl -u "YOUR_API_KEY:" -F "image=@filename" \
  https://www.apitorch.com/api/training-set/:id/:label/image

# Upload via remote URL
curl -u "YOUR_API_KEY:" -F "image_url=https://www.nme.com/wp-content/uploads/2017/12/Philip-Seymour-Hoffman-Mimi-ODonnell.jpg" \
  https://www.apitorch.com/api/training-set/:id/:label/image

from apitorch.training_set import upload_image

training_set_id = 42
label = 'image_label'

# Upload a local file
response = upload_image(training_set_id, label,
                        label, image='/path/to/local/file.jpg')

# Upload a remote file
response = upload_image(training_set_id, label, 
                        image_url='https://www.nme.com/wp-content/uploads/2017/12/Philip-Seymour-Hoffman-Mimi-ODonnell.jpg')

Sample response:

{
  "object":"training_image",
  "id":"ti_654668c7afc766034e7e74d76694392a6869f7ce",
  "message":"Image added to training set."
}

Upload a training image to a training set via a local file or an image URL. Training images can be found on the web under Training Sets and downloaded programmatically using the download images API call.

Endpoint

POST /api/training-set/:id/:label/image

Parameters


`id` `number` The ID of the training set that this image will belong to.


`label` `string` The name of the label that this image will belong to.

POST data

One of image_url or image must be specified.


`image_url` `string` Remote URL of image to upload.


`image` `file` Local image file to upload.

Returns


`object` `string` "training_image"


`id` `string` Unique identifier of the training image that was uploaded.


`message` `string` Human-readable message describing the result of the API call.

Delete an image

curl -u "YOUR_API_KEY:" -X "DELETE" \
  https://www.apitorch.com/api/training-image/:image_id

from apitorch.training_image import delete_image

image_id = '690bdc0955061ffb486d81d679bd83b8c071342d'

response = delete_image(image_id)

Sample response:

{
  "object":"training_image",
  "id":"ti_690bdc0955061ffb486d81d679bd83b8c071342d",
  "message":"Image deleted."
}

Delete a training image from a training set based on its ID.

Endpoint

DELETE /api/training-image/:image_id

Parameters


`image_id` `string` The ID of the image to delete.

Returns


`object` `string` "training_image"


`id` `string` Unique identifier of the training image that was deleted.


`message` `string` Human-readable message describing the result of the API call.

Download images

from apitorch.training_set import download_images

training_set_id = 42
destination = Path('./training-images')

download_images(training_set_id, destination)

curl -u "YOUR_API_KEY:" \
  https://www.apitorch.com/api/training-set/:id/images

Sample response:

{
  "object": "list",
  "training_set_id": 42,
  "training_set_slug": "detect-zebra",
  "training_set_url": "https://www.apitorch.com/training-sets/42/detect-zebra",
  "data": [
    {
      "object": "training_label",
      "label": "mountain_zebra",
      "images": [
        {
          "filename": "d97d10521dfcv73127e5032714d2c7399b118.jpg",
          "url": "https://images.apitorch.com/d9/7d/10521dfcv73127e5032714d2c7399b118?X-Amz-Header=a0b1c2d3e4f5000",
        },
        {
          "filename": "c6cc28d21fa600f5ee615ee74cb775e595b60e2a.jpg",
          "url": "https://images.apitorch.com/c6/cc/28d21fa600f5ee615ee74cb775e595b60e2a?X-Amz-Header=6049cc5546f6f90",
        },
      ]
    },
    {
      "object": "training_label",
      "label": "maneless_zebra",
      "images": []
    }
  ]
}

Returns all labels and images for a training set. This can be used to sync down a new training set to a Jupyter/Colab notebook. Image URLs are signed and are valid for the current day.

Endpoint

GET /api/training-set/:id/images

Parameters


`id` `number` Unique identifier of the training set containing the images to download.

Returns


`object` `string` "list"


`training_set_slug` `string` Slug of the training set.


`training_set_id` `number` Unique identifier for the training set.


`data` `training_label[]` An array of training_label objects.

The training_label object


`object` `string` "training_label"


`label` `string` The name of the label formatted using snake_case.


`images` `training_image[]` An array of training_image objects.

The training_image object


`filename` `string` A filename which uniquely represents the current training image.


`url` `string` A signed URL which can be used to download the training image.

Image Classifiers

Image classifiers represent computer vision endpoints that perform deep learning inference on images.

For a list of publicly available image classifiers, see here. To perform inference on an image using an image classifier, see image classification.

The classifier object

Example classifier object:

{
  "object": "classifier",
  "id": 70,
  "description": "Classifies input image into `work_safe`, `not_work_safe`",
  "name": "Work Safe",
  "return_values": [
    [true, "Image is safe for work"],
    [false, "Image is not safe for work"]
  ]
}

Attributes


`object` `string` "classifier"


`id` `string` Unique identifier for the image classifier.


`description` `string` Short text describing what the classifier does.


`name` `string` Human-readable name of the image classifier.


`return_values` `array` Array of possible values returned when calling the image classifier.


`slug` `string` Slugified version of the classifier name; for use in a URL.

List classifiers

from apitorch.classifier import list_classifiers

classifiers = list_classifiers()

print(classifiers)

require 'httparty'
your_api_key = 'YOUR_API_KEY'
auth = {:username => your_api_key, :password => ""}
url = 'https://www.apitorch.com/api/classifiers'

results = HTTParty.get(url, :basic_auth => auth)

curl -u "YOUR_API_KEY:" \
  https://www.apitorch.com/api/classifiers

Sample response:

{
  "object": "list",
  "data": [
    {
      "object": "classifier",
      "id": 70,
      "description": "Classifies input image into 'work_safe' and 'not_work_safe'",
      "name": "Work Safe"
    }
  ]
}

Returns a list of classifiers that may be used for image classification.

To use one of these classifiers for inference, see classify an image.

Endpoint

GET /api/classifiers

Returns


`object` `string` "list"


`data` `classifier[]` Array of classifier objects.

Image Classification

Image classifiers perform inference on images and return results as a list of classification objects.

The classification object

Example classification object:

{
  "object": "classification",
  "id": "cls_8fc866865388aac024b6b068b0f0a728890c2559",
  "classifier": "safe-for-work",
  "label": "safe for work",
  "sentence": "Image is safe for work.",
  "confidence": "high"
}

Attributes


`object` string `classification`.
`id` string Unique identifier for this classification.
`confidence` string One of `very high`, `high`, `possible`, `low`, `very low`, `unknown`. See note on confidence values below.
`label` string The result label of this classification.

Note on confidence values
Confidence is returned as a human readable string representing a confidence bucket. The intention here is to normalize confidence values across model updates. You can still see the decimal value by passing in options[]='show-confidence-value'

Classify an image

POST /api/classify

curl -u "YOUR_API_KEY:" \
  -d "image_url=YOUR_IMAGE_URL" \
  -d "classifiers[]=safe-for-work&classifiers[]=design-score" \
  https://www.apitorch.com/api/classify

from apitorch.classifier import classify_image

response = classify_image(classifiers=['extract-text', 'safe-for-work'],
                          image_url='https://cdn.apitor.ch/baby-yoda.jpg')

Example response

{
  "object": "list",
  "id": "api_21982baf7e8dde9e9041c07c145a25b43832d5e0",
  "data": [
    {
      "object": "classification",
      "id": "cls_8fc866865388aac024b6b068b0f0a728890c2559",
      "classifier": "extract-text",
      "label": "does not contain text",
      "sentence": "Image does not contain text.",
      "value": false
    },
    {
      "object": "classification",
      "id": "cls_dca9b64c5388aac024b6b068b0f1a728890c6000",
      "classifier": "safe-for-work",
      "label": "safe for work",
      "sentence": "Image is safe for work.",
      "confidence": "high"
    }
  ]
}

This endpoint performs inference on a given image using one or more image classifiers.

Endpoint

POST /api/classify

Parameters


`classifiers` required string[] One or more classifiers that will be used to detect image contents
`image_url` required string URL of a publicly accessible (or signed) image
`options` dictionary See options below.

Options:

show_confidence_value boolean
Returns a decimal confidence value as confidence_value. Even though this field is a decimal, it's returned as a string to avoid any language-specific inconsistencies when parsing float values. Not all classifiers support a confidence value.

Returns


`object` string "list"
`id` string Unique identifier for the API call.
`data` classification[] A list of classification objects.

Feedback

Endpoints

(POST) /api/feedback/classification
(POST) /api/feedback/freeform

Feedback is an essential concept in deep learning and is one of the ways neural networks can keep improving by periodically retraining on new data.

Submitting feedback

You may submit feedback in one of two ways:

In response to an invalid classification event using feedback/classification
At will using feedback/freeform

Incorrect classification

You may submit feedback to correct the result of a classification event.

If an image classification is incorrect, you may submit a correction. The image will get added into the training images for correct_label. Over time this will provide image diversity and improve the accuracy of your model.

URL Parameters

Parameter	Description
classification_id	The `id` of the classification to correct
correct_label_id	The `id` of the label that should have been predicted by the classifier

Free-form feedback

You may send feedback to us via the API. Simply base64 encode your message and pass as a message property.

URL Parameters

Parameter	Description
message	base64 encoded message