# v1 API Endpoints (deprecated)

## Overview

**API URL:** `https://api.celantur.com/v1/`

{% hint style="info" %}
Celantur Cloud API supports only images at the moment. Support for videos will be added soon.
{% endhint %}

## Upload image

<mark style="color:green;">`POST`</mark> `https://api.celantur.com/v1/file`

Upload image that is processed with the specified method.

The payload is limited to 4.45 MB. This limitation will be removed in the upcoming weeks.

#### Query Parameters

| Name                                       | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| method<mark style="color:red;">\*</mark>   | String  | <p>Specifies anonymization method:</p><p><code>blur</code>, <code>pixelate</code>, <code>blacken</code>, <code>detect</code></p><p></p><p><code>detect</code> generates <strong>only</strong> binary and instance segmentation masks and metadata. No anonymized image will be generated.</p><p></p><p>Default: <code>blur</code></p>                                                                                                                     |
| debug                                      | Boolean | <p>Print bounding boxes and segmentation masks of detected objects on the image.</p><p></p><p>Default: <code>false</code></p>                                                                                                                                                                                                                                                                                                                             |
| score                                      | Boolean | Print the detection scores of objects on the image. Works only if `debug` is `true`                                                                                                                                                                                                                                                                                                                                                                       |
| face                                       | Boolean | Specifies whether faces should be anonymized/detected.                                                                                                                                                                                                                                                                                                                                                                                                    |
| license-plate                              | Boolean | Specifies whether license plates should be anonymized/detected.                                                                                                                                                                                                                                                                                                                                                                                           |
| person                                     | Boolean | Specifies whether persons should be anonymized/detected.                                                                                                                                                                                                                                                                                                                                                                                                  |
| vehicle                                    | Boolean | Specifies whether vehicles should be anonymized/detected.                                                                                                                                                                                                                                                                                                                                                                                                 |
| bbox                                       | Boolean | Anonymize bounding boxes of objects (instead of segmentation).                                                                                                                                                                                                                                                                                                                                                                                            |
| ignores                                    | String  | <p>Specifies pixel coordinates of areas on the image in which no anonymization will be applied (as JSON).</p><p></p><p>The JSON string must be <strong>encoded</strong>, see <a data-mention href="#correctly-encode-strings-for-query-parameters">#correctly-encode-strings-for-query-parameters</a></p><p></p><p>Example:</p><p><code>\[{"topLeftX":182, "topLeftY":154,</code></p><p><code>"width":2000,</code></p><p><code>"height":2000}]</code></p> |
| mask-scale                                 | Number  | <p>Specifies the ratio at which the mask file will be scaled down, range between <code>0 .. 100</code>.</p><p></p><p>Default: <code>100</code></p>                                                                                                                                                                                                                                                                                                        |
| save-mask                                  | String  | <p>Specifies whether only mask files should be generated. This speeds up processing time by not creating an anonymized image:</p><p></p><p><code>all</code>, <code>binary</code>, <code>instance</code></p><p></p><p><code>detect</code> generates <strong>only</strong> binary and instance segmentation masks and metadata. No anonymized image will be generated.</p><p></p><p>Default: <code>all</code></p>                                           |
| quality                                    | Number  | <p>Specifies image quality of anonymized images in JPEG format: <code>0 .. 100</code></p><p></p><p>Default: <code>90</code></p>                                                                                                                                                                                                                                                                                                                           |
| compress-level                             | Number  | <p>Specifies image compression level of anonymized images in PNG format.</p><p></p><p>Default: <code>5</code></p>                                                                                                                                                                                                                                                                                                                                         |
| webhook                                    | String  | <p>A webhook URL to which a POST request is sent to after successful processing. </p><p>The URL must be <strong>encoded</strong>, see <a data-mention href="#correctly-encode-strings-for-query-parameters">#correctly-encode-strings-for-query-parameters</a></p><p></p><p>More details here: <a data-mention href="../webhooks">webhooks</a></p>                                                                                                        |
| kernel-size-face                           | Number  | <p>Specifies the kernel size for face blurring. See <a data-mention href="../../container/usage/customize-blurring">customize-blurring</a></p><p></p><p>Default: <code>0.35</code></p>                                                                                                                                                                                                                                                                    |
| kernel-size-person                         | Number  | <p>Specifies the kernel size for person blurring. See <a data-mention href="../../container/usage/customize-blurring">customize-blurring</a></p><p></p><p>Default: <code>95</code></p>                                                                                                                                                                                                                                                                    |
| kernel-size-license-plate                  | Number  | <p>Specifies the kernel size for license plate blurring. See <a data-mention href="../../container/usage/customize-blurring">customize-blurring</a></p><p></p><p>Default: <code>0.5</code></p>                                                                                                                                                                                                                                                            |
| kernel-size-vehicle                        | Number  | <p>Specifies the kernel size for vehicle blurring. See <a data-mention href="../../container/usage/customize-blurring">customize-blurring</a></p><p></p><p>Default: <code>61</code></p>                                                                                                                                                                                                                                                                   |
| face-anonymization-gradient-start          | Number  | <p>Specifies the gradient start value for face blurring. See <a data-mention href="../../container/usage/customize-blurring">customize-blurring</a></p><p></p><p>Default: <code>0.3</code></p>                                                                                                                                                                                                                                                            |
| face-anonymization-gradient-stop           | Number  | <p>Specifies the gradient stop value for face blurring. See <a data-mention href="../../container/usage/customize-blurring">customize-blurring</a></p><p></p><p>Default: <code>0.0</code></p>                                                                                                                                                                                                                                                             |
| license-plate-anonymization-gradient-start | Number  | <p>Specifies the gradient start value for license plate blurring. See <a data-mention href="../../container/usage/customize-blurring">customize-blurring</a></p><p></p><p>Default: <code>0.3</code></p>                                                                                                                                                                                                                                                   |
| license-plate-anonymization-gradient-stop  | Number  | <p>Specifies the gradient stop value for license plate blurring. See <a data-mention href="../../container/usage/customize-blurring">customize-blurring</a></p><p></p><p>Default: <code>0.0</code></p>                                                                                                                                                                                                                                                    |

#### Headers

| Name                                            | Type   | Description                 |
| ----------------------------------------------- | ------ | --------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Authorization token         |
| Content-Type<mark style="color:red;">\*</mark>  | String | "image/jpeg" or "image/png" |

#### Request Body

| Name                                | Type   | Description                                              |
| ----------------------------------- | ------ | -------------------------------------------------------- |
| -<mark style="color:red;">\*</mark> | object | <p>The image.</p><p><br>Payload is limited to 10 MB.</p> |

{% tabs %}
{% tab title="200: OK Response body with JSON " %}
Response body JSON containing file information and parameters:

```javascript
{
  "customer_id": "customer_id",
  "file_id": "file_id",
  "upload_time": "24/01/2023, 14:07:51",
  "delete_time": null,
  "name": "example.jpg",
  "debug": false,
  "score": false,
  "method": "blur",
  "face": true,
  "license_plate": false,
  "person": false,
  "vehicle": false,
  "format": "whole",
  "bbox": false,
  "ignores": [],
  "mask_scale": 100,
  "save_mask": "all",
  "quality": 90,
  "compress_level": 5,
  "kernel_size_face": 0.35,
  "kernel_size_person": 91,
  "kernel_size_license_plate": 0.5,
  "kernel_size_vehicle": 61,
  "face_anonymization_gradient_start": 0.3,
  "face_anonymization_gradient_stop": 0.0,
  "license_plate_anonymization_gradient_start": 0.3,
  "license_plate_anonymization_gradient_stop": 0.0,
  "webhook": null,
  "file_status": "queued",
  "webhook_status": "empty"
}
```

{% endtab %}
{% endtabs %}

### Correctly encode strings for query parameters

When setting format, ignores and webhook values, strings must be encoded.

{% code title="String encoding in Python" %}

```python
webhook_url = 'https://example.com/webhook/dev?sender=celantur&approve=always'

# encode the URL you want to send the webhook to
# returns 'https://example.com/webhook/dev?sender=celantur%26approve=always'
webhook_url_encoded = webhook_url.encode()
```

{% endcode %}

See further string encoding examples in [Java](https://www.baeldung.com/java-url-encoding-decoding), [C#](https://learn.microsoft.com/en-us/dotnet/api/system.web.httputility.urlencode?view=net-8.0), [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI) and [cUrl](https://everything.curl.dev/http/post/url-encode).

## Get file status

<mark style="color:blue;">`GET`</mark> `https://api.celantur.com/v1/file/{id}/status`

#### Path Parameters

| Name                                 | Type   | Description    |
| ------------------------------------ | ------ | -------------- |
| id<mark style="color:red;">\*</mark> | String | id of the file |

#### Headers

| Name          | Type   | Description   |
| ------------- | ------ | ------------- |
| Authorization | String | Authorization |

{% tabs %}
{% tab title="200: OK File status as JSON" %}

```javascript
{
  "file_id": "f8bd9047-9c21-401b-89e4-ff54392e377a",
  "file_status": "done",
  "delete_time": null
}
```

{% endtab %}
{% endtabs %}

## Get anonymized file

<mark style="color:blue;">`GET`</mark> `https://api.celantur.com/v1/file/{id}/anonymized`

#### Path Parameters

| Name                                 | Type   | Description    |
| ------------------------------------ | ------ | -------------- |
| id<mark style="color:red;">\*</mark> | String | id of the file |

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Authorization token |

{% tabs %}
{% tab title="200: OK File" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Get image binary segmentation mask

<mark style="color:blue;">`GET`</mark> `https://api.celantur.com/v1/file/{id}/binary-mask`

#### Path Parameters

| Name                                 | Type   | Description    |
| ------------------------------------ | ------ | -------------- |
| id<mark style="color:red;">\*</mark> | String | id of the file |

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Authorization token |

{% tabs %}
{% tab title="200: OK Binary segmentation mask" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Get image instance segmentation mask

<mark style="color:blue;">`GET`</mark> `https://api.celantur.com/v1/file/{id}/instance-mask`

#### Path Parameters

| Name                                 | Type   | Description    |
| ------------------------------------ | ------ | -------------- |
| id<mark style="color:red;">\*</mark> | String | id of the file |

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Authorization token |

{% tabs %}
{% tab title="200: OK Instance segmentation mask" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Get metadata

<mark style="color:blue;">`GET`</mark> `https://api.celantur.com/v1/file/{id}/metadata`

Returns metadata (detected objects) in JSON format

#### Query Parameters

| Name                                 | Type   | Description    |
| ------------------------------------ | ------ | -------------- |
| id<mark style="color:red;">\*</mark> | String | id of the file |

{% tabs %}
{% tab title="200: OK Metadata in JSON format" %}

```javascript
{
   "customer_id":"2c46d468-ee8c-4317-b4d4-aff8462f4543",
   "file_id":"04b4db09-3b1d-4e2e-8141-935cadad6dcd",
   "detections":[
      {
         "score":"0.9995585083961487",
         "offset":[
            "1209",
            "2752"
         ],
         "color":"None",
         "bbox":[
            "1209",
            "2752",
            "2529",
            "6477"
         ],
         "parent_image":"04b4db09-3b1d-4e2e-8141-935cadad6dcd.jpg",
         "id":"0",
         "type_label":"face",
         "type":"103",
         "is_anonymised":true
      },
      {
         "score":"0.9993017911911011",
         "offset":[
            "2133",
            "2803"
         ],
         "color":"None",
         "bbox":[
            "2133",
            "2803",
            "3444",
            "6553"
         ],
         "parent_image":"04b4db09-3b1d-4e2e-8141-935cadad6dcd.jpg",
         "id":"0",
         "type_label":"face",
         "type":"103",
         "is_anonymised":true
      }
   ],
   "webhook": null,
   "upload_time": "20/04/2023, 07:17:37",
   "kernel_size_vehicle": "61",
   "score": false,
   "name": "a1b69a69-50dd-4541-a6ba-13ce26ec767d.jpg",
   "method": "blur",
   "vehicle": false,
   "compress_level": "5",
   "delete_time": null,
   "ignores": [],
   "webhook_status": "empty",
   "bbox": false,
   "face_anonymization_gradient_start": "0.3",
   "debug": false,
   "file_status": "done",
   "license_plate_anonymization_gradient_start": "0.3",
   "person": false,
   "mask_scale": "100",
   "license_plate_anonymization_gradient_stop": "0",
   "face": true,
   "kernel_size_person": "91",
   "quality": "90",
   "kernel_size_face": "0.35",
   "face_anonymization_gradient_stop": "0",
   "save_mask": "all",
   "kernel_size_license_plate": "0.5",
   "format": "whole",
   "license_plate": false
}
```

{% endtab %}
{% endtabs %}

## Get original file

<mark style="color:blue;">`GET`</mark> `https://api.celantur.com/v1/file/{id}/original`

#### Path Parameters

| Name                                 | Type   | Description    |
| ------------------------------------ | ------ | -------------- |
| id<mark style="color:red;">\*</mark> | String | id of the file |

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Authorization token |

{% tabs %}
{% tab title="200: OK Original image" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## List files

<mark style="color:blue;">`GET`</mark> `https://api.celantur.com/v1/list`

Returns a paginated JSON list of all files ('items' in this context) a user has sent.

The JSON result contains information about the total item count and respective total page count depending on the specified `limit`. \
E.g.: `{'total_item_count': 46, 'total_page_count': 10, 'items': [...]}`&#x20;

The total page calculation: `total item count / limit = total page count`

#### Query Parameters

| Name                                    | Type   | Description                    |
| --------------------------------------- | ------ | ------------------------------ |
| page<mark style="color:red;">\*</mark>  | Number | The page which will be queried |
| limit<mark style="color:red;">\*</mark> | Number | The number of items per page   |

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Authorization token |

{% tabs %}
{% tab title="200: OK List of all files by page" %}

```javascript
{
  "total_item_count": "134",
  "total_page_count": "67",
  "items": [
    {
      "customer_id": "customer_id",
      "file_id": "file_id1",
      "detections": " ",
      "bbox": false,
      "debug": "True",
      "delete_time": null,
      "face": "True",
      "file_status": "queued",
      "format": "whole",
      "ignores": "[{\"topLeftX\": 182, \"topLeftY\": 154, \"width\": 2000, \"height\": 2000}]",
      "license_plate": false,
      "mask_scale": "100",
      "method": "blur",
      "person": false,
      "save_mask": "all",
      "score": "True",
      "upload_time": "10/01/2023, 16:01:23",
      "vehicle": false,
      "kernel_size_face": 0.35,
      "kernel_size_person": 91,
      "kernel_size_license_plate": 0.5,
      "kernel_size_vehicle": 61,
      "face_anonymization_gradient_start": 0.3,
      "face_anonymization_gradient_stop": 0.0,
      "license_plate_anonymization_gradient_start": 0.3,
      "license_plate_anonymization_gradient_stop": 0.0
    },
    {
      "customer_id": "customer_id",
      "file_id": "file_id2",
      "detections": " ",
      "bbox": false,
      "debug": "True",
      "delete_time": null,
      "face": "True",
      "file_status": "queued",
      "format": "{\"number\": [2, 2], \"overlap\": [0, 0]}",
      "ignores": "[{\"topLeftX\": 182, \"topLeftY\": 154, \"width\": 2000, \"height\": 2000}]",
      "license_plate": false,
      "mask_scale": "100",
      "method": "blur",
      "person": false,
      "save_mask": "all",
      "score": "True",
      "upload_time": "11/01/2023, 08:20:02",
      "vehicle": false,
      "kernel_size_face": 0.35,
      "kernel_size_person": 91,
      "kernel_size_license_plate": 0.5,
      "kernel_size_vehicle": 61,
      "face_anonymization_gradient_start": 0.3,
      "face_anonymization_gradient_stop": 0.0,
      "license_plate_anonymization_gradient_start": 0.3,
      "license_plate_anonymization_gradient_stop": 0.0
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Sign in (authorization)

<mark style="color:green;">`POST`</mark> `https://api.celantur.com/v1/signin`

Provide username/password as JSON payload to receive authorization token.&#x20;

`{ "username": "username@usermail.com", "password": "password" }`

#### Request Body

| Name                                   | Type   | Description |
| -------------------------------------- | ------ | ----------- |
| json<mark style="color:red;">\*</mark> | String | Credentials |

{% tabs %}
{% tab title="200: OK Authentication result" %}

```javascript
{
  "ChallengeParameters": {},
  "AuthenticationResult": {
    "AccessToken": "acces_token",
    "ExpiresIn": 3600,
    "TokenType": "Bearer",
    "RefreshToken": "ref_token",
    "IdToken": "id_token"
  }
}
```

{% endtab %}
{% endtabs %}