Scale AI

https://scale.com/docs
Admin
Scale AI provides a data-centric platform combining machine learning and human review to deliver...
Tokens:125,504
Snippets:843
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Scale API Javascript library

Source: https://scale.com/docs/api-reference/introduction-to-scale-api

Install the Scale API client for Javascript using npm.

```shell
$   npm install scaleapi --save
```

--------------------------------

### Install Scale API Python library

Source: https://scale.com/docs/api-reference/introduction-to-scale-api

Install the Scale API client for Python using pip or conda.

```shell
pip install --upgrade scaleapi

conda install -c conda-forge scaleapi # If using Anaconda package management
```

--------------------------------

### Batch Object JSON Example

Source: https://scale.com/docs/api-reference/data-engine-reference

Example of a batch object in JSON format, showing fields such as project, name, status, callback, and created_at. This example is referenced in the workflow steps for Enterprise, Rapid, and Studio.

```json
{
  "project": "kitten_labeling",
  "name": "kitten_labeling_2020-07",
  "status": "staging",
  "callback": "https://example.com/callback",
  "created_at": "2020-07-01T09:09:10.108Z"
}
```

--------------------------------

### Project JSON Structure

Source: https://scale.com/docs/api-reference/projects

Example of the JSON object structure returned for a project.

```json
{
  "type": "imageannotation",
  "name": "project_name",
  "param_history": [
    {
      "instruction": "Instructions",
      "version": 0,
      "created_at": "2021-04-25T07:38:32.368Z"
    }
  ],
  "created_at": "2021-04-25T07:38:32.368Z"
}
```

--------------------------------

### Retrieve a task using HTTP requests or Python SDK

Source: https://scale.com/docs/api-reference/tasks

Two Python examples for retrieving a task from the Scale API. The first uses the requests library with an HTTP GET request to the endpoint, requiring an API key for authentication. The second uses the Scale Python SDK, initializing a ScaleClient and calling get_task with a task ID.

```python
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/576ba74eec471ff9b01557cc"

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

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

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

```

```python
import scaleapi

# Initialize the ScaleClient with your API key
client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

# Define the task ID to retrieve
task_id = "601ba74eec471ff9b01557cc"  # Replace with your actual task ID

# Retrieve the task details
task = client.get_task(task_id)

# Print the task details
print(task.as_dict())

```

--------------------------------

### Create a project using the Scale Python SDK

Source: https://scale.com/docs/api-reference/projects

This example shows how to initialize the ScaleClient and use the create_project method to programmatically create a project.

```python
import scaleapi
from scaleapi.tasks import TaskType

# Initialize the ScaleClient with your API key
client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

# Define the project payload
project_payload = {
    "type": TaskType.ImageAnnotation,
    "name": "project_name",
    "rapid": False,  # Set to True if creating a Scale Rapid project
    "studio": True,  # Set to True if creating a Scale Studio project
    "params": {
        "instruction": "Instructions"
    },
    "pipeline": "pipeline_name"  # Specify the pipeline name for Studio projects
}

# Create the project
project = client.create_project(**project_payload)

# Print the created project's details
print(project.as_dict())
```

--------------------------------

### Create a project using the requests library

Source: https://scale.com/docs/api-reference/projects

This example demonstrates how to create a new project by sending a POST request to the Scale API endpoint using the Python requests library.

```python
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/projects"

# Define the payload for creating a new project
payload = {
    "type": "imageannotation",  # Type of the project
    "name": "kitten_labeling",  # Name of the project
    "rapid": False,             # Indicates if the project is a rapid project
    "studio": False,            # Indicates if the project uses Scale AI's Studio interface
    "params": { 
        "instruction": "Please label the kittens"  # Instructions for the annotation task
    }
}

# 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)
```

--------------------------------

### Image Annotation Taxonomy and param_chunks Example

Source: https://scale.com/docs/rapid-or-taxonomy-chunking

Example taxonomy for image annotation with geometries, annotation attributes, and links. The param_chunks example shows how to group labels for annotation tasks.

```javascript
geometries: {
  box: {
    objects_to_annotate: [
      'plastic_bag',
      'vegetable',
      { choice: 'fruit', subchoices: ['apple', 'banana'] },
    ],
    min_width: 0,
    min_height: 0,
    examples: [],
  },
  polygon: {
    objects_to_annotate: ['camera'],
  },
},
annotation_attributes: {
  color: {
    choices: ['green', 'white', 'yellow'],
    description: 'color',
  },
  glare: {
    description: 'Is there glare on the image?',
    choices: ['sun glare', 'night headlight glare', 'none'],
    conditions: {
      is_global: true,
    },
  },
},
links: {
  'Camera Sees': [
    {
      is_bidirectional: false,
      from_allowed_labels: ['camera'],
      to_allowed_labels: ['vegetable', 'apple', 'banana'],
    },
  ],
  Contains: [
    {
      is_bidirectional: false,
      from_allowed_labels: ['plastic_bag'],
      to_allowed_labels: ['vegetable', 'apple', 'banana'],
    },
  ],
}

```

```javascript
param_chunks: [
  ['plastic_bag', 'fruit', 'glare'],
  ['vegetable', 'camera'],
]

```

--------------------------------

### Text Collection Taxonomy and param_chunks Example

Source: https://scale.com/docs/rapid-or-taxonomy-chunking

Example taxonomy for text collection with fields of type category, text, and field_set. The param_chunks example shows how to group field IDs for text collection tasks.

```json
{
  "fields": [
    {
      "type": "category",
      "field_id": "is_green",
      "title": "Does the picture include the color green?",
      "required": true,
      "choices": [
        {
          "label":"Yes",
          "value":"yes",
        },
        {
          "label":"No",
          "value":"no",
        }
      ],
    },
    {
      "type": "text",
      "field_id": "description",
      "title": "Describe this picture."
    },
    {
      "type": "field_set",
      "field_id": "vehicle",
      "title": "A vehicle in the image",
      "fields": [
        {
          "type": "text",
          "field_id": "vehicle_type",
          "title": "What type of vehicle is this?"
        },
        {
          "type": "number",
          "field_id": "num_wheels",
          "title": "How many wheels does this vehicle have?"
        }
      ]
    }
  ]
}

```

```javascript
param_chunks: [
  ['is_green', 'description'],
  ['vehicle']
]

```

--------------------------------

### Assemble and Serialize Scene

Source: https://scale.com/docs/api-reference/sensor-fusion-reference

Create a list of sensors, instantiate the Scene object, and use JSONBinaryEncoder to write the data to an .sfs file.

```text
### CREATE SENSORS ###
lidar_sensor = generate_lidar_sensor(lidar_dataframes, lidar_timestamps, all_poses_world)
camera_sensors = [
    generate_camera_sensor(camera.name, camera_timestamps[camera.name], all_poses_world)
    for camera in cameras
] 

sensors = camera_sensors + [lidar_sensor]

### ASSEMBLE SCENE ####
scene = sfio.Scene(
    sensors=sensors, time_offset=minimum_timestamp, time_unit="microseconds"  # type: ignore
)

# convert the Scene object to an sfs object
sfs_scene = sfio.model_converters.sfs.to_scene_spec_sfs(scene)

encoder = sfio.JSONBinaryEncoder()
encoder.write_file(os.path.join(SAMPLE, "example_scene.sfs"), sfs_scene) # type: ignore
```

--------------------------------

### Retrieve a project with the Scale Python SDK

Source: https://scale.com/docs/api-reference/projects

Use the ScaleClient.get_project method to retrieve project details. Initialize the client with your API key and pass the project name. The response is printed as a dictionary.

```python
import scaleapi

# Initialize the ScaleClient with your API key
client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

# Define the project name you want to retrieve
project_name = "kitten_labeling"

# Retrieve the project details
project = client.get_project(project_name=project_name)

# Print the project details
print(project.as_dict())
```

--------------------------------

### Ellipse annotation response example

Source: https://scale.com/docs/api-reference/image-and-video-reference

JSON example showing the response for an ellipse annotation, including vertices, label, attributes, and uuid.

```json
{
  "response": {
    "annotations": [
      {
        "type": "ellipse",
        "label": "wheel",
        "attributes": {
            "position": "front_left"
        },
        "vertices": [
            {
                "x": 123,
                "y": 92
            },
            {
                "x": 173,
                "y": 113
            },
            {
                "x": 123,
                "y": 134
            },
            {
                "x": 73,
                "y": 113
            }
        ],
        "uuid": "65ec1f52-5902-4b39-bea9-ab6b4d58ef42"
      },
      { ... },
      { ... }
    ]
  },
  "task_id": "5774cc78b01249ab09f089dd",
  "task": {
    // task inlined for convenience
    ...
  }
}
```

--------------------------------

### List Projects via Python SDK

Source: https://scale.com/docs/api-reference/projects

Uses the ScaleClient to retrieve and iterate through project details.

```python
import scaleapi

# Initialize the ScaleClient with your API key
client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

# Retrieve the list of all projects
projects = client.get_projects()

# Iterate over the projects and print their details
for project in projects:
    print(project.as_dict())
```

--------------------------------

### Create a Batch using Python SDK

Source: https://scale.com/docs/api-reference/batches

Uses the ScaleClient from the scaleapi library to create a new batch.

```python
import scaleapi

# Initialize the ScaleClient with your API key
client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

# Define the batch payload
batch_payload = {
    "project": "project_name",  # The name of the project this batch belongs to
    "name": "batch_name",  # The unique name for this batch
    "callback": "http://www.example.com/callback",  # The callback URL or email
    "calibration_batch": False,  # Only applicable for Rapid projects
    "self_label_batch": False  # Only applicable for Rapid projects
}

# Create the batch
batch = client.create_batch(**batch_payload)

# Print the created batch's details
print(batch.as_dict())
```

--------------------------------

### Categorical attribute response examples

Source: https://scale.com/docs/api-reference/annotation-attributes

Response examples for categorical attributes. When allow_multiple is false, the response is a single string; when true, it is an array of strings.

```json
{
  "example_attribute": "Answer1"
}
```

```json
{
  "example_attribute": [
    "Answer1",
    "Answer2"
  ]
}
```

--------------------------------

### Authenticate with Python SDK

Source: https://scale.com/docs/api-reference/authentication

Initialize the ScaleClient using your API key.

```python
import scaleapi
client = scaleapi.ScaleClient('{{ApiKey}}')
```

--------------------------------

### Task object example - JSON

Source: https://scale.com/docs/api-reference/data-engine-reference

Full example of a completed task object from the Scale API. Shows the structure for fields like task_id, status, params, response, audits, and metadata.

```json
{
  "task_id": "576ba74eec471ff9b01557cc",
  "created_at": "2016-06-23T09:09:34.752Z",
  "updated_at": "2016-06-23T09:10:02.798Z",
  "completed_at": "2016-06-23T09:10:02.798Z",  
  "type": "categorization",
  "status": "completed",
  "instruction": "Would you say this item is big or small?",
  "params": {
    "attachment_type": "text",
    "attachment": "car",
    "categories": [
      "big",
      "small"
    ]
  },
  "callback_url": "http://www.example.com/callback",
  "callback_completed": true,
  "response": {
    "category": "big"
  },
  "metadata": {},
  "audits": [
    {
      "audited_by": "david@company.com",
      "audited_at": "2016-06-23T10:01:02.352Z",
      "audit_time_secs": 120,
      "audit_result": "accepted",
      "audit_source": "customer"
    },
    {
      "audited_by": "auditor@scale.com",
      "audited_at": "2016-06-23T10:01:02.352Z",
      "audit_time_secs": 511,
      "audit_result": "fixed",
      "audit_source": "scale"
    }
  ],
  "tags": ["experiment_1", "owner:david"],
  "unique_id": "product_experiment_dg3d9x83"
}
```

--------------------------------

### Error Response Examples

Source: https://scale.com/docs/api-reference/errors

Examples of error response structures returned by the Scale API for common failure scenarios, including missing attachments, download failures, and attachment processing errors.

```APIDOC
## Error Response Examples

### Description
These examples illustrate the structure and content of error messages returned by the Scale API in different situations.

### Error: Missing Attachment Parameter

#### Description
This error occurs when a request is made without including an attachment or attachments parameter.

#### Response Example
```json
{
  "status_code": 400,
  "error": "Please include an attachment or attachments parameter."
}
```

### Error: Attachment Download Failure

#### Description
This error indicates that one or more attachments could not be downloaded, possibly due to connectivity issues or invalid URLs.

#### Response Example
```json
{
    "error": "One or more attachments could not be downloaded.",
    "attachments": [
        {
            "statusCode": 403,
            "url": "http://example.com/kitten.png"
        }
    ]
}
```

### Error: Attachment Processing Failure

#### Description
This error provides specific details about frames that failed processing, including the frame number and error message.

#### Response Example
```json
{
    "error": "One or more attachments could not be downloaded.",
    "frames": [
        {
            "frame": 10,
            "message": "Invalid JSON Format: Unexpected end of JSON input",
            "attachment": {
                "statusCode": 200,
                "url": "http://example.com/lidar/frame10.json"
            }
        }
    ]
}
```
```

--------------------------------

### Line annotation request example

Source: https://scale.com/docs/api-reference/image-and-video-reference

Example request body for creating line annotations. The objects_to_annotate array can contain strings or LabelDescription objects, and min_vertices and max_vertices define the allowed number of vertices.

```json
{
  "geometries": {
    "line": {
      "objects_to_annotate": [
        "unmarked_lane",
        {
          "choice": "marked lanes",
          "subchoices": [
            "solid",
            {
              "choice": "dashed",
              "display": "dashed or dotted"
            }
          ]
        },
        "shoulder"
      ],
      "min_vertices": 2,
      "max_vertices": 15
    },
    ...
  },
  ...
}
```

--------------------------------

### Example JSON response for project retrieval

Source: https://scale.com/docs/api-reference/projects

Sample JSON response from the project retrieval endpoint, showing project fields such as type, name, parameter history, and creation timestamp.

```json
{
   "type": "imageannotation",
   "name": "kitten_labeling",
   "param_history": [
       {
       "instruction": "Instructions",
       "version": 0,
       "created_at": "2021-04-25T07:38:32.368Z"
       }
   ],
   "created_at": "2021-04-25T07:38:32.368Z"
}
```

--------------------------------

### Cancel a task with HTTP API or Python SDK

Source: https://scale.com/docs/api-reference/tasks

Two Python examples for canceling a task: one using the raw HTTP API with requests and one using the Scale Python SDK. Both require an API key and a task ID. The HTTP example sends a POST to the /cancel endpoint with an optional clear_unique_id query parameter; the SDK example calls client.cancel_task(task_id).

```python
import requests

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

# Define the URL for the API endpoint with query parameters
url = "https://api.scale.com/v1/task/576ba74eec471ff9b01557cc/cancel?clear_unique_id=true"

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

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

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

```python
import scaleapi

# Initialize the ScaleClient with your API key
client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

# Define the task ID to cancel
task_id = "601ba74eec471ff9b01557cc"  # Replace with your actual task ID

# Cancel the task
client.cancel_task(task_id)

# Print confirmation
print(f"Task '{task_id}' has been canceled.")
```

--------------------------------

### Python: Create LIDAR Linking Task

Source: https://scale.com/docs/api-reference/sensor-fusion-lidar-tasks

Sends a POST request to https://api.scale.com/v1/task/lidarlinking with the required payload fields. Replace 'your_api_key_here' with your actual API key. The response is printed as text.

```python
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/lidarlinking"

# Define the payload for the LIDAR linking task
payload = {
    "instruction": "**Instructions:** Please label all the things",
    "annotation_type": "imageannotation",
    "can_add_annotations": True,
    "can_edit_annotations": True,
    "can_edit_annotation_positions": True,
    "can_delete_annotations": True,
    "lidar_task": "607385eadfd77d0029a84084"
}

# 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)
```

--------------------------------

### Set task metadata with requests and Scale Python SDK

Source: https://scale.com/docs/api-reference/tasks

Two Python examples for setting task metadata: one using the raw HTTP API with requests, and one using the Scale Python SDK. Both require an API key and a valid task ID. The raw example posts to the /v1/task/{taskId}/setMetadata endpoint; the SDK example calls client.set_task_metadata(task_id, metadata).

```python
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/576ba74eec471ff9b01557cc/setMetadata"

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

# Define the payload for setting metadata
payload = {
    # Add your metadata here
    # For example: "metadata_key": "metadata_value"
}

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

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

```

```python
import scaleapi

# Initialize the ScaleClient with your API key
client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

# Define the task ID and the metadata to set
task_id = "601ba74eec471ff9b01557cc"  # Replace with your actual task ID
metadata = {
    "key1": "value1",
    "key2": "value2"
}

# Set the metadata for the task
client.set_task_metadata(task_id, metadata)

# Print confirmation
print(f"Metadata for task '{task_id}' has been set to {metadata}.")

```
Tokens:
Raw