First API Call with Python

We'll be walking through making your first API call with Python

Introduction to APIs

If you haven't already, we'd encourage you to [check out our step-by-step guide(https://youtu.be/_Wv3XGICXmU) to making API calls.

Below is a step-by-step guide to making a project, a batch, submitting tasks, and finalizing that batch.

import requests

### SETTINGS ###
# your Test or Live API key will be inserted here
key = "YOUR_API_KEY_NO_COLON"
proj_name = "zoo_2d"
batch_name = "zoo_2d_batch_1"
callback_url = "http://example.com"


### Step 1: Create a project. ###
# url is defining what endpoint is being used
url = "https://api.scale.ai/v1/projects"
instruction_string = "Draw a box around all visible humans and animals."

#payload defines what data is sent throught the API call
payload = {
 'name' : proj_name,
 'type': 'annotation',
 'params': { 'instruction': instruction_string }
}

headers = {"Content-Type": "application/json"}

#this is where the POST requset to the Scale API is made
task_request = requests.post(url,
 json=payload,
 headers=headers,
 auth=(key, ''))

#this line will return an error code if the API call fails
print task_request.status_code

#this line will return the response from Scale
print task_request.json()


### Step 2: Prepare a batch upload. ###
url = "https://api.scale.ai/v1/batches"

payload = {
 'project': proj_name,
 'name': batch_name,
 'callback': callback_url
}

headers = {"Content-Type": "application/json"}

task_request = requests.post(url,
 json=payload,
 headers=headers,
 auth=(key, ''))

print task_request.status_code
print task_request.json()

### Step 3: Add tasks to the batch. ###
url = "https://api.scale.ai/v1/task/annotation"

attachments = [
 'https://upload.wikimedia.org/wikipedia/commons/e/e6/Giraffes_at_west_midlands_safari_park.jpg',
 'https://upload.wikimedia.org/wikipedia/commons/1/14/Seals%40melb_zoo.jpg',
 'https://upload.wikimedia.org/wikipedia/commons/thumb/a/a8/NCZooelephants.jpg/1280px-NCZooelephants.jpg'
]

labels = ['person', 'giraffe', 'elephant', 'seal']

for image_url in attachments:
 payload = {
 'batch': batch_name,
 'callback_url': callback_url,
 'attachment_type': 'image',
 'attachment': image_url,
 'objects_to_annotate': labels,
 'with_labels': True
 }

headers = {"Content-Type": "application/json"}

task_request = requests.post(url,
 json=payload,
 headers=headers,
 auth=(key, ''))
 
print task_request.status_code
print task_request.json()

### Step 4: Finalize the batch! ###
url = "https://api.scale.ai/v1/batches/"+batch_name+"/finalize"

task_request = requests.post(url,
 auth=(key, ''))

print task_request.status_code
print task_request.json()

From these examples we can see the key parts of the API call are:

  • Your API key: LiveXXX vs. TestXXX
  • The endpoint URL: Used to define what actions you are trying to perform through the API call - all of the different endpoints with their descriptions can be found in our API docs
  • The Payload: Defines what data you are sending through the API call under the supported parameters for that endpoint - The parameters that are supported by each endpoints can be found in our API docs
Updated a year ago