> For the complete documentation index, see [llms.txt](https://docs.nvision.nipa.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nvision.nipa.cloud/api-references/api-guide.md).

# API Guide

## POST object-detection

<mark style="color:green;">`POST`</mark> `https://nvision.nipa.cloud/api/v1/object-detection`

This endpoint allows you to get free cakes.

#### Headers

| Name           | Type   | Description                                                               |
| -------------- | ------ | ------------------------------------------------------------------------- |
| Authentication | string | ApiKey: Authentication token to track down who is requesting predictions. |
| Content-Type   | string | Application/json                                                          |

#### Request Body

| Name           | Type   | Description                                                |
| -------------- | ------ | ---------------------------------------------------------- |
| raw\_data      | string | Base64 encoded string of an image                          |
| configurations | array  | List of configuration params corresponding to the service. |

{% tabs %}
{% tab title="200 Predictions successfully retrieved." %}

```javascript
{    
   "source_id" : "",
   "frame_id" : "",
   "service_id" : "",
   "detected_objects" : [
      {
         "bounding_box" : {
            "bottom" : 251,
            "top" : 167,
            "right" : 479,
            "left" : 361
         },
         "parent" : "electronic",
         "cropped_image" : "",
         "confidence" : 0.995199978351593,
         "name" : "tvmonitor"
      }
   ]
}
```

{% endtab %}

{% tab title="400 The request body is not conformed." %}

```
{
    "message": "Bad request."
}
```

{% endtab %}

{% tab title="401 The API key is not valid, not defined, or revoked." %}

```
{
    "message": "This API key is invalid."
}
```

{% endtab %}

{% tab title="429 Request rate limit exceeded." %}

```
{
    "message": "Too many request."
}
```

{% endtab %}

{% tab title="500 Internal server error." %}

```
{
    "message": "Something went wrong."
}
```

{% endtab %}
{% endtabs %}

## Example JSON Request Body

```javascript
{
    "raw_data": <<BASE64_ENCODED_IMAGE>>,
    "configurations": [
        {
            "parameter": "ConfidenceThreshold",
            "value": "0.1"
        },
        {
            "parameter": "OutputCroppedImage",
            "value": "false"
        },
        {
            "parameter": "OutputVisualizedImage",
            "value": "false"
        }
    ]
}
```

The configuration is different on individual service types. It is structured as a key-value mapping. A config name is defined in **`parameter`** field and the corresponding value is defined in **`value`** field in **string format**.

For object detection service, there are two available configurations as follows:

* **`ConfidenceThreshold`**: to define the minimum confidence score of the prediction results.
  * Value options: `[0, 1]`
  * Default: `"0.1"`
* **`OutputCroppedImage`**: to return cropped images from bounding box detections.
  * Value options: `"true"` or `"false"`
  * Default: `"false"`
* **`OutputVisualizedImage`**: to return drawn bounding box detections on raw image.
  * Value options: `"true"` or `"false"`
  * Default: `"false"`