Create Multi-Stage Task

This endpoint creates a

multistage

task. Multi-stage tasks are designed to handle complex full-scene labeling that spans multiple annotation types and modalities, and serves as a replacement for Scale’s legacy dependent tasks system (which requires using multiple tasks to fully label a scene).

Use cases for multi-stage tasks include but are not limited to:

Linking 3D cuboids to their 2D bounding box/polygon projections
Linking 3D cuboids to relevant top-down annotations
Conditional labeling (e.g. categorizing scenes based on localization quality to determine whether to label them)

The required parameters for this task are project, attachments, and scene_format.

The callback_url is the URL which will be POSTed on task completion, and is described in more detail in the Callback section.

Scale supports the following attachment types for multi-stage tasks:

(Recommended) Sensor Fusion Scene (.SFS)
LiDAR frames (.JSON)

Body Params

projectstringrequired

The name of the project to associate this task with. See the Projects Section for more details.

batchstring

The name of the batch to associate this task with. Note that if a batch is specified, you need not specify the project, as the task will automatically be associated with the batch's project. For Scale Rapid projects specifying a batch is required. See Batches section for more details.

instructionstring

A markdown-enabled string or iframe embed google doc explaining how to do the task. You can use markdown to show example images, give structure to your instructions, and more.

callback_urlstring

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.

attachmentsarray of stringsrequired

URLs to the scene attachments. Can be a single URL for .SFS attachments, or one URL per frame for .JSON attachments.

scene_formatstringrequired

Describes what type of file the attachment is. Can be sensor_fusion for .SFS attachments or split_base64 for .JSON attachments

task_blueprint_idstring

The ID of the blueprint that you would like to use when creating the multi-stage task. If no blueprint is specified, Scale will default to using the project’s most recent active blueprint.

metadataobject

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. Max 10KB.

unique_idstring

A arbitrary ID that you can assign to a task and then query for later. This ID must be unique across all projects under your account, otherwise the task submission will be rejected. See Avoiding Duplicate Tasks for more details.

priorityinteger

A value of 10, 20, or 30 that defines the priority of a task within a project. The higher the number, the higher the priority.

clear_unique_id_on_errorboolean

If set to be true, if a task errors out after being submitted, the unique id on the task will be unset. This param allows workflows where you can re-submit the same unique id to recover from errors automatically

tagsarray of strings

Arbitrary labels that you can assign to a task. At most 5 tags are allowed per task. You can query tasks with specific tags through the task retrieval API.

Request

POST/v1/task/multistage

import requests

# Replace with your actual API key
API_KEY = "your_api_key_here"

# Define the URL for the API endpoint
url = "https://api.scale.com/v1/task/multistage"

# Define the payload for the multi-stage task
payload = {
    "project": "your_project_name_here"
    "instruction": "Annotate the *vehicles* and *pedestrians* in the scene.",
    "callback_url": "https://example.com/callback",
    "attachments": ["https://static.scale.com/uploads/pandaset-demo/scene.sfs"],
    "scene_format": "sensor_fusion",
    "priority": None
}

# Set up the headers for the request
headers = {
    "accept": "application/json",       # Specify that we want the response in JSON format
    "content-type": "application/json"  # Specify the content type of the request
}

# Adding authentication to the POST request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.post(url, json=payload, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

Response

{
  "callback_url": "http://www.example.com/callback",
  "created_at": "2024-01-16T21:03:33.166Z",
  "instruction": "Annotate the *vehicles* and *pedestrians* in the scene.",
  "is_test": false,
  "params": {},
  "status": "pending",
  "task_id": "5a99e20de50d4979ce6d291e",
  "type": "multistage"
}