Introduction

Welcome to the Hive API! You can use our API to submit task classification requests to our data labeling service or pretrained APIs. Sign up here to get started with a free account on Hive. You can also contact us at sales@thehive.ai with any questions.

Authentication

We use API keys to allow access to our API. Each project that you create will be associated with a unique API key. We expect a project API key to be included in all API requests to the server via HTTP Basic Auth. Provide your API key as the Authorization value. You do not need to provide a password.

Authorization: Token YOUR_API_KEY

You must replace YOUR_API_KEY with your project’s API key. You must make sure to include the Token string before your API key when construction the authorization header.

Data Labeling API

curl --request POST \
  --url https://api.thehive.ai/api/v1/tag/task \
  --header 'Authorization: Token YOUR_TOKEN' \
  --form 'image=@YOUR_OBJECT' \
  --form 'text=Optional Text Data' \

curl --request POST \
  --url https://api.thehive.ai/api/v1/tag/task \
  --header 'Authorization: Token YOUR_TOKEN' \
  --form 'image_url=YOUR_URL' \
  --form 'text=Optional Text Data' \

Example response:

{
  "id": "demo_dc880ab0-9598-44eb-89c7-945dbc37ccdc",
  "project_id": 0,
  "user_id": 3,
  "callback": null,
  "project_type": "np",
  "media_type": "photo",
  "params": {},
  "status": ["yes"],
  "created_on": "2016-09-21T03:34:57.000Z"
}

API Call

This endpoint creates a classification task. This endpoint is used to submit tasks to both our data labeling service and our pretrained APIs. We will return a response to you once the task has been classified. You can submit images, gifs, and videos.

Endpoint
POST	https://api.thehive.ai/api/v1/tag/task

Request Header
Authorization	Token YOUR_TOKEN

Request Body (image data)
form	image=@YOUR_FILEPATH OR image_url=YOUR_URL

API Response

The endpoint will then return the data labeling result to you in the status field of the json response.

Pretrained API

curl --request POST \
  --url https://api.thehive.ai/api/v1/tag/task \
  --header 'Authorization: Token YOUR_TOKEN' \
  --form 'image=@YOUR_OBJECT' \

curl --request POST \
  --url https://api.thehive.ai/api/v1/tag/task \
  --header 'Authorization: Token YOUR_TOKEN' \
  --form 'image_url=YOUR_URL' \

Example response:

{
  "status": {
    "code": "INT",
    "message": "STRING"
  },
  "response": {
    "input": {
      "id": "UUID",
      "user_id": "INT",
      "project_id": "INT",
      "charge": "FLOAT",
      "model": "STRING",
      "model_version": "STRING",
      "model_type": "STRING",
      "created_on": "TIMESTAMP",
      "media": {
        "url": "STRING",
        "filename": "STRING",
        "type": "STRING",
        "mimetype": "STRING",
        "width": "INT",
        "height": "INT",
        "num_frames": "INT"
      }
    },

    // BOUNDING BOX OUTPUT
    "output": [
      {
        "time": "INT",
        "bounding_poly": [
          {
            "vertices": [
              {
                "y": "FLOAT",
                "x": "FLOAT"
              },
              {
                "y": "FLOAT",
                "x": "FLOAT"
              },
              {
                "y": "FLOAT",
                "x": "FLOAT"
              },
              {
                "y": "FLOAT",
                "x": "FLOAT"
              }
            ],
            "classes": [
              {
                "class": "STRING",
                "score": "FLOAT"
              }
            ],
            "keypoints": [],
            "meta": {
              "score": "FLOAT"
            }
          }
        ]
      }
    ]
  },

  // CATEGORIZATION OUTPUT
  "output": [
    {
      "classes": [
        {
          "class": "STRING",
          "score": "FLOAT"
        }
      ],
      "time": "TIMESTAMP"
    }
  ],

  // SEMANTIC SEGMENTATION OUTPUT
  "output": [
    {
      "url": "STRING", 
      "mapping": [
        {
          "class": "STRING",
          "value": "INT"
        }
      ]
    }
  ]
}

API Call

Endpoint
POST	https://api.thehive.ai/api/v1/tag/task

Request Header
Authorization	Token YOUR_TOKEN

Request Body (image data)
form	image=@YOUR_FILEPATH OR image_url=YOUR_URL

Request Body (optional text data)
form	text=YOUR_OPTIONAL_TEXT

API Response

The endpoint will then return the categorization result to you in the status field of the json response.

status object
code	A status code indicating the success or failure of your request
message	A status string indicating the success or failure of your request

response object
input	A json object containing data about your API request
output	A json object containing data about the classification of your API request.

input object
id	A unique identifier for your task submission
user_id	A unique identifier for your Hive account
project_id	A unique identifier for your Hive project
charge	The amount you were charged for the task submission
model	The pretrained model used to process your request
model_version	The model version of the pretrained model used to process your request
model_type	The type of model used to process your request. This could be categorization, bounding_box, semantic_segmentation, etc
created_on	A timestamp indicating when your task was submitted
media	A json object containing data about the image or video that was submitted

media object
url	The original url of the image or video if the task was created using the ‘image_url’ form field
filename	The filename of the image or video if the task was created by uploading binary data in the 'image’ form field
type	The file type of your media
mimetype	The mime type of your media
width	The width of your media in pixels
height	The height of your media in pixels
num_frames	The number of frames of your media if your media is a video or a .gif

output object
time	The time in seconds
bounding_poly	An array that contains information about every bounding box for the image or video frame

bounding_poly object
vertices	An array of points that form a boundary around the detected object
classes	An array that contains information about every bounding box for the image or video frame
keypoints	An optional array that contains information about any keypoints returned for the classification
meta	An optional array that contains information about the object

vertices object
x	The x coordinate of the vertice in pixels
y	The y coordinate of the vertice in pixels

classes object
class	The model class
score	A value indicating the confidence of the returned class

output object
time	The time in seconds
classes	An array that contains information about every image or video frame

classes object
class	The model class
score	A value indicating the confidence of the returned class

output object
url	The time in seconds
mapping	An array that contains information about how to map pixel values to classes

mapping object
class	The model class
value	An integer from 0 to 255 representing the class

Errors

Error Code	Meaning
200	OK – Everything worked!
400	Bad Request – The request could not be accepted.
403	Unauthorized – Your API key is wrong.
404	Not Found – The page could not be found.
405	Not Found – Insufficient account balance.
429	Too Many Requests – You’ve made too many requests to the API, please try again in a few minutes.
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarially offline for maintanance. Please try again later.
504	Gateway Timeout – We’re not able to fulfill your request at this time. Please try again later.