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.
Video processing
For video processing, use the object detection model (--model object-detection-v2
) for faster processing speed. Currently, it only supports face and license plate blurring.
Task and files
There are two classes of endpoints:
/file
endpoints where you can upload and download files. When you upload a file withPOST /file
you will receive a JSON response including{ "id": "string", ... }
. You can use the id to query the status of processing viaGET /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 theDELETE /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):
Sychronous processing
Upload image with POST request Upload file. Processing is ready once the request returns with a successful response.
Download image with GET request Download anonymized image
Download segmentation masks and metadata:
GET request Download binary mask
GET request Download instance mask
GET request Download image metadata (JSON)
Asynchronous processing
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.Wait until processing is done.
Webhook: If you added webhook, you'll receive notification, once the processing is complete.
Otherwise query the task status with List all processing tasks
Download the assets as in #aynchronous-processing.
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: Default: Specifies processing method. Method |
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 Default: |
segmentation-threshold | Number | DEPRECATED Specifies detection threshold value for segmentation. ▶ Use |
vehicle-threshold | Number | Specifies detection threshold Default: |
person-threshold | Number | Specifies detection threshold Default: |
license-plate-threshold | Number | Specifies detection threshold Default: |
no-object-tracking | Boolean | Disables object tracking in videos. Default: |
keep-bit-rate | Boolean | Specifies whether the bitrate of the anonymized video should remain very close to the one of the original video. Enabling |
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: Default: |
Request Body
Name | Type | Description |
---|---|---|
fileobject* | string<binary> (Fileobject) | Images:
Videos: Specify the video type
|
Download anonymized image
GET
https://localhost/v1/file/{id}/anonymised
Download anonymized image
Path Parameters
Name | Type | Description |
---|---|---|
id* | String | The |
Query Parameters
Name | Type | Description |
---|---|---|
download | String | Enum: Whether the image should be downloaded as a JPEG or PNG. |
quality | Number | Specifies quality level for JPEG images ranging from Default: |
compress-level | Number | Specifies compression level for PNG images ranging from Default: |
Download anonymized video
GET
https://localhost/v1/file/{id}/video/anonymised
Download anonymized video
Path Parameters
Name | Type | Description |
---|---|---|
id | String | The |
Media type: "video/mp4"
Download binary mask
GET
https://localhost/v1/file/{id}/binary-mask
Path Parameters
Name | Type | Description |
---|---|---|
id* | String | The |
Query Parameters
Name | Type | Description |
---|---|---|
mask-scale | Number | Specifies the ratio at which the mask file will be scaled down, range between Default: |
Media type: image/png
For conceptual information on segmentation masks, see:
Segmentation Masks and MetadataDownload instance mask
GET
https://localhost/v1/file/{id}/instance-mask
Path Parameters
Name | Type | Description |
---|---|---|
id | String | The |
Query Parameters
Name | Type | Description |
---|---|---|
mask-scale | Number | Specifies the ratio at which the mask file will be scaled down, range between Default: |
For conceptual information on segmentation masks, see:
Segmentation Masks and MetadataDownload image metadata (JSON)
GET
https://localhost/v1/file/{id}/metadata
Path Parameters
Name | Type | Description |
---|---|---|
id* | String | The |
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.
Path Parameters
Name | Type | Description |
---|---|---|
id* | String | The |
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: Default: |
end_frame* | Number | Specifies the last frame of the range of frames for which the metadata will be downloaded. Range: Default: |
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.
List all processing tasks
GET
https://localhost/v1/task/list
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 |
|
Get information about a specific task
GET
https://localhost/v1/task/{id}
Path Parameters
Name | Type | Description |
---|---|---|
id* | 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 |
Query Parameters
Name | Type | Description |
---|---|---|
delete-scope | String |
|
Examples
Check server status
Check the server status by sending a GET request to the #checks-celantur-container-statusendpoint:
Anonymize images
Post image to pixelate faces
Post image to blur blur whole persons and show debug information
Post method returns image id with GET request links:
Download anonymized image
Photo Credits: Omar Lopez on Unsplash
Download segmentation mask
Download instance segmentation mask
Download downscaled instance segmentation mask
Download metadata
Last updated