REST API (v1) mode

REST API mode for Celantur Container

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.

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.

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.

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

Video processing

For video processing, use the newer segmentatio-omnium model (--model segmentatio-omnium) for faster processing speed. Currently, it only supports face and license plate blurring.

bash celantur.sh --api --api-endpoint http://localhost:7000/ -a face -a license-plate --format whole --model segmentatio-omnium

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.

Metadata, binary and instance segmentation masks are not yet supported for videos.

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.

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

1. Upload image with POST request Upload file. Processing is ready once the request returns with a successful response.

2. Download image with GET request Download anonymized image

3. Download segmentation masks and metadata:

   1. GET request Download binary mask

   2. GET request Download instance mask

   3. GET request Download image metadata (JSON)

Asynchronous processing

1. Upload image with POST request Upload file 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

3. Download the assets as in #aynchronous-processing.

4. Delete the task with Delete a specific task

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 .

Image and video anonymization

Upload file

POST 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*	String	Enum: blur, pixelate, blacken, detect Default: blur Specifies processing method. Method detect only returns segmentation and binary masks, not an anonymized image.
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	Default: "whole" Example: format={"number": [2,2], "overlap": [0, 0]} Tiling of the input image
ignores	String	Default: ""Example: ignores=[{"topLeftX": 182,"topLeftY": 154,"width":2000,"height":2000}] Areas of the image that are not going to be anonymized
face-threshold	Number	Specifies detection threshold 0..1 for faces. Default: 0.5
segmentation-threshold	Number	DEPRECATED Specifies detection threshold value for segmentation. ▶ Use person-threshold and vehicle-threshold instead.
vehicle-threshold	Number	Specifies detection threshold 0..1 for vehicles. Default: 0.4
person-threshold	Number	Specifies detection threshold 0..1 for persons. Default: 0.4
license-plate-threshold	Number	Specifies detection threshold 0..1 for license plates. Default: 0.5
no-object-tracking	Boolean	Disables object tracking in videos, which is enabled by default. See Object Tracking
keep-bit-rate	Boolean	Specifies whether the bitrate of the anonymized video should remain very close to the one of the original video. Enabling keep-bit-rate will ensure a nearly identically file size of the processed video, at the cost of 10% to 20% higher processing time. Default: false
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	Enables async processing. Values: true or false Default: false

Request Body

Name	Type	Description
fileobject*	string<binary> (Fileobject)	Images: fileobject=@/path/to/input/image; See Supported image formats Videos: Specify the video type fileobject=@/path/to/input/video;type=video/mp4 See Supported video codecs

200: OK JSON (image upload)

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

422: Unprocessable Entity JSON

{
  "detail": "..."
}

500: Internal Server Error

200: OK JSON (video uplaod)

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

Download anonymized image

GET https://localhost/v1/file/{id}/anonymised

Download anonymized image

Path Parameters

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

Query Parameters

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

200: OK JPEG or PNG

Media type: image/png or image/jpeg

422: Unprocessable Entity JSON

{
    "detail": "..."
}

500: Internal Server Error

Download anonymized video

GET 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.

200: OK video/mp4

Media type: "video/mp4"

422: Unprocessable Entity JSON

{
  "detail": "..."
}

500: Internal Server Error

Download binary mask

GET https://localhost/v1/file/{id}/binary-mask

Path Parameters

Name	Type	Description
id*	String	The id (UUID) of the file whose binary segmentation mask will be downloaded.

Query Parameters

Name	Type	Description
mask-scale	Number	Specifies the ratio at which the mask file will be scaled down, range between 0 .. 100. Default: 100

200: OK PNG

Media type: image/png

422: Unprocessable Entity JSON

{
  "detail": "..."
}

500: Internal Server Error

For conceptual information on segmentation masks, see:

Segmentation Masks and Metadata

Download instance mask

GET 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	Specifies the ratio at which the mask file will be scaled down, range between 0 .. 100. Default: 100

200: OK PNG

Media type: image/png

422: Unprocessable Entity JSON

{
    "detail": "..."
}

500: Internal Server Error

For conceptual information on segmentation masks, see:

Segmentation Masks and Metadata

Download image metadata (JSON)

GET https://localhost/v1/file/{id}/metadata

Path Parameters

Name	Type	Description
id*	String	The id (UUID) of the file whose metadata will be downloaded.

200: OK 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"
}

422: Unprocessable Entity JSON

{
    "detail": "..."
}

500: Internal Server Error

Download video metadata (JSON)

GET https://localhost/v1/file/{id}/video/metadata

Returns the metadata for the specified range of frames of the last processed video as JSON.

Consecutive frame IDs start at 0.

See Video metadata example

Path Parameters

Name	Type	Description
id*	String	The id (UUID) of the video whose metadata will be downloaded.

Query Parameters

Name	Type	Description
start_frame*	Number	Specifies the first frame of the range of frames for which the metadata will be downloaded. Range: 0 .. last_frame. Default: 0
end_frame*	Number	Specifies the last frame of the range of frames for which the metadata will be downloaded. Range: 1 .. last_frame. Default: last_frame

200: OK Metadata

[
  {
    "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
  },  ...
]

422: Unprocessable Entity No video has been uploaded

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

422: Unprocessable Entity Image instead of video has been uploaded

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

Container and Task management

Check Celantur Container status

GET https://localhost/v1/status

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

200: OK JSON

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

500: Internal Server Error

List all processing tasks

GET https://localhost/v1/task/list

200: OK JSON

Returns a list of tasks.

Delete all existing tasks

DELETE 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	task-and-files to delete everything. only-files to delete only files, keeping the records. Default: task-and-files

200: OK JSON

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

422: Unprocessable Entity

Get information about a specific task

GET https://localhost/v1/task/{id}

Path Parameters

Name	Type	Description
id*	String	task / upload id (UUID) that is part of the response from Upload file request.

200: OK JSON

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

Delete a specific task

DELETE https://localhost/v1/task/{id}

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

Path Parameters

Name	Type	Description
id*	String	task / upload id (UUID) that is part of the response from Upload file request.

Query Parameters

Name	Type	Description
delete-scope	String	task-and-files to delete everything. only-files to delete only files, keeping the records. Default: task-and-files

200: OK JSON

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

Examples

Check server status

Check the server status by sending a GET request to the #checks-celantur-container-statusendpoint:

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

Response

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

Anonymize images

Post image to pixelate faces

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

Post image to blur blur whole persons and show debug information

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'

Post method returns image id with GET request links:

JSON Response

{
    "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"
}

Download anonymized image

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

Photo Credits: Omar Lopez on Unsplash

Download segmentation mask

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

Download instance segmentation mask

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

Download downscaled instance segmentation mask

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

Download metadata

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

{
    "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
}