# REST API (v1) mode

## Overview

You can start the Celantur Container in API mode and use the REST API to anonymize images and videos. There are two ways to process images and videos, via **synchronous** and **asynchronous** uploads.&#x20;

When you upload files via synchronous upload, which is the default configuration, it takes some time for you to get the response. You can then immediately download the result.

When you upload files via the asynchronous upload, by adding the header parameter `x-is-async: true` (and optionally a webhook via the query parameter),  you'll immediately receive the response, but the processing is not necessarily finished. If you added a webhook, you'll be notified once processing is finished. Otherwise, you can query the `GET /task/{id}` to check whether the processing is finished. See more information [below](#asynchronous-processing).

### Start the Container in REST API mode

Start the server with all object types (`-a face -a license-plate -a person -a vehicle`) that you want to anonymize by using the API. You can select specific objects for individual images using API calls.

{% code overflow="wrap" %}

```bash
bash celantur.sh --api --api-endpoint http://localhost:7000/ -a face -a license-plate -a person -a vehicle --format whole --save-mask all
```

{% endcode %}

#### CLI starting parameters

See [general-parameters](https://doc.celantur.com/container/usage/general-parameters "mention") for other parameters.

<table><thead><tr><th width="324">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>--api</code></td><td>Start container in REST API mode.</td></tr><tr><td><code>--api-endpoint URL</code></td><td>Specify the API endpoint that is returned with the requests. URL for downloading the anonymised images, binary masks and metadata.</td></tr></tbody></table>

### Task and files

There are two classes of endpoints:

* `/file` endpoints where you can upload and download files. When you upload a file with `POST /file` you will receive a JSON response including `{ "id": "string", ... }`. You can use the **id** to query the status of processing via `GET /task/{id}` endpoint.
* `/task` endpoints where you can query the status of file processing and manage the tasks, especially important for asynchronous processing. For processing, the files are stored internally in the folders specified by the user with the `--input` and `--output` parameters.\
  Currently, you need to manage the storage manually by deleting the files associated with a task with the `DELETE /task/{id}` to free up stsorage.

{% hint style="info" %}
Metadata, binary and instance segmentation masks are not yet supported for videos.
{% endhint %}

### Webhook

If you specify a webhook URL in `POST /file` with the query parameter `webhook` (urlencoded). You can specify header authentication with `web-auth-header-name` and `web-auth-header-value`.&#x20;

After the file has been processed, the Container will post a request to the he webhook URL with the following header and body (example):

```
POST {webhook}
{web-auth-header-name}: {web-auth-header-value}

{ 
  "ts": "2023-02-08T12:30:45.123456",
  "type": "notification.processing.status.changed",
  "event": {
    "id": "1693295888421318",
    "status": "done"
  }
} 
```

### Sychronous processing

<figure><img src="https://1992407480-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fr2aH3h1rP4SjkhFlr7Mp%2Fuploads%2FXHIBTVsJQEuhaHCq1ygU%2Fimage.png?alt=media&#x26;token=d8a9f405-2460-4212-b83f-4ebf0e26a31e" alt=""><figcaption></figcaption></figure>

1. Upload image with POST request [#upload-file](#upload-file "mention"). \
   Processing is ready once the request returns with a successful response.
2. Download image with GET request [#download-anonymized-image](#download-anonymized-image "mention")
3. Download segmentation masks and metadata:
   1. GET request [#download-binary-mask](#download-binary-mask "mention")
   2. GET request [#download-instance-mask](#download-instance-mask "mention")
   3. GET request [#download-image-metadata-json](#download-image-metadata-json "mention")

### Asynchronous processing

<figure><img src="https://1992407480-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fr2aH3h1rP4SjkhFlr7Mp%2Fuploads%2FGU1gvZHT7BaVjtbdiVJ5%2Fimage.png?alt=media&#x26;token=a2e8c231-6cd2-4d81-ae15-793bf45abf51" alt=""><figcaption></figcaption></figure>

1. Upload image with POST request [#upload-file](#upload-file "mention") with the header parameter `x-is-async: true`.\
   Request returns immediately with a response. However processing runs asynchronously and is not necessary complete.
2. Wait until processing is done.
   1. Webhook: If you added webhook, you'll receive notification, once the processing is complete.
   2. Otherwise query the task status with [#list-all-processing-tasks](#list-all-processing-tasks "mention")
3. Download the assets as in [#aynchronous-processing](#aynchronous-processing "mention").
4. Delete the task with [#delete-a-specific-task](#delete-a-specific-task "mention")

{% hint style="warning" %}
In asynchronous mode, you need to pay attention to the storage management. So delete all tasks including files that you have downloaded and are not required anymore. You can delete single tasks `DELETE /tast/{id}` or all tasks `DELETE /task/lists` .
{% endhint %}

## Image and video anonymization

We currently support JPEG and PNG images, and MP3 video containers.

## Upload file

<mark style="color:green;">`POST`</mark> `https://localhost/v1/file`

Upload a file that is processed with the specified method. The container only holds data for one image at any time. A new POST request overwrites the old data.

#### Query Parameters

| Name                                     | Type    | Description                                                                                                                                                                                                                                                                                                                       |
| ---------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| method<mark style="color:red;">\*</mark> | String  | <p>Enum: <code>blur</code>, <code>pixelate</code>, <code>blacken</code>, <code>detect</code></p><p></p><p>Default: <code>blur</code></p><p></p><p>Specifies processing method.</p><p>Method <code>detect</code> only returns segmentation and binary masks, not an anonymized image.</p>                                          |
| debug                                    | Boolean | Print bounding boxes and segmentation masks of detected objects on the image.                                                                                                                                                                                                                                                     |
| 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)                                                                                                                                                                                                                                                                     |
| format                                   | String  | <p>Default: <code>whole</code></p><p>Example: </p><p><code>format={"number": \[2,2], "overlap": \[0, 0]}</code></p><p>Tiling of the input image</p>                                                                                                                                                                               |
| ignores                                  | String  | <p>Default: ""<br>Example: <code>ignores=\[{"topLeftX": 182,"topLeftY": 154,"width":2000,"height":2000}]</code></p><p>Areas of the image that are not going to be anonymized</p>                                                                                                                                                  |
| face-threshold                           | Number  | <p>Specifies detection threshold <code>0..1</code> for faces.</p><p></p><p>Default: <code>0.5</code></p>                                                                                                                                                                                                                          |
| segmentation-threshold                   | Number  | <p><strong>DEPRECATED</strong></p><p>Specifies detection threshold value for segmentation. </p><p>▶ Use <code>person-threshold</code> and <code>vehicle-threshold</code> instead.</p>                                                                                                                                             |
| vehicle-threshold                        | Number  | <p>Specifies detection threshold <code>0..1</code> for vehicles.</p><p></p><p>Default: <code>0.4</code></p>                                                                                                                                                                                                                       |
| person-threshold                         | Number  | <p>Specifies detection threshold <code>0..1</code> for persons.</p><p></p><p>Default: <code>0.4</code></p>                                                                                                                                                                                                                        |
| license-plate-threshold                  | Number  | <p>Specifies detection threshold <code>0..1</code> for license plates.</p><p></p><p>Default: <code>0.5</code></p>                                                                                                                                                                                                                 |
| no-object-tracking                       | Boolean | Disables object tracking in videos, which is enabled by default. See [object-tracking](https://doc.celantur.com/container/usage/object-tracking "mention")                                                                                                                                                                        |
| keep-bit-rate                            | Boolean | <p>Specifies whether the bitrate of the anonymized video should remain very close to the one of the original video. </p><p></p><p>Enabling <code>keep-bit-rate</code> will ensure a nearly identically file size of the processed video, at the cost of 10% to 20% higher processing time.<br><br>Default: <code>false</code></p> |
| webhook                                  | String  | Webhook URL (urlencoded)                                                                                                                                                                                                                                                                                                          |
| webhook-auth-header-name                 | String  | Webhook header auth key/name                                                                                                                                                                                                                                                                                                      |
| webhook-auth-header-value                | String  | Webhook header auth value                                                                                                                                                                                                                                                                                                         |

#### Headers

| Name       | Type   | Description                                                                                                              |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| x-is-async | String | <p>Enables async processing.</p><p>Values: <code>true</code> or <code>false</code></p><p>Default: <code>false</code></p> |

#### Request Body

| Name                                         | Type                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fileobject<mark style="color:red;">\*</mark> | string\<binary> (Fileobject) | <p><strong>Images:</strong> </p><p><code>fileobject=@/path/to/input/image;</code></p><p></p><p>See <a data-mention href="../batch-and-stream-mode#supported-image-formats">#supported-image-formats</a></p><p></p><p><strong>Videos:</strong> </p><p>Specify the video type</p><p><code>fileobject=@/path/to/input/video;type=video/mp4</code></p><p></p><p>See <a data-mention href="../batch-and-stream-mode#supported-video-codecs">#supported-video-codecs</a></p><p></p> |

{% tabs %}
{% tab title="200: OK JSON (image upload)" %}

```javascript
{
  "content_type": "image/jpeg",
  "id": "string (uuid)",
  "metadata_url": "string",
  "binary_mask_url": "string",
  "instance_mask_url": "string",
  "anonymised_url": "string"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity JSON" %}

```javascript
{
  "detail": "..."
}
```

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}

{% tab title="200: OK JSON (video uplaod)" %}

```json
{ 
  "content_type": "video/mp4",
  "id": "string (uuid)",
  "anonymized_video": "string",
  "metadata_url": "string"
}
```

{% endtab %}
{% endtabs %}

## Download anonymized image

<mark style="color:blue;">`GET`</mark> `https://localhost/v1/file/{id}/anonymised`

Download anonymized image

#### Path Parameters

| Name                                 | Type   | Description                                          |
| ------------------------------------ | ------ | ---------------------------------------------------- |
| id<mark style="color:red;">\*</mark> | String | The `id` (UUID) of the file that will be downloaded. |

#### Query Parameters

| Name           | Type   | Description                                                                                                              |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| download       | String | <p>Enum: <code>JPEG</code> or <code>PNG</code></p><p>Whether the image should be downloaded as a JPEG or PNG.</p>        |
| quality        | Number | <p>Specifies quality level for JPEG images ranging from <code>1 .. 100</code>.</p><p></p><p>Default: <code>90</code></p> |
| compress-level | Number | <p>Specifies compression level for PNG images ranging from <code>0 .. 9</code>.</p><p></p><p>Default: <code>5</code></p> |

{% tabs %}
{% tab title="200: OK JPEG or PNG" %}

```javascript
Media type: image/png or image/jpeg
```

{% endtab %}

{% tab title="422: Unprocessable Entity JSON" %}

```javascript
{
    "detail": "..."
}
```

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}
{% endtabs %}

## Download anonymized video

<mark style="color:blue;">`GET`</mark> `https://localhost/v1/file/{id}/video/anonymised`

Download anonymized video

#### Path Parameters

| Name | Type   | Description                                          |
| ---- | ------ | ---------------------------------------------------- |
| id   | String | The `id` (UUID) of the file that will be downloaded. |

{% tabs %}
{% tab title="200: OK video/mp4" %}
Media type: "video/mp4"
{% endtab %}

{% tab title="422: Unprocessable Entity JSON" %}

```
{
  "detail": "..."
}
```

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}
{% endtabs %}

## Download binary mask

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

#### Path Parameters

| Name                                 | Type   | Description                                                                    |
| ------------------------------------ | ------ | ------------------------------------------------------------------------------ |
| id<mark style="color:red;">\*</mark> | String | The `id` (UUID) of the file whose binary segmentation mask will be downloaded. |

#### Query Parameters

| Name       | Type   | Description                                                                                                                                        |
| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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> |

{% tabs %}
{% tab title="200: OK PNG" %}
Media type: image/png
{% endtab %}

{% tab title="422: Unprocessable Entity JSON" %}

```javascript
{
  "detail": "..."
}
```

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}
{% endtabs %}

For conceptual information on segmentation masks, see:

{% content-ref url="segmentation-masks-and-metadata" %}
[segmentation-masks-and-metadata](https://doc.celantur.com/container/usage/segmentation-masks-and-metadata)
{% endcontent-ref %}

## Download instance mask

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

#### Path Parameters

| Name | Type   | Description                                                                      |
| ---- | ------ | -------------------------------------------------------------------------------- |
| id   | String | The `id` (UUID) of the file whose instance segmentation mask will be downloaded. |

#### Query Parameters

| Name       | Type   | Description                                                                                                                                        |
| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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> |

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

```javascript
Media type: image/png
```

{% endtab %}

{% tab title="422: Unprocessable Entity JSON" %}

```javascript
{
    "detail": "..."
}
```

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}
{% endtabs %}

For conceptual information on segmentation masks, see:

{% content-ref url="segmentation-masks-and-metadata" %}
[segmentation-masks-and-metadata](https://doc.celantur.com/container/usage/segmentation-masks-and-metadata)
{% endcontent-ref %}

## Download image metadata (JSON)

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

#### Path Parameters

| Name                                 | Type   | Description                                                    |
| ------------------------------------ | ------ | -------------------------------------------------------------- |
| id<mark style="color:red;">\*</mark> | String | The `id` (UUID) of the file whose metadata will be downloaded. |

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

```json
{
  "id": "cc6198c8-c696-11ee-afbe-0242ac120002.jpg",
  "detections": [
    {
      "id": 0,
      "parent_image": "cc6198c8-c696-11ee-afbe-0242ac120002.jpg",
      "offset": [
        70,
        1796
      ],
      "bbox": [
        421,
        1805,
        597,
        1982
      ],
      "type": 103,
      "score": 0.999830961227417,
      "is_anonymised": true,
      "type_label": "face",
      "color": null
    }
  ],
  "size": [
    3000,
    4000
  ],
  "duration": 0.6000208689947613,
  "filename": "cc6198c8-c696-11ee-afbe-0242ac120002.jpg",
  "folder": "/tmp/input"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity JSON" %}

```
{
    "detail": "..."
}
```

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}
{% endtabs %}

## Download video metadata (JSON)

<mark style="color:blue;">`GET`</mark> `https://localhost/v1/file/{id}/video/metadata`

Returns the metadata for the specified range of frames of the last processed video as JSON.&#x20;

Consecutive frame IDs start at 0.

See [#video-metadata-example](https://doc.celantur.com/container/segmentation-masks-and-metadata#video-metadata-example "mention")

#### Path Parameters

| Name                                 | Type   | Description                                                     |
| ------------------------------------ | ------ | --------------------------------------------------------------- |
| id<mark style="color:red;">\*</mark> | String | The `id` (UUID) of the video whose metadata will be downloaded. |

#### Query Parameters

| Name                                           | Type   | Description                                                                                                                                                                            |
| ---------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| start\_frame<mark style="color:red;">\*</mark> | Number | <p>Specifies the first frame of the range of frames for which the metadata will be downloaded. Range: <code>0 .. last\_frame</code>.</p><p></p><p>Default: <code>0</code></p>          |
| end\_frame<mark style="color:red;">\*</mark>   | Number | <p>Specifies the last frame of the range of frames for which the metadata will be downloaded. Range: <code>1 .. last\_frame</code>.</p><p></p><p>Default: <code>last\_frame</code></p> |

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

<pre class="language-json"><code class="lang-json"><strong>[
</strong>  {
    "id": 0,
    "detections": [
      {
        "id": 0,
        "parent_image": 0,
        "offset": [
          1501,
          1280
        ],
        "bbox": [
          1504,
          1280,
          1563,
          1337
        ],
        "type": 103,
        "score": 0.8185984492301941,
        "is_anonymised": true,
        "type_label": "face",
        "color": null
      }
    ],
    "size": [
      2160,
      3840
    ],
    "duration": 0.3577723959897412
  },
  {
    "id": 1,
    "detections": [
      {
        "id": 0,
        "parent_image": 1,
        "offset": [
          1499,
          1283
        ],
        "bbox": [
          1513,
          1283,
          1574,
          1335
        ],
        "type": 103,
        "score": 0.8149935007095337,
        "is_anonymised": true,
        "type_label": "face",
        "color": null
      }
    ],
    "size": [
      2160,
      3840
    ],
    "duration": 0.3155565749912057
  },  ...
]
</code></pre>

{% endtab %}

{% tab title="422: Unprocessable Entity No video has been uploaded" %}

```
{
    "detail": "Upload a video file at v1/file before using this endpoint."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Image instead of video has been uploaded" %}

```
{
    "detail": "You can receive anonymised video metadata only after video upload"
}
```

{% endtab %}
{% endtabs %}

## Container and Task management

## Check Celantur Container status

<mark style="color:blue;">`GET`</mark> `https://localhost/v1/status`

Returns health status of of Celantur Container.\
200 when running, 500 when down.

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

```javascript
{
  "ts": "2024-02-08T15:35:43.853905",
  "api_version": "v1",
  "status": "RUNNING"
}
```

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}
{% endtabs %}

## List all processing tasks

<mark style="color:blue;">`GET`</mark> `https://localhost/v1/task/list`

{% tabs %}
{% tab title="200: OK JSON" %}
Returns a list of tasks.
{% endtab %}
{% endtabs %}

## Delete all existing tasks&#x20;

<mark style="color:red;">`DELETE`</mark> `https://localhost/v1/task/list`

Delete all the tasks' records and/or input and output files.

#### Query Parameters

| Name         | Type    | Description                                                                                                                                                              |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| confirm      | Boolean | Provide true to confirm your action.                                                                                                                                     |
| delete-scope | String  | <p><code>task-and-files</code> to delete everything. <br><code>only-files</code> to delete only files, keeping the records.<br>Default: <code>task-and-files</code> </p> |

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

```json
{ "result": "success", "message": "string" }
```

{% endtab %}

{% tab title="422: Unprocessable Entity " %}

{% endtab %}
{% endtabs %}

## Get information about a specific task

<mark style="color:blue;">`GET`</mark> `https://localhost/v1/task/{id}`

#### Path Parameters

| Name                                 | Type   | Description                                                                                                   |
| ------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------- |
| id<mark style="color:red;">\*</mark> | String | task / upload **id** (UUID) that is part of the response from [#upload-file](#upload-file "mention") request. |

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

```json
{ "result": "success", "message": "string" }
```

{% endtab %}
{% endtabs %}

## Delete a specific task

<mark style="color:red;">`DELETE`</mark> `https://localhost/v1/task/{id}`

Remove the record and/or input and output files of a specific task.

#### Path Parameters

| Name                                 | Type   | Description                                                                                                   |
| ------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------- |
| id<mark style="color:red;">\*</mark> | String | task / upload **id** (UUID) that is part of the response from [#upload-file](#upload-file "mention") request. |

#### Query Parameters

| Name         | Type   | Description                                                                                                                                                             |
| ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| delete-scope | String | <p><code>task-and-files</code> to delete everything. <br><code>only-files</code> to delete only files, keeping the records.<br>Default: <code>task-and-files</code></p> |

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

```json
{ "result": "success", "message": "string" }
```

{% endtab %}
{% endtabs %}

## Examples

### Check server status

Check the server status by sending a GET request to the [#checks-celantur-container-status](#checks-celantur-container-status "mention")endpoint:

```bash
curl -i -X GET 'http://127.0.0.1:7000/v1/status'
```

{% code title="Response" %}

```json
{
  "ts": "2024-02-08T15:35:43.853905",
  "api_version": "v1",
  "status": "RUNNING"
}
```

{% endcode %}

### Anonymize images

#### Post image to pixelate faces

{% code overflow="wrap" %}

```bash
curl -i -X POST 'http://127.0.0.1:7000/v1/file?method=pixelate&face=True' -F 'fileobject=@/path/to/original-image.jpg'
```

{% endcode %}

#### Post image to blur blur whole persons and show debug information

{% code overflow="wrap" %}

```bash
curl -i -X POST 'http://127.0.0.1:7000/v1/file?method=blur&debug=True&person=True' -F 'fileobject=@/path/to/original-image.jpg'
```

{% endcode %}

Post method returns image id with GET request links:

{% code title="JSON Response" %}

```json
{
    "content-type": "image/jpeg",
    "id": "{image_id}",
    "metadata-url": "http://localhost:7000/v1/file/{image_id}/metadata",
    "binary-mask-url": "http://localhost:7000/v1/file/{image_id}/binary-mask",
    "instance-mask-url": "http://localhost:7000/v1/file/{image_id}/instance-mask",
    "anonymised-url": "http://localhost:7000/v1/file/{image_id}/anonymised"
}
```

{% endcode %}

#### Download anonymized image

{% code overflow="wrap" %}

```bash
curl -X GET http://127.0.0.1:7000/v1/file/{image_id}/anonymised --output /path/to/anonymised-image.jpg
```

{% endcode %}

![](https://1992407480-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fr2aH3h1rP4SjkhFlr7Mp%2Fuploads%2FXXgASi0O6q3Bezfjwnit%2Fimage.png?alt=media\&token=7aa46ca6-f9b7-4908-b703-991be92029e9)

![](https://1992407480-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fr2aH3h1rP4SjkhFlr7Mp%2Fuploads%2FOPE0r7fldAjpsitewkGx%2Fimage.png?alt=media\&token=570cb361-f2e0-4e68-9691-212df64b634d)

**Photo Credits:** [Omar Lopez](https://unsplash.com/photos/rwF_pJRWhAI) on [Unsplash](https://unsplash.com/)

#### Download segmentation mask

{% code overflow="wrap" %}

```bash
curl -X GET http://127.0.0.1:7000/v1/file/{image_id}/binary-mask --output /path/to/binary-mask.png
```

{% endcode %}

#### ![](https://1992407480-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fr2aH3h1rP4SjkhFlr7Mp%2Fuploads%2FRHsfrfkqY0R1pfdZqTvg%2Fimage.png?alt=media\&token=bf777cbe-ca2a-490a-8c75-5d2bfcb4390c)

#### Download instance segmentation mask

{% code overflow="wrap" %}

```bash
curl -X GET http://127.0.0.1:7000/v1/file/{image_id}/instance-mask --output /path/to/instance-mask.png
```

{% endcode %}

#### Download downscaled instance segmentation mask

{% code overflow="wrap" %}

```bash
curl -X GET http://127.0.0.1:7000/v1/file/{image_id}/instance-mask?mask-scale=50 --output /path/to/instance-mask.png
```

{% endcode %}

![](https://1992407480-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fr2aH3h1rP4SjkhFlr7Mp%2Fuploads%2FtmA6O2dsTXUFBhwKuBet%2Fimage.png?alt=media\&token=97d3792f-f6e2-4cc2-8175-9e11fc51e4e1)

#### Download metadata

```bash
curl -X GET http://127.0.0.1:7000/v1/file/{image_id}/metadata
```

```json
{
    "id": "omar-lopez-rwF_pJRWhAI-unsplash.jpg",
    "detections": [
    {
        "id": 0,
        "parent_image": "omar-lopez-rwF_pJRWhAI-unsplash.jpg",
        "offset": [
            1560,
            744
        ],
        "bbox": [
            1957,
            744,
            3003,
            1855
        ],
        "type": 103,
        "score": 0.9993754029273987,
        "is_anonymised": true,
        "type_label": "face",
        "color": null
    },
    {
        "id": 1,
        "parent_image": "omar-lopez-rwF_pJRWhAI-unsplash.jpg",
        "offset": [
            2682,
            760
        ],
        "bbox": [
            3091,
            760,
            4078,
            1680
        ],
        "type": 103,
        "score": 0.9989292025566101,
        "is_anonymised": true,
        "type_label": "face",
        "color": null
    },
    {
    "id": 0,
        "parent_image": "omar-lopez-rwF_pJRWhAI-unsplash.jpg",
        "offset": [
            3736,
            712
        ],
        "bbox": [
            4015,
            758,
            4777,
            1520
        ],
        "type": 103,
        "score": 0.9988161325454712,
        "is_anonymised": true,
        "type_label": "face",
        "color": null
    }
    ],
    "size": [
        3456,
        5184
    ],
    "duration": 1.8533296539999355,
    "filename": "omar-lopez-rwF_pJRWhAI-unsplash.jpg",
    "folder": null
}
```
Parameter	Description
`--api`	Start container in REST API mode.
`--api-endpoint URL`	Specify the API endpoint that is returned with the requests. URL for downloading the anonymised images, binary masks and metadata.