How to use Hasty API

If you ever find yourself in a situation when you do not want to use Hasty’s UI to work on your project, you can always rely on Hasty’s API to help you complete the task programmatically. Still, if you have not worked with APIs before, it might be challenging to tune in and start using an API effectively. Please pay attention to the step-by-step guide and simple examples below if that is the case.

Let’s jump in.

General workflow

In general, working with APIs is pretty straightforward:

1. Create an API account;

2. Create an API key;

3. Use the API following its official documentation.

Unfortunately, sometimes you might face different obstacles as not all the APIs are intuitive. Let’s go through a step-by-step guide of using Hasty’s API to minimize the possibility of difficulties.

How to create your API key

To start with, let’s deal with the terminology. An Application Programming Interface (API) is a system of tools and resources that allows communication between different programs. In simple words, an API includes:

• A set of operations it can perform;

• The data an API should receive as an input for the operation to happen;

• The data an API should return as output after executing a specific process.

Communication between a user and an API is impossible without an API key. API keys are encryption keys for user authentication. In other words, an API key is an analog with a login and password for an API. There are two kinds of API keys:

• The public key is used to encrypt the data when the API accesses the server;

• The private key is known only by the user and platform owner and used to decrypt data sent by the API.

So, to work with Hasty’s API, you also need an API key. Let’s check out how to get one. First, you need to go to the list of your workspaces by clicking on Hasty’s hedgehog logo in the upper left corner. Second, choose a workspace you want to create your API key for.

In my case, I will create the key for the Demo projects workspace (the green one you might see in the screenshot above). To do so, please press on the three dots near the workspace name and then click on the Edit button.

This will get you to the workspace editing page.

To create an API key, please go to the API accounts section and press the Add new account button.

You will see a form for creating a service account which is essentially a virtual user created only for the API. Please fill in all the necessary fields and press the Create button.

The account you have just created will appear on the same page below. To generate the key, press the Create key button, fill in the key’s name, make sure the key is Active, and press Create.

Your API key is ready. Please, make sure to copy and save it as you will not see it once again for security reasons. If you ever lose the key, simply generate the other one.

As soon as you generate the key, it will be attached to your service account and will appear under the corresponding account of the API accounts section. There you can always check its status and change it if necessary.

Excellent, now you have the API key. It is time to get the API to work.

Getting started with the API

If you have an API key, you are ready to try out the API. The best first step you can take when learning to work with something new is to refer to its official documentation. The same is true with Hasty API. So, to start with, please check all the API capabilities in the documentation.

You can do many things with our API, but let’s focus on the basic ones to form a general workflow. When starting working with Hasty, the first thing you should do is create a new project. Sure, you can do it via Hasty’s UI, but you can do it through the API as well.

As you may have noticed, you can access Hasty API through many programming languages, but here we will stick with Python as the most popular language among Data Scientists.

Creating a new project

Our documentation has a convenient UI that will allow you to form your API request on short notice. To create a new project, you need to fill in the following fields:

• Header - your API key;

• URL - leave it as it is;

• content_type - images or videos;

• description - project description;

• name - project name;

• workspace_id - id of the workspace the project will be created in. Please click on the workspace name on the workspace list page and copy the string after the last slash to find out your workspace id. For example, for my workspace the URL is app-default-none-kp.dev.hasty.ai/workspace/2724b9ab-fc60-4184-8fe3-39910992cf50, so the workspace id is 2724b9ab-fc60-4184-8fe3-39910992cf50.

Let’s fill in all these fields.

As you might have noticed, the request Python code in the right lower corner instantly updated as soon as you added the necessary parameters to your request. So, if you have all the fields filled in, you can just press the Try It! button to send your request to the API or copy the code to use it somewhere else. In my case, it is a bit more complicated since my URL differs from the default one. So, I will copy the code, adjust it, and send a request to the Hasty API through Google Colab notebook.

      import requests

# the URL to my workspace was 
# https://app-default-none-kp.dev.hasty.ai/workspace/2724b9ab-fc60-4184-8fe3-39910992cf50
# It happened because I was working on a different Hasty cluster
# (this shouldn't be the case for you)
# So, to get it to work, I simply added the cluster name -default-none-kp.dev.
# after the api in the Base URL

url = "https://api-default-none-kp.dev.hasty.ai/v1/projects"

payload = {
    "description": "Eye detection",
    "content_type": "IMAGES",
    "name": "OpenCloseEye",
    "workspace_id": "2724b9ab-fc60-4184-8fe3-39910992cf50"
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "X-Api-Key": "your_api_key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
    

The request worked as intended, and now I have a new empty project in my workspace. Check yours too - the project should be there.

Creating a new dataset

Your new project will likely have many datasets. By default, Hasty creates one named Default, but you can create a new dataset yourself. The workflow is the same as in the previous example:

1. Fill in all the Required fields in the documentation UI;

2. Request the API directly from the docs or copy the code to use it somewhere else;

3. Check if the request worked through the Hasty UI.

To create a new dataset inside the existing project, you need to know the project’s id. Just as in the previous case with the workspace id, you can click on your project, check its URL, and copy the id. In my case the URL is app-default-none-kp.dev.hasty.ai/projects/bd023960-f2d9-402b-b44a-e274dc1ca95e/edit/dashboard, so the id is bd023960-f2d9-402b-b44a-e274dc1ca95e.

      import requests

url = "https://api-default-none-kp.dev.hasty.ai/v1/projects/bd023960-f2d9-402b-b44a-e274dc1ca95e/datasets"

payload = {"name": "train"}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "X-Api-Key": "your_api_key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
    

You can check whether the request worked in the Images & Datasets section (check out the menu on the left after clicking on your project).

Do you see? It worked!

Uploading images

A dataset is a set of data assets. Let’s import some images into the train dataset we have created in the previous step. The best way to do it is to use the external upload request. Thus, you will be able to import any image on the Web to your Hasty project.

You might wonder where did I get the dataset_id parameter. It is an excellent example of the importance of API responses. When creating a dataset, API returns its id in the JSON response it outputs if the request was successful. In my case, it looked as follows:

That is where I got the dataset_id. As for the URL for external image upload, you can choose any image in Google Images, click on the right button, and copy its address. It is as simple as that.

      import requests

url = "https://api-default-none-kp.dev.hasty.ai/v1/projects/bd023960-f2d9-402b-b44a-e274dc1ca95e/images"

payload = {
    "copy_original": True,
    "filename": "image_2",
    "dataset_id": "2a935e66-4a95-4349-90be-b4fb778bd6f0",
    "url": "https://post.healthline.com/wp-content/uploads/2020/04/woman_eye-732x549-thumbnail.jpg"
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "X-Api-Key": "your_api_key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
    

Excellent, it worked.

Creating labels

To further work with images, we need to create labels and annotate the images. In the previous section, we have imported two cropped images of an open human eye. Let’s create the Open eye labeling class through the Hasty API.

      import requests

url = "https://api-default-none-kp.dev.hasty.ai/v1/projects/bd023960-f2d9-402b-b44a-e274dc1ca95e/label_classes"

payload = {
    "name": "Open eye",
    "type": "object"
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "X-Api-Key": "your_api_key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
    

Thus, we have created a new labeling class. You can check if it worked for you in the LABEL CLASSES section of the annotation environment (it is on the right). Also, please note that the API response contains the id of the created class. You will further use this id for labeling through the API.

Just as in the examples above, please fill in all the required parameters and the label information (you can find the image id in the response from the API you got when importing images).

      import requests

url = "https://api-default-none-kp.dev.hasty.ai/v1/projects/bd023960-f2d9-402b-b44a-e274dc1ca95e/images/758d4364-1911-433d-a814-3d30d77d9544/labels"

payload = [
    {
        "bbox": [10, 10, 750, 500],
        "mask": [],
        "polygon": [],
        "class_id": "5cdfe6f7-202a-4d72-98bf-6dc07c3549f9"
    }
]
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "X-Api-Key": "your_api_key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
    

Once again, it worked.

Updating image status

You can swiftly manage your data assets in Hasty through a status system. This system is quite essential as, for example, it shows the AI assistants which images should be used on training.

So, one more time. Fill in the parameters, send the request to the API, receive the response, and check if it worked.

      import requests

url = "https://api-default-none-kp.dev.hasty.ai/v1/projects/bd023960-f2d9-402b-b44a-e274dc1ca95e/images/758d4364-1911-433d-a814-3d30d77d9544/status"

payload = {"status": "DONE"}
headers = {
    "Content-Type": "application/json",
    "X-Api-Key": "your_api_key"
}

response = requests.request("PUT", url, json=payload, headers=headers)

print(response.text)
    

Exporting project

At some point, you might want to export your project. If you have been with us from the beginning of this page, you are already a pro API user. So, without further ado, let’s fill in all the necessary parameters for the project export initialization.

      import requests

url = "https://api-default-none-kp.dev.hasty.ai/v1/projects/bd023960-f2d9-402b-b44a-e274dc1ca95e/exports"


payload = {
    "dataset_id": ["2a935e66-4a95-4349-90be-b4fb778bd6f0"],
    "image_status": ["DONE"],
    "export_name": "Export",
    "format": "json_v1.1"
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "X-Api-Key": "your_api_key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
    

Then, you must execute the export.

      import requests

url = "https://api-default-none-kp.dev.hasty.ai/v1/projects/bd023960-f2d9-402b-b44a-e274dc1ca95e/exports/22f8462b-914d-4405-981c-4c90a6eb55be"

headers = {
    "Accept": "application/json",
    "X-Api-Key": "your_api_key"
}

response = requests.request("GET", url, headers=headers)

print(response.text)
    

That’s it. The export session is complete, and you can download your project from Hasty.

Congratulations, you nailed it!

Further Resources

• Getting started with Hasty;
• How to handle EXIF rotation