NAV Navbar
cURL JavaScript Python Ruby

Introduction

API Endpoint

https://api.scaleapi.com/v1/

Welcome to the Scale API! You can use our API to access Scale API endpoints, which can create, access, and cancel human tasks.

Anyone can use our API! Sign up here to get started using Scale. You can also contact us for volume pricing or any inquiries.

You can also join our Slack channel here!

Client Libraries / SDKs

To install the client library, use the following command:

pip install --upgrade scaleapi
npm install scaleapi --save
gem install scaleapi

Currently we have client libraries available for the following languages:

We also have unofficial SDKs in the following languages:

Let us know if you want (or are interested in writing) a library for a language not represented here!

Authentication

To authorize, use this code:

# With curl, you can just pass the correct header with each request
curl "api_endpoint_here" \
  -u "{{ApiKey}}:"
import scaleapi

client = scaleapi.ScaleClient('{{ApiKey}}')
var scaleapi = require('scaleapi');

var client = scaleapi.ScaleClient('{{ApiKey}}');
require 'scale'

scale = Scale.new(api_key: '{{ApiKey}}')
=> #<Scale:0x007fcc1292fe88 @api_key="{{ApiKey}}", @callback_auth_key=nil, @default_request_params={:callback_url=>nil}, @logging=false>

You must replace {{ApiKey}} with your personal API key. If you sign up or log in, your API key will be automatically filled in the docs. Your test API key {{ApiKey}} is included in all the examples on this page, so you can test any example right away. Only you can see this value.

Scale uses API keys to allow access to the API. You can find your API keys on your dashboard, which you can access by logging in or signing up.

Scale expects for the API key to be included in all API requests to the server via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password. You can do this using the -u flag:

-u "{{ApiKey}}:"

Test and Live Modes

To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no “switch” for changing between modes, just use the appropriate key to perform a live or test API requests.

Requests made with test mode credentials are not completed by a human, and therefore have incorrect test responses. Requests made with live mode credentials are always completed by a human, and will incur a charge past your first 5 API requests.

Callback Authentication

If you’d like to authenticate our callbacks, we set a scale-callback-auth HTTP header on each of our callbacks. The value will be equal to your Live Callback Auth Key shown on your dashboard. If this header is not set, or it is set incorrectly, the callback is not from Scale.

Task Object

The task object represents a single task that you create with Scale and is completed by a worker.

Attributes

{
  "task_id": "576ba74eec471ff9b01557cc",
  "completed_at": "2016-06-23T09:10:02.798Z",
  "created_at": "2016-06-23T09:09:34.752Z",
  "callback_url": "http://www.example.com/callback",
  "type": "categorization",
  "status": "completed",
  "instruction": "Would you say this item is big or small?",
  "urgency": "immediate",
  "params": {
    "attachment_type": "text",
    "attachment": "car",
    "categories": [
      "big",
      "small"
    ]
  },
  "callback_succeeded": true,
  "response": {
    "category": "big"
  },
  "metadata": {}
}
Attribute Type Description
task_id string The task_id is the unique identifier for the task.
type string The type of the task. Currently, we support categorization, transcription, audiotranscription, comparison, annotation, and datacollection.
instruction string A markdown-enabled string explaining the instructions for the task. You can use markdown to show example images, give structure to your instructions, and more.
params object An object with the parameters of the task based on the type. For categorization, for example, this will include attachment_type, attachment, and categories.
urgency string A string describing the urgency of the response. One of immediate, day, or week, where immediate is a one-hour response time.
response object An object corresponding to the response once the task is completed. For categorization, it will have the attribute category, corresponding to the chosen category.
callback_url string A string of the URL that should be POSTed once the task is completed for the response data. See the Callback section for more details.
status string The status of the task, one of pending, completed, or canceled.
created_at timestamp A string of the UTC timestamp of when the task was created.
completed_at timestamp A string of the UTC timestamp of when the task was completed. This will only be filled in after it is completed.
callback_succeeded boolean A boolean stating whether or not the callback succeeded. If the callback returns with a 2xx status code, the value will be true. If the callback fails to return a 2xx status code through all retries, then the value will be false.
metadata object, default {} A set of key/value pairs that you can attach to a task object. It can be useful for storing additional information about the task in a structured format.

Metadata

Tasks objects have a metadata parameter. You can use this parameter to attach key-value data to tasks.

Metadata is useful for storing additional, structured information on an object. As an example, you could store a video’s unique identifier in your system on its content moderation categorization task. You can also use it to denote the end use case for the task, as “content moderation” or “data categorization” for example. Metadata is not used by Scale (e.g., to affect how the task is done).

Attachments

Callback example for bad attachment URL:

{
  "error": "One or more attachments could not be downloaded.",
  "attachments": [
    {
      "statusCode": 500,
      "url": "https://your-s3-bucket.s3.amazonaws.com/attachment-1.png"
    },
    {
      "statusCode": 500,
      "url": "https://your-s3-bucket.s3.amazonaws.com/attachment-2.png"
    }
  ]
}

Tasks often require a file associated with them that Scale API calls an attachment. For example, an annotation task requires an image file to show to a Scaler. These attachments are not limited to images and may also be audio, video, or pdf files, or a website, or even plain text. For all attachment types except plain text, the attachment must be specified via a URL. See the specific task documentation below for some examples.

Currently we only support fetching urls whose protocol is http or https. Make sure that the URL is a direct link to the file you wish to use as an attachment and not a document showing a preview of the file. For certain storage providers we may be able to rewrite URLs that are previews of the file you are trying to attach to the correct direct download URL.

Scale API will attempt to fetch the attachment via the URL you provide. If we do not receive an HTTP 200 response when attempting to fetch your attachment(s), we will send your callback_url an error with the bad HTTP codes we received.

Image Annotation Layers

All of these input formats have the same formatting as our responses, so passing one Scale tasks’ data to another Scale task is really easy.

// This example uses express with body-parser
var scaleapi = require('scaleapi');

var client = scaleapi.ScaleClient('{{ApiKey}}');

app.post('/polygon_task_callback_handler', function(req, res) {
  // Validate callback auth key
  ...

  var polygons = req.body.response.annotations;
  var attachment = req.body.task.params.attachment;

  client.createAnnotationTask({
    'callback_url': 'http://www.example.com/annotation_task_callback_handler',
    'instruction': 'Draw a box around each **car** and **pedestrian**',
    'attachment_type': 'image',
    'attachment': attachment,
    'objects_to_annotate': ['car', 'pedestrian'],
    'with_labels': true,
    'min_width': '30',
    'min_height': '30',
    'layers': {
      'polygons': polygons
    }
  }, (err, task) => {
      // do something with task
  });
});
# This example uses Flask
import scaleapi
from flask import request, Flask

app = Flask(__name__)

client = scaleapi.ScaleClient('{{ApiKey}}')

@app.route('/polygon_task_callback_handler', methods=['POST'])
def create_annotation_task():
  # Validate callback auth key
  ...

  polygons = request.json['response']['annotations']
  attachment = request.json['task']['params']['attachment']

  task = client.create_annotation_task(
      callback_url='http://www.example.com/annotation_task_callback_handler',
      instruction='Draw a box around each **car** and **pedestrian**',
      attachment_type='image',
      attachment=attachment,
      objects_to_annotate=['car', 'pedestrian'],
      with_labels=True,
      min_width='30',
      min_height='30',
      layers={'polygons': polygons}
  )

  # do something with the task
# This example uses Rails
require 'scale'

class ExampleController < ActionController::Base
  def initialize
    @scale = Scale.new(api_key: '{{ApiKey}}')
  end

  # This should be mapped to a POST route
  def polygon_task_callback_handler
    # Validate callback auth key
    ...

    polygons = params['response']['annotations']
    attachment = params['task']['params']['attachment']

    task = @scale.create_annotation_task({
      callback_url: 'http://www.example.com/annotation_task_callback_handler',
      instruction: 'Draw a box around each **car** and **pedestrian**',
      attachment_type: 'image',
      attachment: attachment,
      objects_to_annotate: ['car', 'pedestrian'],
      with_labels: true,
      min_width: '30',
      min_height: '30',
      layers: {polygons: polygons}
    })

    # do something with the task
  end
end

“Layers” can be used to specify existing (read-only) boxes, lines, polygons, and/or cuboids to be pre-drawn on an image.

For instance, you could specify boxes around the cars of an image, for a task that requires drawing polygons around the currently boxed cars. Or you could create a task for drawing boxes around all cars which you hadn’t already recognized.

To specify layers, you can pass an optional layers parameter in the request for annotation, lineannotation, polygonannotation, or pointannotation tasks. They can also be used in categorization tasks if the attachment_type is image.

The layers parameter can contains fields for boxes, lines, polygons, and cuboids, which are arrays of the corresponding elements. Each of these elements are specified in the same format as the responses for their respective endpoints.

Boxes

Example layers param with boxes

{
    "lines": [
        ...
    ],
    "polygons": [
        ...
    ],
    "boxes": [
        {
            "label": "car",
            "height": 97,
            "width": 147,
            "top": 229,
            "left": 300
        }
    ],
    "cuboids": [
        ...
    ]
}

Each of the boxes is specified with an object containing left, top, width, and height keys, and an optional label.

Polygons

Example layers param with polygons

{
    ...
    "polygons": [
        {
            "vertices": [
                {
                    "y": 145,
                    "x": 356
                },
                {
                    "y": 103,
                    "x": 502
                },
                {
                    "y": 264,
                    "x": 482
                }
            ],
            "label": "building"
        }
    ]
}

polygons are objects with an optional label field, and a vertices field which contains a list of objects with x and y attributes.

Lines

Example layers param with lines

{
    ...
    "lines": [
        {
            "vertices": [
                {
                    "y": 323,
                    "x": 414
                },
                {
                    "y": 164,
                    "x": 616
                },
                {
                    "y": 334,
                    "x": 776
                }
            ],
            "label" : "crosswalk",
            "spline": true
        }
    ]
}

lines are objects with an optional label field, and a vertices field which contains a list of objects with x and y attributes, similar to polygons. Additionally, line objects have an optional spline flag, which determines whether the curve used is linear (if the value is false or the param is not passed) or cardinal (if the value is true).

Cuboids

Example layers param with cuboids

{
    ...
    "cuboids": [
        {
            "vertices" : [
                {
                    "description" : "face-topleft",
                    "y" : 219.0,
                    "x" : 137.0
                },
                {
                    "description" : "face-bottomleft",
                    "y" : 318.0,
                    "x" : 137.0
                },
                {
                    "description" : "face-topright",
                    "y" : 219.0,
                    "x" : 245.0
                },
                {
                    "description" : "face-bottomright",
                    "y" : 318.0,
                    "x" : 245.0
                },
                {
                    "description" : "side-topcorner",
                    "y" : 165.0,
                    "x" : 316.0
                },
                {
                    "description" : "side-bottomcorner",
                    "y" : 264.0,
                    "x" : 316.0
                }
            ],
            "label" : "car"
        }
    ]
}

cuboids are described in a similar way as polygons or lines, but the vertices also need a description, using the following values to identify them:

Create Image Annotation Tasks

Bounding Box Annotation

curl "https://api.scaleapi.com/v1/task/annotation" \
  -u "{{ApiKey}}:" \
  -d callback_url="http://www.example.com/callback" \
  -d instruction="Draw a box around each **car** and **pedestrian**." \
  -d attachment_type=image \
  -d attachment="http://i.imgur.com/XOJbalC.jpg" \
  -d objects_to_annotate="car" \
  -d objects_to_annotate="pedestrian" \
  -d with_labels=true \
  -d min_width="30" \
  -d min_height="30"
import scaleapi

client = scaleapi.ScaleClient('{{ApiKey}}')

client.create_annotation_task(
    callback_url='http://www.example.com/callback',
    instruction='Draw a box around each **car** and **pedestrian**',
    attachment_type='image',
    attachment='http://i.imgur.com/XOJbalC.jpg',
    objects_to_annotate=['car', 'pedestrian'],
    with_labels=True,
    min_width='30',
    min_height='30'
)
var scaleapi = require('scaleapi');

var client = scaleapi.ScaleClient('{{ApiKey}}');

client.createAnnotationTask({
  'callback_url': 'http://www.example.com/callback',
  'instruction': 'Draw a box around each **car** and **pedestrian**',
  'attachment_type': 'image',
  'attachment': 'http://i.imgur.com/XOJbalC.jpg',
  'objects_to_annotate': ['car', 'pedestrian'],
  'with_labels': true,
  'min_width': '30',
  'min_height': '30'
}, (err, task) => {
    // do something with task
});
require 'scale'
scale = Scale.new(api_key: '{{ApiKey}}')

scale.create_annotation_task({
  callback_url: 'http://www.example.com/callback',
  instruction: 'Draw a box around each **car** and **pedestrian**',
  attachment_type: 'image',
  attachment: 'http://i.imgur.com/XOJbalC.jpg',
  objects_to_annotate: ['car', 'pedestrian'],
  with_labels: true,
  min_width: '30',
  min_height: '30'
})
=> #<Scale::Api::Tasks::ImageRecognition:0x007fcc11092f10 @task_id="58a6363baa9d139b20a4252f", @type="annotation", @instruction="Draw a box around each **car** and **pedestrian**", @params={"with_labels"=>true, "objects_to_annotate"=>["car", "pedestrian"], "attachment_type"=>"image", "attachment"=>"http://i.imgur.com/v4cBreD.jpg"}, @urgency="day", @response=nil, @callback_url="http://www.example.com/callback", @created_at=2017-02-16 23:31:07 UTC, @status="pending", @completed_at=nil, @callback_succeeded_at=nil, @metadata={}>

The above command returns an object structured like this:

{
  "task_id": "5774cc78b01249ab09f089dd",
  "created_at": "2016-9-03T07:38:32.368Z",
  "callback_url": "http://www.example.com/callback",
  "type": "annotation",
  "status": "pending",
  "instruction": "Draw a box around each **car** and **pedestrian**",
  "urgency": "day",
  "params": {
    "with_labels": true,
    "min_width": 30,
    "min_height": 30,
    "objects_to_annotate": [
      "car",
      "pedestrian"
    ],
    "attachment_type": "image",
    "attachment": "http://i.imgur.com/XOJbalC.jpg"
  },
  "metadata": {}
}

This endpoint creates a annotation task. In this task, one of our Scalers view the given image and draw bounding boxes around the specified objects, returning the positions and sizes of these boxes.

The required parameters for this task are callback_url, attachment, and objects_to_annotate. The callback_url is the URL which will be POSTed on task completion, and is described in more detail in the Callbacks section. The attachment is a URL to an image you’d like to be annotated.

objects_to_annotate is an array of strings describing the different types of objects you’d like annotated.

You can optionally provide additional markdown-enabled instructions via the instruction parameter.

You can also optionally set with_labels to true, which will have Scalers provide labels for each box specifying what type of object it is. The labels will be strings in the objects_to_annotate list.

It is recommended, but not required, for you to flesh out your Markdown instructions with many examples of tasks being done correctly and incorrectly.

You may also provide min_width and min_height parameters, which will tell Scalers to only annotate objects whose bounding boxes are of dimension at least min_width x min_height.

If successful, Scale will immediately return the generated task object, of which you should at least store the task_id.

HTTP Request

POST https://api.scaleapi.com/v1/task/annotation

Parameters

Parameter Type Description
callback_url string The full url (including the scheme http:// or https://) of the callback when the task is completed. See the Callback section for more details about callbacks.
objects_to_annotate [string] An array of strings describing which objects you’d like bounding boxes to be drawn around. Each string should be singular and self-descriptive (ex: “cat”, “street sign”, “potato”). You may include at most 6 objects.
attachment string A URL to the image you’d like to be annotated with bounding boxes.
with_labels (optional, default false) boolean Specifies whether you’d like labels for each bounding box in the response. Each label will be a member of the objects_to_annotate array.
min_height (optional) integer, default 0 The minimum height in pixels of the bounding boxes you’d like to be made.
min_width (optional) integer, default 0 The minimum width in pixels of the bounding boxes you’d like to be made.
urgency (optional, default day) string A string describing the urgency of the response. One of immediate, day, or week, where immediate is a six hour response time.
instruction (optional) string A markdown-enabled string explaining how to draw the bounding boxes. You can use markdown to show example images, give structure to your instructions, and more.
attachment_type (optional, default image) string Describes what type of file the attachment is. We currently only support image for the annotation endpoint.
metadata (optional, default {}) object A set of key/value pairs that you can attach to a task object. It can be useful for storing additional information about the task in a structured format.
layers (optional) object A set of existing read-only objects to be pre-drawn on the image. See the Layers section for more detail.

Callback Format

Example callback body sent on completion

{
  "response": {
    "annotations": [
      {
        "left": 123,
        "top": 10,
        "width": 121,
        "height": 39,
        "label": "car"
      },
      {
        "left": 82,
        "top": 56,
        "width": 64,
        "height": 30,
        "label": "pedestrian"
      },
      { ... },
      { ... }
    ]
  },
  "task_id": "5774cc78b01249ab09f089dd",
  "task": {
    // populated task for convenience
    ...
  }
}

The response object, which is part of the callback POST request and permanently stored as part of the task object, will have either an error field or an annotations field.

If the annotation was completed successfully, the annotations field will contain an array of annotations. Each annotation will have the following values:

If the attachment was invalid, the error will be detailed in the error field.

Point Annotation

curl "https://api.scaleapi.com/v1/task/pointannotation" \
  -u "{{ApiKey}}:" \
  -d callback_url="http://www.example.com/callback" \
  -d instruction="Draw a point on every **headlight** and **brakelight** of a car in the image." \
  -d attachment_type=image \
  -d attachment="http://i.imgur.com/XOJbalC.jpg" \
  -d objects_to_annotate="headlight" \
  -d objects_to_annotate="brakelight" \
  -d with_labels=true
import scaleapi

client = scaleapi.ScaleClient('{{ApiKey}}')

client.create_pointannotation_task(
    callback_url='http://www.example.com/callback',
    instruction='Draw a point on every **headlight** and **brakelight** of a car in the image.',
    attachment_type='image',
    attachment='http://i.imgur.com/XOJbalC.jpg',
    objects_to_annotate=['headlight', 'brakelight'],
    with_labels=True
)
var scaleapi = require('scaleapi');

var client = scaleapi.ScaleClient('{{ApiKey}}');

client.createPointannotationTask({
  'callback_url': 'http://www.example.com/callback',
  'instruction': 'Draw a point on every **headlight** and **brakelight** of a car in the image.',
  'attachment_type': 'image',
  'attachment': 'http://i.imgur.com/XOJbalC.jpg',
  'objects_to_annotate': ['headlight', 'brakelight'],
  'with_labels': true
}, (err, task) => {
    // do something with task
});
require 'scale'
scale = Scale.new(api_key: '{{ApiKey}}')

scale.create_pointannotation_task({
  callback_url: 'http://www.example.com/callback',
  instruction: 'Draw a point on every **headlight** and **brakelight** of a car in the image.',
  attachment_type: 'image',
  attachment: 'http://i.imgur.com/XOJbalC.jpg',
  objects_to_annotate: ['headlight', 'brakelight'],
  with_labels: true
})
=> #<Scale::Api::Tasks::Pointannotation:0x007fcc11092f10 @task_id="58a6363baa9d139b20a4252f", @type="pointannotation", @instruction="Draw a point on every **headlight** and **brakelight** of a car in the image.", @params={"with_labels"=>true, "objects_to_annotate"=>["headlight", "brakelight"], "attachment_type"=>"image", "attachment"=>"http://i.imgur.com/XOJbalC.jpg"}, @urgency="day", @response=nil, @callback_url="http://www.example.com/callback", @created_at=2017-02-16 23:31:07 UTC, @status="pending", @completed_at=nil, @callback_succeeded_at=nil, @metadata={}>

The above command returns an object structured like this:

{
  "task_id": "5774cc78b01249ab09f089dd",
  "created_at": "2016-9-03T07:38:32.368Z",
  "callback_url": "http://www.example.com/callback",
  "type": "pointannotation",
  "status": "pending",
  "instruction": "Draw a point on every **headlight** and **brakelight** of a car in the image.",
  "urgency": "day",
  "params": {
    "with_labels": true,
    "objects_to_annotate": [
      "headlight",
      "brakelight"
    ],
    "attachment_type": "image",
    "attachment": "http://i.imgur.com/XOJbalC.jpg"
  },
  "metadata": {}
}

This endpoint creates a pointannotation task. In this task, one of our Scalers view the given image and draw points at the specified locations, returning the locations of these points.

The required parameters for this task are callback_url, attachment, and objects_to_annotate. The callback_url is the URL which will be POSTed on task completion, and is described in more detail in the Callbacks section. The attachment is a URL to an image you’d like to be annotated.

objects_to_annotate is an array of strings describing the different types of objects you’d like annotated. You may include at most 6 objects in the objects_to_annotate parameter.

You can optionally provide additional markdown-enabled instructions via the instruction parameter.

You can also optionally set with_labels to true, which will have Scalers provide labels for each point specifying what type of object it is. The labels will belong to the objects_to_annotate list.

If successful, Scale will immediately return the generated task object, of which you should at least store the task_id.

HTTP Request

POST https://api.scaleapi.com/v1/task/pointannotation

Parameters

Parameter Type Description
callback_url string The full url (including the scheme http:// or https://) of the callback when the task is completed. See the Callback section for more details about callbacks.
objects_to_annotate [string] An array of strings describing which objects you’d like points to be drawn on. Each string should be singular and self-descriptive (ex: “cat”, “street sign”, “potato”). You may include at most 6 objects.
attachment string A URL to the image you’d like to be annotated with points.
with_labels (optional, default false) boolean Specifies whether you’d like labels for each point in the response. Each label will be a member of the objects_to_annotate array.
urgency (optional, default day) string A string describing the urgency of the response. One of immediate, day, or week, where immediate is a 6 hour response time.
instruction (optional) string A markdown-enabled string explaining how to draw the points. You can use markdown to show example images, give structure to your instructions, and more.
attachment_type (optional, default image) string Describes what type of file the attachment is. We currently only support image for the point annotation endpoint.
metadata (optional, default {}) object A set of key/value pairs that you can attach to a task object. It can be useful for storing additional information about the task in a structured format.
layers (optional) object A set of existing read-only objects to be pre-drawn on the image. See the Layers section for more detail.

Callback Format

Example callback body sent on completion

{
  "response": {
    "annotations": [
      {
        "label": "headlight",
        "x": 123,
        "y": 10
      },
      {
        "label": "headlight",
        "x": 140,
        "y": 49
      },
      {
        "label": "brakelight",
        "x": 67,
        "y": 34
      }
    ]
  },
  "task_id": "5774cc78b01249ab09f089dd",
  "task": {
    // task inlined for convenience
    ...
  }
}

The response field, which is part of the callback POST request and permanently stored as part of the task object, will contain either an annotations field or an error field.

The annotations field will contain an array of point annotations. Each annotation will have the following values:

If the attachment was invalid, the error will be detailed in the error field.

Line Annotation

curl "https://api.scaleapi.com/v1/task/lineannotation" \
  -u "{{ApiKey}}:" \
  -d callback_url="http://www.example.com/callback" \
  -d instruction="Annotate lines over all of the **lane lines** in the street-level image." \
  -d attachment_type=image \
  -d attachment="http://i.imgur.com/XOJbalC.jpg" \
  -d objects_to_annotate="solid line" \
  -d objects_to_annotate="dashed line" \
  -d with_labels=true
import scaleapi

client = scaleapi.ScaleClient('{{ApiKey}}')

client.create_lineannotation_task(
    callback_url='http://www.example.com/callback',
    instruction='Annotate lines over all of the **lane lines** in the street-level image.',
    attachment_type='image',
    attachment='http://i.imgur.com/XOJbalC.jpg',
    objects_to_annotate=['solid line', 'dashed line'],
    with_labels=True
)
var scaleapi = require('scaleapi');

var client = scaleapi.ScaleClient('{{ApiKey}}');

client.createLineannotationTask({
  'callback_url': 'http://www.example.com/callback',
  'instruction': 'Annotate lines over all of the **lane lines** in the street-level image.',
  'attachment_type': 'image',
  'attachment': 'http://i.imgur.com/XOJbalC.jpg',
  'objects_to_annotate': ['solid line', 'dashed line'],
  'with_labels': true
}, (err, task) => {
    // do something with task
});
require 'scale'
scale = Scale.new(api_key: '{{ApiKey}}')

scale.create_lineannotation_task({
  callback_url: 'http://www.example.com/callback',
  instruction: 'Annotate lines over all of the **lane lines** in the street-level image.',
  attachment_type: 'image',
  attachment: 'http://i.imgur.com/XOJbalC.jpg',
  objects_to_annotate: ['solid line', 'dashed line'],
  with_labels: true
})
=> #<Scale::Api::Tasks::Lineannotation:0x007fcc11092f10 @task_id="58a6363baa9d139b20a4252f", @type="lineannotation", @instruction="Annotate lines over all of the **lane lines** in the street-level image.", @params={"with_labels"=>true, "objects_to_annotate"=>["solid line", "dashed line"], "attachment_type"=>"image", "attachment"=>"http://i.imgur.com/XOJbalC.jpg"}, @urgency="day", @response=nil, @callback_url="http://www.example.com/callback", @created_at=2017-02-16 23:31:07 UTC, @status="pending", @completed_at=nil, @metadata={}>

The above command returns an object structured like this:

{
  "task_id": "5774cc78b01249ab09f089dd",
  "created_at": "2016-9-03T07:38:32.368Z",
  "callback_url": "http://www.example.com/callback",
  "type": "lineannotation",
  "status": "pending",
  "instruction": "Annotate lines over all of the **lane lines** in the street-level image.",
  "urgency": "day",
  "params": {
    "with_labels": true,
    "objects_to_annotate": [
      "solid line",
      "dashed line"
    ],
    "attachment_type": "image",
    "attachment": "http://i.imgur.com/XOJbalC.jpg"
  },
  "metadata": {}
}

This endpoint creates a lineannotation task. In this task, one of our Scalers view the given image and draw segmented lines along each object, returning the vertices of these segmented lines.

The required parameters for this task are callback_url, attachment, and objects_to_annotate. The callback_url is the URL which will be POSTed on task completion, and is described in more detail in the Callbacks section. The attachment is a URL to an image you’d like to be annotated.

objects_to_annotate is an array of strings describing the different types of objects you’d like annotated.

You can optionally provide additional markdown-enabled instructions via the instruction parameter.

You can also optionally set with_labels to true, which will have Scalers provide labels for each segmented line specifying what type of object it is. The labels will belong to the objects_to_annotate list.

If you’d prefer splines as opposed to segmented lines, then you may specify the splines flag as true.

You can also optionally set min_vertices and/or max_vertices which specify the minimum and maximum number of vertices that you would want on a line. Note the range is inclusive of both bounds. For example, if min_vertices is 2 and max_vertices is 2, then Scale will only return line segments.

If successful, Scale will immediately return the generated task object, of which you should at least store the task_id.

HTTP Request

POST https://api.scaleapi.com/v1/task/lineannotation

Parameters

Parameter Type Description
callback_url string The full url (including the scheme http:// or https://) of the callback when the task is completed. See the Callback section for more details about callbacks.
objects_to_annotate [string] An array of strings describing which objects you’d like segmented lines to be drawn along. Each string should be singular and self-descriptive (ex: “lane line”, “crop line”). You may include at most 3 objects.
attachment string A URL to the image you’d like to be annotated with segmented lines.
with_labels (optional, default false) boolean Specifies whether you’d like labels for each segmented line in the response. Each label will be a member of the objects_to_annotate array.
urgency (optional, default day) string A string describing the urgency of the response. One of immediate, day, or week, where immediate is a 6 hour response time.
instruction (optional) string A markdown-enabled string explaining how to draw the segmented lines. You can use markdown to show example images, give structure to your instructions, and more.
attachment_type (optional, default image) string Describes what type of file the attachment is. We currently only support image for the line annotation endpoint.
splines (optional, default false) boolean Specifies whether or not you’d like your lines drawn as cardinal splines instead of segmented lines
min_vertices (optional, default 1) number An optional parameter defining the minimum number of vertices in a valid line annotation for your request.
max_vertices (optional, default null) number An optional parameter defining the maximum number of vertices in a valid line annotation for your request. Must be at least min_vertices.
metadata (optional, default {}) object A set of key/value pairs that you can attach to a task object. It can be useful for storing additional information about the task in a structured format.
layers (optional) object A set of existing read-only objects to be pre-drawn on the image. See the Layers section for more detail.

Callback Format

Example callback body sent on completion

{
  "response": {
    "annotations": [
      {
        "label": "solid line",
        "vertices": [
            {
                "x": 123,
                "y": 10
            },
            {
                "x": 140,
                "y": 49
            },
            {
                "x": 67,
                "y": 34
            }
        ]
      },
      { ... },
      { ... }
    ]
  },
  "task_id": "5774cc78b01249ab09f089dd",
  "task": {
    // populated task for convenience
    ...
  }
}

The response field, which is part of the callback POST request and permanently stored as part of the task object, will contain either an annotations field or an error field.

The annotations field will contain an array of annotations. Each annotation will have the following values:

If the attachment was invalid, the error will be detailed in the error field.

Polygon Annotation

curl "https://api.scaleapi.com/v1/task/polygonannotation" \
  -u "{{ApiKey}}:" \
  -d callback_url="http://www.example.com/callback" \
  -d instruction="Draw a tight polygon around every **car** in the image." \
  -d attachment_type=image \
  -d attachment="http://i.imgur.com/XOJbalC.jpg" \
  -d objects_to_annotate="car" \
  -d objects_to_annotate="truck" \
  -d with_labels=true
import scaleapi

client = scaleapi.ScaleClient('{{ApiKey}}')

client.create_polygonannotation_task(
    callback_url='http://www.example.com/callback',
    instruction='Draw a tight polygon around every **car** in the image.',
    attachment_type='image',
    attachment='http://i.imgur.com/XOJbalC.jpg',
    objects_to_annotate=['car', 'truck'],
    with_labels=True
)
var scaleapi = require('scaleapi');

var client = scaleapi.ScaleClient('{{ApiKey}}');

client.createPolygonannotationTask({
  'callback_url': 'http://www.example.com/callback',
  'instruction': 'Draw a tight polygon around every **car** in the image.',
  'attachment_type': 'image',
  'attachment': 'http://i.imgur.com/XOJbalC.jpg',
  'objects_to_annotate': ['car', 'truck'],
  'with_labels': true
}, (err, task) => {
    // do something with task
});
require 'scale'
scale = Scale.new(api_key: '{{ApiKey}}')

scale.create_polygonannotation_task({
  callback_url: 'http://www.example.com/callback',
  instruction: 'Draw a tight polygon around every **car** in the image.',
  attachment_type: 'image',
  attachment: 'http://i.imgur.com/XOJbalC.jpg',
  objects_to_annotate: ['car', 'truck'],
  with_labels: true
})
=> #<Scale::Api::Tasks::Polygonannotation:0x007fcc11092f10 @task_id="58a6363baa9d139b20a4252f", @type="polygonannotation", @instruction="Draw a tight polygon around every **car** in the image.", @params={"with_labels"=>true, "objects_to_annotate"=>["car", "truck"], "attachment_type"=>"image", "attachment"=>"http://i.imgur.com/XOJbalC.jpg"}, @urgency="day", @response=nil, @callback_url="http://www.example.com/callback", @created_at=2017-02-16 23:31:07 UTC, @status="pending", @completed_at=nil, @callback_succeeded_at=nil, @metadata={}>

The above command returns an object structured like this:

{
  "task_id": "5774cc78b01249ab09f089dd",
  "created_at": "2016-9-03T07:38:32.368Z",
  "callback_url": "http://www.example.com/callback",
  "type": "polygonannotation",
  "status": "pending",
  "instruction": "Draw a tight polygon around every **car** in the image.",
  "urgency": "day",
  "params": {
    "with_labels": true,
    "objects_to_annotate": [
      "car",
      "truck"
    ],
    "attachment_type": "image",
    "attachment": "http://i.imgur.com/XOJbalC.jpg"
  },
  "metadata": {}
}

This endpoint creates a polygonannotation task. In this task, one of our Scalers view the given image and draw bounding polygons around the specified objects, returning the vertices of these polygons.

The required parameters for this task are callback_url, attachment, and objects_to_annotate. The callback_url is the URL which will be POSTed on task completion, and is described in more detail in the Callbacks section. The attachment is a URL to an image you’d like to be annotated.

objects_to_annotate is an array of strings describing the different types of objects you’d like annotated.

You can optionally provide additional markdown-enabled instructions via the instruction parameter.

You can also optionally set with_labels to true, which will have Scalers provide labels for each polygon specifying what type of object it is. The labels will belong to the objects_to_annotate list.

You can also optionally set min_vertices and/or max_vertices which specify the minimum and maximum number of vertices that you’d like on a polygon. Note the range is inclusive of both bounds. For example, if min_vertices is 3 and max_vertices is 5, then Scale will only return triangles, quadrilaterals, and pentagons.

If successful, Scale will immediately return the generated task object, of which you should at least store the task_id.

HTTP Request

POST https://api.scaleapi.com/v1/task/polygonannotation

Parameters

Parameter Type Description
callback_url string The full url (including the scheme http:// or https://) of the callback when the task is completed. See the Callback section for more details about callbacks.
objects_to_annotate [string] An array of strings describing which objects you’d like bounding polygons to be drawn around. Each string should be singular and self-descriptive (ex: “cat”, “street sign”, “potato”). You may include at most 6 objects.
attachment string A URL to the image you’d like to be annotated with bounding polygons.
with_labels (optional, default false) boolean Specifies whether you’d like labels for each bounding polygon in the response. Each label will be a member of the objects_to_annotate array.
urgency (optional, default day) string A string describing the urgency of the response. One of immediate, day, or week, where immediate is a 6 hour response time.
instruction (optional) string A markdown-enabled string explaining how to draw the bounding polygons. You can use markdown to show example images, give structure to your instructions, and more.
attachment_type (optional, default image) string Describes what type of file the attachment is. We currently only support image for the polygon annotation endpoint.
min_vertices (optional, default 1) number An optional parameter defining the minimum number of vertices in a valid polygon annotation for your request.
max_vertices (optional, default null) number An optional parameter defining the maximum number of vertices in a valid polygon annotation for your request. Must be at least min_vertices.
metadata (optional, default {}) object A set of key/value pairs that you can attach to a task object. It can be useful for storing additional information about the task in a structured format.
layers (optional) object A set of existing read-only objects to be pre-drawn on the image. See the Layers section for more detail.

Callback Format

Example callback body sent on completion

{
  "response": {
    "annotations": [
      {
        "label": "car",
        "vertices": [
            {
                "x": 123,
                "y": 10
            },
            {
                "x": 140,
                "y": 49
            },
            {
                "x": 67,
                "y": 34
            }
        ]
      },
      { ... },
      { ... }
    ]
  },
  "task_id": "5774cc78b01249ab09f089dd",
  "task": {
    // task inlined for convenience
    ...
  }
}

The response field, which is part of the callback POST request and permanently stored as part of the task object, will contain either an annotations field or an error field.

The annotations field will contain an array of annotations. Each annotation will have the following values:

If the attachment was invalid, the error will be detailed in the error field.

Semantic Segmentation

curl "https://api.scaleapi.com/v1/task/segmentannotation" \
  -u "{{ApiKey}}:" \
  -d callback_url="http://www.example.com/callback" \
  -d instruction="Please segment the image using the given labels." \
  -d attachment_type=image \
  -d attachment="http://i.imgur.com/XOJbalC.jpg" \
  -d labels="vehicle" \
  -d labels="background" \
  -d labels="road" \
  -d labels="vegetation" \
  -d labels="lane marking" \
  -d allow_unlabeled=false
import scaleapi

client = scaleapi.ScaleClient('{{ApiKey}}')

client.create_segmentannotation_task(
    callback_url='http://www.example.com/callback',
    instruction='Please segment the image using the given labels.',
    attachment_type='image',
    attachment='http://i.imgur.com/XOJbalC.jpg',
    labels=['vehicle', 'background', 'road', 'vegetation', 'lane marking'],
    allow_unlabeled=False
)
var scaleapi = require('scaleapi');

var client = scaleapi.ScaleClient('{{ApiKey}}');

client.createSegmentannotationTask({
  callback_url: 'http://www.example.com/callback',
  instruction: 'Please segment the image using the given labels.',
  attachment_type: 'image',
  attachment: 'http://i.imgur.com/XOJbalC.jpg',
  labels: ['vehicle', 'background', 'road', 'vegetation', 'lane marking'],
  allow_unlabeled: false
}, (err, task) => {
    // do something with task
});
require 'scale'
scale = Scale.new(api_key: '{{ApiKey}}')

scale.create_segmentannotation_task({
  callback_url: 'http://www.example.com/callback',
  instruction: 'Please segment the image using the given labels.',
  attachment_type: 'image',
  attachment: 'http://i.imgur.com/XOJbalC.jpg',
  labels: ['vehicle', 'background', 'road', 'vegetation', 'lane marking'],
  allow_unlabeled: false
})
=> #<Scale::Api::Tasks::Segmentannotation:0x007fcc11092f10 @task_id="58a6363baa9d139b20a4252f", @type="segmentannotation", @instruction="Please segment the image using the given labels.", @params={"allow_unlabeled"=>false, "objects_to_annotate"=>['vehicle', 'background', 'road', 'vegetation', 'lane marking'], "attachment_type"=>"image", "attachment"=>"http://i.imgur.com/XOJbalC.jpg"}, @urgency="day", @response=nil, @callback_url="http://www.example.com/callback", @created_at=2017-02-16 23:31:07 UTC, @status="pending", @completed_at=nil, @callback_succeeded_at=nil, @metadata={}>

The above command returns an object structured like this:

{
  "task_id": "5774cc78b01249ab09f089dd",
  "created_at": "2016-9-03T07:38:32.368Z",
  "callback_url": "http://www.example.com/callback",
  "type": "segmentannotation",
  "status": "pending",
  "instruction": "Please segment the image using the given labels.",
  "urgency": "day",
  "params": {
    "allow_unlabeled": false,
    "objects_to_annotate": [
      "vehicle",
      "background",
      "road",
      "vegetation",
      "lane marking"
    ],
    "attachment_type": "image",
    "attachment": "http://i.imgur.com/XOJbalC.jpg"
  },
  "metadata": {}
}

This endpoint creates a segmentannotation task. In this task, one of our Scalers view the given image and classify every pixel of the image according to the labels provided. You will get a full semantic, pixel-wise, dense segmentation of the image.

The required parameters for this task are callback_url, attachment, and labels. The callback_url is the URL which will be POSTed on task completion, and is described in more detail in the Callbacks section. The attachment is a URL to an image you’d like to be segmented.

labels is an array of strings describing the different types of objects you’d like to be used to segment the image.

You can optionally provide additional markdown-enabled instructions via the instruction parameter.

You can also optionally set allow_unlabeled to true, which will allow the existence of unlabeled pixels in the segmentation response - otherwise, all pixels in the image will be classified (in which case it’s important that there are labels for everything in the image, to avoid misclassification).

The response you will receive will be a series of images where each pixel’s value corresponds to the label, either via a numerical index or a color mapping. You will also get separate masks for each label for convenience.

If successful, Scale will immediately return the generated task object, of which you should at least store the task_id.

HTTP Request

POST https://api.scaleapi.com/v1/task/segmentannotation

Parameters

Parameter Type Description
callback_url string The full url (including the scheme http:// or https://) of the callback when the task is completed. See the Callback section for more details about callbacks.
labels [string] An array of strings describing the different types of objects you’d like to be used to segment the image. Each string should be singular and descriptive (ex: car, background, pole). You may include at most 50 objects.
attachment string A URL to the image you’d like to be segmented.
allow_unlabeled (optional, default false) boolean Specifies whether you’ll allow unlabeled pixels in the segmentation. If left with the default value of false, all pixels in the image will be classified using the labels you provided.
urgency (optional, default day) string A string describing the urgency of the response. One of immediate, day, or week, where immediate is a 6 hour response time.
instruction (optional) string A markdown-enabled string explaining how carry out the semantic segmentation. You can use markdown to show example images, give structure to your instructions, and more.
attachment_type (optional, default image) string Describes what type of file the attachment is. We currently only support image for the semantic segmentation endpoint.
metadata (optional, default {}) object A set of key/value pairs that you can attach to a task object. It can be useful for storing additional information about the task in a structured format.

Callback Format

Example callback body sent on completion

{
  "task": {
    // task inlined for convenience
    ...
  },
  "response": {
    "annotations": {
      "unlabeled": null,
      "labeled": {
        "lane marking": "https://scaleapi-attachments.s3.amazonaws.com/3f184900-6809-11e7-bb22-c346fd2b0658",
        "vehicle": "https://scaleapi-attachments.s3-ap-northeast-1.amazonaws.com/b7566ef0-8119-11e7-ac39-7d56f40a5f60",
        "road": "https://scaleapi-attachments.s3-ap-northeast-1.amazonaws.com/b756bd10-8119-11e7-ac39-7d56f40a5f60",
        "vegetation": "https://scaleapi-attachments.s3-ap-northeast-1.amazonaws.com/b756bd11-8119-11e7-ac39-7d56f40a5f60",
        "background": "https://scaleapi-attachments.s3-ap-northeast-1.amazonaws.com/b7573240-8119-11e7-ac39-7d56f40a5f60"
      },
      "combined": {
        "image": "https://scaleapi-attachments.s3-ap-northeast-1.amazonaws.com/b7573241-8119-11e7-ac39-7d56f40a5f60",
        "indexedImage": "https://scaleapi-attachments.s3-ap-northeast-1.amazonaws.com/ba9a9d70-8119-11e7-ac39-7d56f40a5f60"
      }
    },
    "labelMapping": {
      "lane marking": {
        "color": "#9e3fff",
        "index": 5
      },
      "vehicle": {
        "color": "#8000ff",
        "index": 4
      },
      "background": {
        "color": "#00ffff",
        "index": 3
      },
      "road": {
        "color": "#80ff00",
        "index": 2
      },
      "vegetation": {
        "color": "#ff0000",
        "index": 1
      }
    },
    "instances": {}
  },
  "task_id": "598e0da3e8068e06002d9407"
}

The response field, which is part of the callback POST request and permanently stored as part of the task object, will contain a labelMapping and an annotations field.

labelMapping is a dictionary where the keys are each label name, and the value is an object with the index and color used to represent each label in the response images.

annotations is an object that contains URLs of PNG images describing the segmentation result in different ways:

Create Categorization Task

curl "https://api.scaleapi.com/v1/task/categorization" \
  -u "{{ApiKey}}:" \
  -d callback_url="http://www.example.com/callback" \
  -d instruction="Is this company public or private?" \
  -d attachment_type=website \
  -d attachment="http://www.google.com/" \
  -d categories=public \
  -d categories=private
import scaleapi

client = scaleapi.ScaleClient('{{ApiKey}}')

client.create_categorization_task(
    callback_url='http://www.example.com/callback',
    instruction='Is this company public or private?',
    attachment_type='website',
    attachment='http://www.google.com/',
    categories=['public', 'private']
)

var scaleapi = require('scaleapi');

var client = scaleapi.ScaleClient('{{ApiKey}}');

client.createCategorizationTask({
  'callback_url': 'http://www.example.com/callback',
  'instruction': 'Is this company public or private?',
  'attachment_type': 'website',
  'attachment': 'http://www.google.com/',
  'categories': ['public', 'private']
}, (err, task) => {
    // do something with task
});
require 'scale'
scale = Scale.new(api_key: '{{ApiKey}}')

scale.create_categorization_task({
  callback_url: 'http://www.example.com/callback',
  instruction: 'Is this company public or private?',
  attachment_type: 'website',
  attachment: 'https://www.google.com',
  categories: ['public', 'private']
})
=> #<Scale::Api::Tasks::Categorization:0x007fcc11819bf8 @task_id="58a63795aa9d139b20a42535", @type="categorization", @instruction="Is this company public or private?", @params={"allow_multiple"=>false, "categories"=>["public", "private"], "attachment"=>"https://www.google.com", "attachment_type"=>"website"}, @urgency="day", @response=nil, @callback_url="http://www.example.com/callback", @created_at=2017-02-16 23:36:53 UTC, @status="pending", @completed_at=nil, @callback_succeeded_at=nil, @metadata={}>

The above command returns an object structured like this:

{
  "task_id": "576ba74eec471ff9b01557cc",
  "created_at": "2016-06-23T09:09:34.752Z",
  "callback_url": "http://www.example.com/callback",
  "type": "categorization",
  "status": "pending",
  "instruction": "Is this company public or private?",
  "urgency": "day",
  "params": {
    "attachment_type": "website",
    "attachment": "http://www.google.com/",
    "categories": [
      "public",
      "private"
    ]
  },
  "metadata": {}
}

This endpoint creates a categorization task. In this task, one of our workers will view the attachment and choose a category for it according to the instruction. You may allow multiple categories to be chosen by setting allow_multiple to true. Example use cases are spam detection, copyright detection, product categorization, etc.

This task involves a markdown-enabled instruction about how to make the categorization, an attachment of what you’d like to categorize, an attachment_type, and finally a list of categories.

There is an optional category_ids parameter, which you can use to impose an id system over the categories. The format of this parameter should be a dictionary, where the keys are the ids (as strings), and then the values are the category values provided in categories. An example is:

"category_ids": { "123": "Blue Cross", "124": "Red Cross" }

If successful, Scale will immediately return the generated task object, of which you should at least store the task_id.

The parameters attachment_type, attachment, categories, and category_ids (optional) will be stored in the params object of the constructed task object.

HTTP Request

POST https://api.scaleapi.com/v1/task/categorization

Parameters

Parameter Type Description
callback_url string The full url (including the scheme http:// or https://) of the callback when the task is completed. See the Callback section for more details about callbacks.
instruction string A markdown-enabled string explaining how to categorize the item. You can use markdown to show example images, give structure to your instructions, and more.
attachment_type string One of text, image, video, audio, website, or pdf. Describes what type of file the attachment is.
attachment string The attachment to be categorized. If attachment_type is text, then it should be plaintext. Otherwise, it should be a URL pointing to the attachment.
categories [string] An array of strings for the categories which you’d like the object to be sorted between.
urgency (optional, default day) string A string describing the urgency of the response. One of immediate, day, or week, where immediate is a 6 hour response time.
category_ids (optional) dictionary An optional dictionary where the keys are the optional ids, and the values are the category values provided in categories.
allow_multiple (optional) boolean Default is false. Determines whether you allow multiple categories to be chosen for the attachment
metadata (optional, default {}) object A set of key/value pairs that you can attach to a task object. It can be useful for storing additional information about the task in a structured format.
layers (optional) object A set of existing read-only boxes, lines, polygons and/or cuboids to be pre-drawn on the image attachment (this only works if attachment_type is image). This can be useful e.g. to draw a bounding box indicating which object to categorize within the image. See the Layers section in image annotation for more detail.

Callback Format

If allow_multiple is false, the callback body will look like:

{
  "response": {
    "category": "one_of_the_categories"
  },
  "task_id": "576ba74eec471ff9b01557cc",
  "task": {
    // populated task for convenience
    ...
  }
}

If allow_multiple is true, the callback body will look like:

{
  "response": {
    "category": ["some_of", "the_categories"]
  },
  "task_id": "576ba74eec471ff9b01557cc",
  "task": {
    // populated task for convenience
    ...
  }
}

Example if category_ids is provided and allow_multiple is false

{
  "response": {
    "category": "Blue Cross",
    "category_id": "123"
  },
  "task_id": "576ba74eec471ff9b01557cc",
  "task": {
    // populated task for convenience
    ...
  }
}

Example if category_ids is provided and allow_multiple is true


{
  "response": {
    "category": ["Blue Cross", "Red Cross"],
    "category_id": ["123", "124"]
  },
  "task_id": "576ba74eec471ff9b01557cc",
  "task": {
    // populated task for convenience
    ...
  }
}

The response object, which is part of the callback POST request and permanently stored as part of the task object, will have a category field and potentially a category_id field.

If allow_multiple is false, then the value will be a string equal to one of the original categories.

If allow_multiple is true, the value will be an array of categories, each one being one of the original categories.

If category_ids was provided, there will be another field category_id corresponding to the given id of the chosen category/categories.

Create Comparison Task

curl "https://api.scaleapi.com/v1/task/comparison" \
  -u "{{ApiKey}}:" \
  -d callback_url="http://www.example.com/callback" \
  -d instruction="Do the objects in these images have the same pattern?" \
  -d attachment_type=image \
  -d attachments="http://i.ebayimg.com/00/\$T2eC16dHJGwFFZKjy5ZjBRfNyMC4Ig~~_32.JPG" \
  -d attachments="http://images.wisegeek.com/checkered-tablecloth.jpg" \
  -d choices="yes" \
  -d choices="no"
import scaleapi

client = scaleapi.ScaleClient('{{ApiKey}}')

client.create_comparison_task(
    callback_url='http://www.example.com/callback',
    instruction='Do the objects in these images have the same pattern?',
    attachment_type='image',
    attachments=[
        'http://i.ebayimg.com/00/$T2eC16dHJGwFFZKjy5ZjBRfNyMC4Ig~~_32.JPG',
        'http://images.wisegeek.com/checkered-tablecloth.jpg'
    ],
    choices=['yes', 'no']
)
var scaleapi = require('scaleapi');

var client = scaleapi.ScaleClient('{{ApiKey}}');

client.createComparisonTask({
  'callback_url': 'http://www.example.com/callback',
  'instruction': 'Do the objects in these images have the same pattern?',
  'attachment_type': 'image',
  'attachments': [
    'http://i.ebayimg.com/00/$T2eC16dHJGwFFZKjy5ZjBRfNyMC4Ig~~_32.JPG',
    'http://images.wisegeek.com/checkered-tablecloth.jpg'
  ],
  'choices': ['yes', 'no']
}, (err, task) => {
    // do something with task
});
require 'scale'
scale = Scale.new(api_key: '{{ApiKey}}')

scale.create_comparison_task({
  callback_url: 'http://www.example.com/callback',
  instruction: 'Do the objects in these images have the same pattern?',
  attachments: [
    'http://i.ebayimg.com/00/$T2eC16dHJGwFFZKjy5ZjBRfNyMC4Ig~~_32.JPG',
    'http://images.wisegeek.com/checkered-tablecloth.jpg'
  ],
  attachment_type: 'image',
  choices: ['yes', 'no']
})
=> #<Scale::Api::Tasks::Comparison:0x007fcc109636e0 @task_id="58a6378aaa9d139b20a42532", @type="comparison", @instruction="Do the objects in these images have the same pattern?", @params={"choices"=>["yes", "no"], "attachment_type"=>"image", "attachments"=>["http://i.ebayimg.com/00/$T2eC16dHJGwFFZKjy5ZjBRfNyMC4Ig~~_32.JPG", "http://images.wisegeek.com/checkered-tablecloth.jpg"]}, @urgency="day", @response=nil, @callback_url="http://www.example.com/callback", @created_at=2017-02-16 23:36:42 UTC, @status="pending", @completed_at=nil, @callback_succeeded_at=nil, @metadata={}>

The above command returns an object structured like this:

{
  "task_id": "5774cc78b02487c424f089dd",
  "created_at": "2016-06-30T07:38:32.368Z",
  "callback_url": "http://www.example.com/callback",
  "type": "comparison",
  "status": "pending",
  "instruction": "Do the objects in these images have the same pattern?",
  "urgency": "day",
  "params": {
    "choices": [
      "yes",
      "no"
    ],
    "attachment_type": "image",
    "attachments": [
      "http://i.ebayimg.com/00/$T2eC16dHJGwFFZKjy5ZjBRfNyMC4Ig~~_32.JPG",
      "http://images.wisegeek.com/checkered-tablecloth.jpg"
    ]
  },
  "metadata": {}
}

This endpoint creates a comparison task. In this task, one of our workers view the given attachments and do any comparison requested.

This task involves a markdown-enabled instruction, an array of attachments, and an attachment_type.

At least of the fields or choices parameters must specified for the data to be returned. choices is an array of strings from which the worker to choose, and fields is useful for free-text response.

fields is a dictionary where the keys are the keys you’d like the results to be returned under, and values are the descriptions you’d like to show the human worker.

If successful, Scale will immediately return the generated task object, of which you should store the task_id.

The parameters attachment_type, attachments, choices, and fields will be stored in the params object of the constructed task object.

HTTP Request

POST https://api.scaleapi.com/v1/task/comparison

Parameters

Parameter Type Description
callback_url string The full url (including the scheme http:// or https://) of the callback when the task is completed. See the Callback section for more details about callbacks.
instruction string A markdown-enabled string explaining how to compare the attachments. You can use markdown to show example images, give structure to your instructions, and more.
attachment_type string One of text, image, video, audio, website, or pdf. Describes what type of file the attachments are.
attachments array An array of attachments to compare. If attachment_type is text, then each attachment should be plaintext. Otherwise, they should be URLs pointing to the attachments.
urgency (optional, default day) string A string describing the urgency of the response. One of immediate, day, or week, where immediate is a 6 hour response time.
fields (optional) dictionary A dictionary corresponding to the fields to be recorded. Keys are the keys you’d like the fields to be returned under, and values are descriptions to be shown to human workers.
choices (optional) [string] An array of strings for the choices to be given to the worker. One of choices or fields must be specified.
metadata (optional, default {}) object A set of key/value pairs that you can attach to a task object. It can be useful for storing additional information about the task in a structured format.

Callback Format

Example callback body:

{
  "response": {
    "choice": "yes",
    "fields": {
      "difference": "The patterns are identical."
    }
  },
  "task_id": "576ba74eec471ff9b01557cc",
  "task": {
    // populated task for convenience
    ...
  }
}

The response object, which is part of the callback POST request and permanently stored as part of the task object, will have a fields field and/or choice field depending on the original request.

If your original call provided choices, choice will be one of the original choices.

If your original call provided fields, fields will have keys corresponding to the keys you provided in the parameters, with values the transcribed value.

Create Data Collection Task

curl "https://api.scaleapi.com/v1/task/datacollection" \
  -u "{{ApiKey}}:" \
  -d callback_url="http://www.example.com/callback" \
  -d instruction="Find the URL for the hiring page for the company with attached website." \
  -d attachment_type=website \
  -d attachment="https://www.scaleapi.com/" \
  -d fields[hiring_page]="Hiring Page URL"
import scaleapi

client = scaleapi.ScaleClient('{{ApiKey}}')

client.create_datacollection_task(
    callback_url='http://www.example.com/callback',
    instruction='Find the URL for the hiring page for the company with attached website.',
    attachment_type='website',
    attachment='https://www.scaleapi.com',
    fields={
        'hiring_page': 'Hiring Page URL'
    }
)
var scaleapi = require('scaleapi');

var client = scaleapi.ScaleClient('{{ApiKey}}');

client.createDatacollectionTask({
  'callback_url': 'http://www.example.com/callback',
  'instruction': 'Find the URL for the hiring page for the company with attached website.',
  'attachment_type': 'website',
  'attachment': 'https://www.scaleapi.com/',
  'fields': {
    'hiring_page': 'Hiring Page URL'
  }
}, (err, task) => {
    // do something with task
});
require 'scale'
scale = Scale.new(api_key: '{{ApiKey}}')

scale.create_datacollection_task({
  callback_url: 'http://www.example.com/callback',
  instruction: 'Find the URL for the hiring page for the company with attached website.',
  attachment: 'https://www.scaleapi.com/',
  attachment_type: 'website',
  fields: {
    hiring_page: 'Hiring Page URL'
  }
})
=> #<Scale::Api::Tasks::Datacollection:0x007fcc109b7a38 @task_id="58a63649aa9d139b20a42531", @type="datacollection", @instruction="Find the URL for the hiring page for the company with attached website.", @params={"fields"=>{"hiring_page"=>"Hiring Page URL"}, "attachment"=>"https://www.scaleapi.com/", "attachment_type"=>"website"}, @urgency="day", @response=nil, @callback_url="http://www.example.com/callback", @created_at=2017-02-16 23:31:21 UTC, @status="pending", @completed_at=nil, @callback_succeeded_at=nil, @metadata={}>

The above command returns an object structured like this:

{
  "task_id": "576de9dc1ea5f917d56fc2a0",
  "created_at": "2016-06-25T02:18:04.248Z",
  "callback_url": "http://www.example.com/callback",
  "type": "datacollection",
  "status": "pending",
  "instruction": "Find the URL for the hiring page for the company with attached website.",
  "urgency": "day",
  "params": {
    "fields": {
      "hiring_page": "Hiring Page URL"
    },
    "attachment": "http://www.scaleapi.com/",
    "attachment_type": "website"
  },
  "metadata": {}
}

This endpoint creates a datacollection task. In this task, one of our workers will try to find some information through the internet, following the instructions that you provide. Example use cases could be finding the product page of a particular product on Amazon, or trying to find the email of a particular person given their name and position.

This task involves a markdown-enabled instruction about how to find the information, an attachment detailing the particular data you’d like to collect, an attachment_type, and a fields parameter, which describes all of the different pieces of information you’d like captured.

The fields parameter is a dictionary where the keys are the keys you’d like the results to be returned under, and values are the descriptions you’d like to show the human Scaler.

If successful, Scale will immediately return the generated task object, of which you should at least store the task_id.

The parameters attachment_type, attachment, and fields will be stored in the params object of the constructed task object.

HTTP Request

POST https://api.scaleapi.com/v1/task/datacollection

Parameters

Parameter Type Description
callback_url string The full url (including the scheme http:// or https://) of the callback when the task is completed. See the Callback section for more details about callbacks.
instruction string A markdown-enabled string explaining how to collect the data. You can use markdown to show example images, give structure to your instructions, and more.
attachment_type string One of text, image, or website. Describes what type of file the attachment is.
attachment string The attachment detailing the data to be collected. If attachment_type is text, then it should be plaintext. Otherwise, it should be a URL pointing to the attachment.
fields dictionary A dictionary corresponding to the fields of information to be collected. Keys are the keys you’d like the fields to be returned under, and values are descriptions to be shown to human workers.
urgency (optional, default day) string A string describing the urgency of the response. One of immediate, day, or week, where immediate is a 6 hour response time.
metadata (optional, default {}) object A set of key/value pairs that you can attach to a task object. It can be useful for storing additional information about the task in a structured format.

Callback Format

Example callback body

{
  "response": {
    "fields": {
      "hiring_page": "Hiring Page URL"
    }
  },
  "task_id": "576ba74eec471ff9b01557cc",
  "task": {
    // populated task for convenience
    ...
  }
}

The response object, which is part of the callback POST request and permanently stored as part of the task object, will have a fields object and time_spent_in_seconds, an integer.

fields will have keys corresponding to the keys you provided in the parameters, with values the transcribed value.

time_spent_in_seconds represents the time spent looking for the data you specified, not including the time spent in our review processes.

Create OCR Transcription Task

curl "https://api.scaleapi.com/v1/task/transcription" \
  -u "{{ApiKey}}:" \
  -d callback_url="http://www.example.com/callback" \
  -d instruction="Transcribe the given fields." \
  -d attachment_type=website \
  -d attachment="http://news.ycombinator.com/" \
  -d fields[title]="Title of Webpage" \
  -d fields[top_result]="Title of the top result"
import scaleapi

client = scaleapi.ScaleClient('{{ApiKey}}')

client.create_transcription_task(
    callback_url='http://www.example.com/callback',
    instruction='Transcribe the given fields.',
    attachment_type='website',
    attachment='http://news.ycombinator.com/',
    fields={
        'title': 'Title of Webpage',
        'top_result': 'Title of the top result'
    }
)
var scaleapi = require('scaleapi');

var client = scaleapi.ScaleClient('{{ApiKey}}');

client.createTranscriptionTask({
  'callback_url': 'http://www.example.com/callback',
  'instruction': 'Transcribe the given fields.',
  'attachment_type': 'website',
  'attachment': 'http://news.ycombinator.com/',
  'fields': {
    'title': 'Title of Webpage',
    'top_result': 'Title of the top result'
  }
}, (err, task) => {
    // do something with task
});
require 'scale'
scale = Scale.new(api_key: '{{ApiKey}}')

scale.create_transcription_task({
  callback_url: 'http://www.example.com/callback',
  instruction: 'Transcribe the given fields.',
  attachment_type: 'website',
  attachment: 'http://news.ycombinator.com/',
  fields: {
    title: 'Title of Webpage',
    top_result: 'Title of the top result'
  }
})

=> #<Scale::Api::Tasks::Transcription:0x007fcc1098d828 @task_id="58a6361eaa9d139b20a4252d", @type="transcription", @instruction="Transcribe the given fields.", @params={"fields"=>{"top_result"=>"Title of the top result", "title"=>"Title of Webpage"}, "attachment"=>"http://news.ycombinator.com/", "attachment_type"=>"website"}, @urgency="day", @response=nil, @callback_url="http://www.example.com/callback", @created_at=2017-02-16 23:30:38 UTC, @status="pending", @completed_at=nil, @callback_succeeded_at=nil, @metadata={}>

The above command returns an object structured like this:

{
  "task_id": "576de9dc1ea5f917d56fc2a0",
  "created_at": "2016-06-25T02:18:04.248Z",
  "callback_url": "http://www.example.com/callback",
  "type": "transcription",
  "status": "pending",
  "instruction": "Transcribe the given fields.",
  "urgency": "day",
  "params": {
    "fields": {
      "title": "Title of Webpage",
      "top_result": "Title of the top result"
    },
    "attachment": "http://news.ycombinator.com/",
    "attachment_type": "website"
  },
  "metadata": {}
}

This endpoint creates a transcription task. In this task, one of our workers will read an attachment and arbitrarily transcribe any information you’d like. Example use cases could be transcribing information from PDFs, manually scraping a web page for information, etc.

This task involves a markdown-enabled instruction about how to transcribe the attachment, an attachment of what you’d like to transcribe, an attachment_type, fields, and repeatable_fields.

fields is a dictionary which describes items you’d like transcribed for the attachment. Examples are phone numbers, names, etc. repeatable_fields is a dictionary which describes items which you’d like transcribed for the attachment which appear in the attachment multiple times. Examples are the row-by-row items of an invoice or purchase order.

In addition, we now support choices for repeatable_fields where you can specify an array of choices for the repeatable field.

At least one of fields or repeatable_fields is required. Both fields and repeatable_fields are dictionaries where the keys are the identifiers you’d like the results to be returned using, and values are plaintext descriptions you’d like to show the Scaler as they complete the task.

If successful, Scale will immediately return the generated task object, of which you should at least store the task_id.

The parameters attachment_type, attachment, fields, and repeatable_fields will be stored in the params object of the constructed task object.

HTTP Request

POST https://api.scaleapi.com/v1/task/transcription

Parameters

Parameter Type Description
callback_url string The full url (including the scheme http:// or https://) of the callback when the task is completed. See the Callback section for more details about callbacks.
instruction string A markdown-enabled string explaining how to transcribe the attachment. You can use markdown to show example images, give structure to your instructions, and more.
attachment_type string One of image, pdf, or website. Describes what type of file the attachment is.
attachment string The attachment to be transcribed. If attachment_type is text, then it should be plaintext. Otherwise, it should be a URL pointing to the attachment.
fields (optional if using repeatable_fields) object A dictionary corresponding to the fields to be transcribed. Keys are the identifiers you’d like the fields to be returned using, and values are descriptions to be shown to the Scalers as they complete the task.
repeatable_fields (optional if using fields) object If your task requires a transcription of items which might be repeated within the attachment, such as rows of an invoice, then this dictionary describes those fields. With the addition of choices, there are now two acceptable formats. The first acceptable format is the same format as fields to generate repeatable text fields. The second acceptable format is a dictionary with keys of description (identifiers) and choices (the list of choices for that input). In addition, for repeatable_fields with the same format as fields, our internal task model will represent each repeatable field as a dictionary object with key description to the original value.
urgency (optional, default day) string A string describing the urgency of the response. One of immediate, day, or week, where immediate is a 6 hour response time.
metadata (optional, default {}) object A set of key/value pairs that you can attach to a task object. It can be useful for storing additional information about the task in a structured format.

Callback Format

Example callback response sent on completion with fields

{
  "response": {
    "fields": {
      "title": "Some Title",
      "top_result": "The Top Result or Something"
    }
  },
  "task_id": "5774cc78b01249ab09f089dd",
  "task": {
    // populated task for convenience
    ...
  }
}

Example callback response sent on completion with repeatable_fields

{
  "response": {
    "repeatable_fields": [
      {
        "description": "Espresso",
        "amount": "10.00"
      },
      {
        "description": "Ice Cream",
        "amount": "9.99"
      }
    ]
  },
  "task_id": "5774cc78b01249ab09f089dd",
  "task": {
    // populated task for convenience
    ...
  }
}

The response object, which is part of the callback POST request and permanently stored as part of the task object, will have a fields field.

fields will have keys corresponding to the keys you provided in the parameters, with values equal to the transcribed value.

If you requested repeatable_fields, repeatable_fields in the response will be an array of such dictionaries, with keys corresponding to the keys you provided in the repeatable_fields parameter, and values corresponding to the transcribed value. Each element of the array will correspond to one transcribed value in the attachment.

Create Audio Transcription Task

curl "https://api.scaleapi.com/v1/task/audiotranscription" \
  -u "{{ApiKey}}:" \
  -d callback_url="http://www.example.com/callback" \
  -d attachment_type=audio \
  -d attachment="https://storage.googleapis.com/deepmind-media/pixie/knowing-what-to-say/second-list/speaker-3.wav" \
  -d verbatim=false \
  -d phrases=avocado \
  -d phrases=stone
import scaleapi

client = scaleapi.ScaleClient('{{ApiKey}}')

client.create_audiotranscription_task(
    callback_url='http://www.example.com/callback',
    attachment_type='audio',
    attachment='https://storage.googleapis.com/deepmind-media/pixie/knowing-what-to-say/second-list/speaker-3.wav',
    verbatim=False,
    phrases=['avocado', 'stone']
)
var scaleapi = require('scaleapi');

var client = scaleapi.ScaleClient('{{ApiKey}}');

client.createAudiotranscriptionTask({
  'callback_url': 'http://www.example.com/callback',
  'attachment_type': 'audio',
  'attachment': 'https://storage.googleapis.com/deepmind-media/pixie/knowing-what-to-say/second-list/speaker-3.wav',
  'verbatim': false,
  'phrases': ['avocado', 'stone']
}, (err, task) => {
    // do something with task
});
require 'scale'
scale = Scale.new(api_key: '{{ApiKey}}')

scale.create_audiotranscription_task({
  callback_url: 'http://www.example.com/callback',
  attachment_type: 'audio',
  attachment: 'https://storage.googleapis.com/deepmind-media/pixie/knowing-what-to-say/second-list/speaker-3.wav',
  verbatim: false,
  phrases: ['avocado', 'stone']
})

=> #<Scale::Api::Tasks::AudioTranscription:0x007fcc109b7d58 @task_id="58a6341eaa9d139b20a4252b", @type="audiotranscription", @instruction="Please transcribe the attached audio file.", @params={"verbatim"=>false, "attachment_type"=>"audio", "attachment"=>"https://storage.googleapis.com/deepmind-media/pixie/knowing-what-to-say/second-list/speaker-3.wav"}, @urgency="day", @response=nil, @callback_url="http://www.example.com/callback", @created_at=2017-02-16 23:22:06 UTC, @status="pending", @completed_at=nil, @callback_succeeded_at=nil, @metadata={}>

The above command returns an object structured like this:

{
  "task_id": "582bfe0ee5d51cda4e903f4a",
  "created_at": "2016-11-16T06:34:54.884Z",
  "callback_url": "http://www.example.com/callback",
  "type": "audiotranscription",
  "status": "pending",
  "urgency": "day",
  "instruction": "Please transcribe the attached audio file.",
  "params": {
    "verbatim": false,
    "attachment_type": "audio",
    "attachment": "https://storage.googleapis.com/deepmind-media/pixie/knowing-what-to-say/second-list/speaker-3.wav",
    "phrases": ["avocado", "stone"]
  },
  "is_test": true,
  "metadata": {}
}

This endpoint creates an audiotranscription task. In this task, we will transcribe the speech from the audio file you specify into plaintext.

You are required to provide a URL to the audio file as the attachment. The attachment_type must be audio.

If you have more specific instructions about how to transcribe the audio file, you may optionally provide a markdown-enabled instruction.

You may optionally specify verbatim to true or false, determining whether non-words such as “um” and “hm” will be included in the transcript. The default is false.

You may also optionally specify phrases, a list of strings containing words and phrases as “hints” so that the audio transcription is more likely to recognize them. This can be used to improve the accuracy for specific words and phrases, or to add additional words to the vocabulary for the transcription.

If successful, Scale will immediately return the generated task object, of which you should at least store the task_id.

The parameters attachment_type, attachment, verbatim, and phrases will be stored in the params object of the constructed task object.

HTTP Request

POST https://api.scaleapi.com/v1/task/audiotranscription

Parameters

Parameter Type Description
callback_url string The full url (including the scheme http:// or https://) of the callback when the task is completed. See the Callback section for more details about callbacks.
instruction (optional) string An markdown-enabled string specifying any special instructions for the audio transcription. You can use markdown to show examples, give structure to your instructions, and more.
attachment string A URL pointing to the audio file attachment.
attachment_type (optional, default audio) string Describes what type of file the attachment is. Only accepts audio.
verbatim (optional, default false) boolean Specifies whether or not to include non-words (ex: “um”, “hm”) in the transcript.
phrases (optional) [string] A list of strings containing words and phrases “hints” so that the audio transcription is more likely to recognize them. This can be used to improve the accuracy for specific words and phrases, or to add additional words to the vocabulary for the transcription.
urgency (optional, default day) string A string describing the urgency of the response. One of immediate, day, or week, where immediate is a 6 hour response time.
metadata (optional, default {}) object A set of key/value pairs that you can attach to a task object. It can be useful for storing additional information about the task in a structured format.
skip_human_transcription (optional, default false) boolean Specifies whether or not to skip human transcription. Skipping human transcription will result in a very fast response and lower price, but will likely have a lower final quality.

Callback Format

Example callback sent on completion

{
  "response": {
    "transcript": "The avocado is a pear-shaped fruit with leathery skin, smooth edible flesh, and a large stone.",
    "duration": 5.106188,
    "alignment": [
      { "word": "The", "start": 0.3, "end": 0.37, "confidence": 0.9 },
      { "word": "avocado", "start": 0.37, "end": 0.79, "confidence": 0.9 },
      { "word": "is", "start": 0.79, "end": 0.94, "confidence": 0.9 },
      { "word": "a", "start": 0.94, "end": 1, "confidence": 0.9 },
      { "word": "pear", "start": 1, "end": 1.3, "confidence": 0.3 },
      { "word": "shaped", "start": 1.3, "end": 1.59, "confidence": 0.3 },
      { "word": "fruit", "start": 1.59, "end": 1.8, "confidence": 0.9 },
      { "word": "with", "start": 1.81, "end": 2.01, "confidence": 0.9 },
      { "word": "leathery", "start": 2.01, "end": 2.37, "confidence": 0.9 },
      { "word": "skin", "start": 2.37, "end": 2.82, "confidence": 0.9 },
      { "word": "smooth", "start": 2.85, "end": 3.11, "confidence": 0.9 },
      { "word": "edible", "start": 3.19, "end": 3.53, "confidence": 0.9 },
      { "word": "flesh", "start": 3.53, "end": 3.88, "confidence": 0.9 },
      { "word": "and", "start": 3.88, "end": 4.02, "confidence": 0.9 },
      { "word": "a", "start": 4.02, "end": 4.06, "confidence": 0.9 },
      { "word": "large", "start": 4.06, "end": 4.37, "confidence": 0.9 },
      { "word": "stone", "start": 4.37, "end": 4.84, "confidence": 0.9 }
    ]
  },
  "task_id": "5774cc78b01249ab09f089dd",
  "task": {
    // populated task for convenience
    ...
  }
}

Example callback body on error or issue

{
  "response": {
    "error": "The audio file cannot be loaded."
  },
  "task_id": "5774cc78b01249ab09f089dd",
  "task": {
    // populated task for convenience
    ...
  }
}

The response object, which is part of the callback POST request and permanently stored as part of the task object, will have either an error field or a transcript, duration, and alignment field.

If the transcription was completed successfully, the transcript will be stored in plaintext under the transcript field. It will also contain a duration field, which stores the duration of the audio file in seconds.

Successful transcriptions will also include an alignment field, which will contain an array of aligned words (in the same order as the transcript), where each entry in the array has the following values:

If there was an error or issue during transcription, the error will be detailed in the error field, and a partial transcript (if applicable) will be stored in the transcript field.

Callbacks

The callback_url will be POSTed with application/json data of the following object form:

{
  "task": {
    "task_id": "576c41bf13e36b0600b02b34",
    "completed_at": "2016-06-23T21:54:44.904Z",
    "response": {
      "category": "red"
    },
    "created_at": "2016-06-23T20:08:31.573Z",
    "callback_url": "http://www.example.com/callback",
    "type": "categorization",
    "status": "completed",
    "instruction": "Is this object red or blue?",
    "urgency": "day",
    "params": {
      "attachment_type": "text",
      "attachment": "tomato",
      "categories": [
        "red",
        "blue"
      ]
    },
    "metadata": {}
  },
  "response": {
    "category": "red"
  },
  "task_id": "576c41bf13e36b0600b02b34"
}

On your tasks, you will be required to supply a callback_url, a fully qualified URL that we will POST with the results of the task when completed. The data will be served as a JSON body (application/json). Alternately, you can set a default callback URL in your profile, which will be used for tasks that do not specify one.

You should respond to the POST request with a 2xx status code. If we do not receive a 2xx status code, we will continue to retry up to 20 times over the course of the next 24 hours.

If we receive a 2xx status code, the task will be populated with a true value for the callback_succeeded parameter. Otherwise, if we do not recieve a 2xx status code on any retry, the task will be populated with a false value for the callback_succeeded parameter.

Getting Started

We have sample callback server implementations, which you can deploy to Heroku in seconds, in the following languages:

If you’re just testing and want to try a few requests, the easiest way to get started is to use a RequestBin and send requests using your http://requestb.in/someHash URL as the callback_url. You can also use ngrok to expose a local server to the internet for fast prototyping.

Feel free to chat us on Slack or email us if you have any trouble.

Authentication

If you’d like to authenticate our callbacks, we set a scale-callback-auth HTTP header on each of our callbacks. The value will be equal to your Live Callback Auth Key shown on your dashboard. If this header is not set, or it is set incorrectly, the callback is not from Scale.

POST Data

Attribute Type Description
task_id string The task_id is the unique identifier for the task.
response object The response object of the completed request. For categorization, it will contain a category attribute of the assigned category.
task object The full task object for reference and convenience.

Task Endpoints

Retrieve a Task

curl "https://api.scaleapi.com/v1/task/{task_id}" \
  -u "{{ApiKey}}:"
import scaleapi

client = scaleapi.ScaleClient('{{ApiKey}}')
task_id = 'YOUR_TASK_ID'

task = client.fetch_task(task_id)
var scaleapi = require('scaleapi');

var client = scaleapi.ScaleClient('{{ApiKey}}');

var task_id = 'YOUR_TASK_ID';

client.fetchTask(task_id, (err, task) => {
    // do something with task
});
require 'scale'
scale = Scale.new(api_key: '{{ApiKey}}')

scale.tasks.find("58a63795aa9d139b20a42535")
=> #<Scale::Api::Tasks::Categorization:0x007fcc10978ab8 @task_id="58a63795aa9d139b20a42535", @type="categorization", @instruction="Is this company public or private?", @params={"attachment_type"=>"website", "attachment"=>"https://www.google.com", "categories"=>["public", "private"], "allow_multiple"=>false}, @urgency="day", @response=nil, @callback_url="http://www.example.com/callback", @created_at=2017-02-16 23:36:53 UTC, @status="pending", @completed_at=nil, @callback_succeeded_at=nil, @metadata={}, @client=#<struct Scale::Api api_key="live_358440e50ba277654e847a079eda9614", callback_auth_key=nil, default_request_params={:callback_url=>nil}, logging=false>>

The above command returns an object structured like this:

{
  "task_id": "576ba74eec471ff9b01557cc",
  "completed_at": "2016-06-23T09:10:02.798Z",
  "created_at": "2016-06-23T09:09:34.752Z",
  "callback_url": "http://www.example.com/callback",
  "type": "categorization",
  "status": "completed",
  "instruction": "Would you say this item is big or small?",
  "urgency": "day",
  "params": {
    "attachment_type": "text",
    "attachment": "car",
    "categories": [
      "big",
      "small"
    ]
  },
  "response": {
    "category": "big"
  },
  "metadata": {}
}

This endpoint retrieves a specific task.

HTTP Request

GET https://api.scaleapi.com/v1/task/{TASK_ID}

URL Parameters

Parameter Description
task_id The task_id of the task to retrieve

Returns

Returns a task if a valid identifier was provided, and returns a 404 error otherwise.

Cancel a task

curl -X POST "https://api.scaleapi.com/v1/task/{task_id}/cancel" \
  -u "{{ApiKey}}:"
import scaleapi

client = scaleapi.ScaleClient('{{ApiKey}}')
task_id = 'YOUR_TASK_ID'

task = client.cancel_task(task_id)
var scaleapi = require('scaleapi');

var client = scaleapi.ScaleClient('{{ApiKey}}');

var task_id = 'YOUR_TASK_ID';

client.cancelTask(task_id, (err, task) => {
    // do something with task
});
require 'scale'
scale = Scale.new(api_key: '{{ApiKey}}')

canceled_task = scale.tasks.cancel("YOUR_TASK_ID") # Returns the appropriate Task object with status set to canceled
=> #<Scale::Api::Tasks::Categorization:0x007fcc1108b288 @task_id="58a63795aa9d139b20a42535", @type="categorization", @instruction="Is this company public or private?", @params={"attachment_type"=>"website", "attachment"=>"https://www.google.com", "categories"=>["public", "private"], "allow_multiple"=>false}, @urgency="day", @response=nil, @callback_url="http://www.example.com/callback", @created_at=2017-02-16 23:36:53 UTC, @status="canceled", @completed_at=nil, @callback_succeeded_at=nil, @metadata={}, @client=#<struct Scale::Api api_key="live_358440e50ba277654e847a079eda9614", callback_auth_key=nil, default_request_params={:callback_url=>nil}, logging=false>>

canceled_task.cancelled?
=> true

The above command returns an object structured like this:

{
  "task_id": "576ba74eec471ff9b01557cc",
  "created_at": "2016-06-23T09:09:34.752Z",
  "callback_url": "http://www.example.com/callback",
  "type": "categorization",
  "status": "canceled",
  "instruction": "Would you say this item is big or small?",
  "urgency": "week",
  "params": {
    "attachment_type": "text",
    "attachment": "car",
    "categories": [
      "big",
      "small"
    ]
  },
  "metadata": {}
}

This endpoint cancels a task so that it will not be completed.

You may only cancel pending tasks, and the endpoint will return a 500 error code if you attempt to cancel a completed task.

HTTP Request

POST https://api.scaleapi.com/v1/task/{TASK_ID}/cancel

URL Parameters

Parameter Description
task_id The task_id of the task to cancel

Returns

Returns the canceled task if a valid identifier for a pending task was provided, and returns a 404 error or 500 error otherwise.

List All Tasks

curl "https://api.scaleapi.com/v1/tasks" \
  -u "{{ApiKey}}:"
import scaleapi

client = scaleapi.ScaleClient('{{ApiKey}}')
task_id = 'YOUR_TASK_ID'

# specify URL params as kwargs to tasks()
tasklist = client.tasks()
var scaleapi = require('scaleapi');

var client = scaleapi.ScaleClient('{{ApiKey}}');

// specify URL parameters as properties in the params object
var params = {};
client.tasks(params, (err, tasklist) => {
    // do something with tasklist
});
require 'scale'
scale = Scale.new(api_key: 'SCALE_API_KEY')

# You can pass params like start_time or end_time as keys to filter results
scale.tasks.where
=> #<Scale::Api::TaskList:0x007fcc11822a28 @client=#<struct Scale::Api api_key="live_358440e50ba277654e847a079eda9614", callback_auth_key=nil, default_request_params={:callback_url=>nil}, logging=false>, @docs=[#<Scale::Api::Tasks::Categorization:0x007fcc118227f8 @task_id="58a63795aa9d139b20a42535", @type="categorization", @instruction="Is this company public or private?", @params={"attachment_type"=>"website", "attachment"=>"https://www.google.com", "categories"=>["public", "private"], "allow_multiple"=>false}, @urgency="day", @response=nil, @callback_url="http://www.example.com/callback", @created_at=2017-02-16 23:36:53 UTC, @status="pending", @completed_at=nil, @callback_succeeded_at=nil, @metadata={}, @client=#<struct Scale::Api api_key="live_358440e50ba277654e847a079eda9614", callback_auth_key=nil, default_request_params={:callback_url=>nil}, logging=false>>], @limit=1, @offset=0, @has_more=true, @params={:start_time=>nil, :end_time=>nil, :limit=>1, :offset=>0, :status=>nil, :type=>nil}>
# Scale::Api::TaskList implements Enumerable, so it is Array-like.

The above command returns an object structured like this:

{
  "docs": [
    {
      "task_id": "576b998b4628d1bfaed7d3a4",
      "created_at": "2016-06-23T08:10:51.032Z",
      "callback_url": "http://www.example.com/callback",
      "type": "categorization",
      "status": "completed",
      "instruction": "Is this object big or small?",
      "urgency": "immediate",
      "params": {
        "attachment_type": "text",
        "attachment": "ant",
        "categories": [
          "big",
          "small"
        ]
      },
      "completed_at": "2016-06-23T19:36:23.084Z",
      "response": {
        "category": "small"
      },
      "metadata": {}
    },
    {
      "task_id": "576ba301eed30241b0e9bbf7",
      "created_at": "2016-06-23T08:51:13.903Z",
      "callback_url": "http://www.example.com/callback",
      "type": "categorization",
      "status": "completed",
      "instruction": "Is this object big or small?",
      "urgency": "day",
      "params": {
        "attachment_type": "text",
        "attachment": "T-Rex",
        "categories": [
          "big",
          "small"
        ]
      },
      "completed_at": "2016-06-23T09:09:10.108Z",
      "response": {
        "category": "big"
      },
      "metadata": {}
    }
  ],
  "total": 2,
  "limit": 100,
  "offset": 0,
  "has_more": false
}

This is a paged endpoint retrieves a list of your tasks. The tasks will be returned in descending order based on created_at time. The pagination is based on the limit and offset parameters, which determine the page size and how many results to skip.

HTTP Request

GET https://api.scaleapi.com/v1/tasks

URL Parameters

Parameter Type Description Required
start_time ISO 8601 Date The minimum value of created_at for tasks to be returned optional
end_time ISO 8601 Date The maximum value of created_at for tasks to be returned optional
status string The status of the task - can be: completed, pending, or canceled optional
type string The type of the task - can be: transcription, categorization, comparison, annotation, datacollection, audiotranscription, or any other task type. optional
limit integer A number between 1 and 100, the maximum number of results to display per page optional, default 100
offset integer The number of results to skip, for showing the next page optional, default 0

Returns

Returns a list of your tasks.

Errors

The Scale API uses the following HTTP codes:

Error Code Meaning
200 OK – Everything worked as expected.
400 Bad Request – The request was unacceptable, often due to missing a required parameter.
401 Unauthorized – No valid API key provided.
402 Not enabled – Please contact [email protected] before creating this type of task.
404 Not Found – The requested resource doesn’t exist.
429 Too Many Requests – Too many requests hit the API too quickly.
500 Internal Server Error – We had a problem with our server. Try again later.