API Endpoints

Celantur Cloud API v2 endpoints

Overview

API URL:

https://api.celantur.com/v2/

Celantur Cloud API supports only images at the moment. Support for videos will be added soon.

Create anonymization task

POST https://api.celantur.com/v2/task

Creates a task for anonymizing images.

Uploading an image to the upload_url starts the anonymization process. If the file uploaded to the upload_url is not the content type image/jpeg or image/png the task status will be set to failed along with the failure cause CONTENT_TYPE_ERROR

Required parameters for a task are anonymization_method and either face, person, license_plate or vehicle.

Headers

Name	Type	Description
Authorization*	String	Authorization token

Request Body

Name	Type	Description
anonymization_method*	String	Specifies anonymization method: blur, pixelate, blacken
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.
debug	Boolean	Print bounding boxes and segmentation masks of detected objects on the image. Default: false
score	Boolean	Print the detection scores of objects on the image. Works only if debug is true
format	String	Specifies the resolution of the input images and subsequently uses optimized parameter presets for the image processing (e.g. "pano:8000" for an image resolution of 8000x4000). Parameter: Resolution "whole": default, valid for all resolutions "pano:4096": 4096x2048 "pano:5400": 5400x2700 "pano:5640": 5640x2816 "pano:7060": 7060x3530 "pano:7680": 7680x3840 "pano:8000": 8000x4000 "pano:7680": 7680x3840 "pano:8000": 8000x4000 "pano:8192": 8192x4096 "pano:11000": 11000x5500
bbox	Boolean	Anonymize bounding boxes of objects (instead of segmentation).
ignores	String	Specifies pixel coordinates of areas on the image in which no anonymization will be applied (as JSON). Example: [{"topLeftX":182, "topLeftY":154, "width":2000, "height":2000}]
webhook	String	A webhook URL to which a POST request is sent to after successful processing. More details here: Webhooks
start_on	String	Specifies whether the anonymization process of this task should start when a file has been uploaded (upload), or a request has been sent (start_request) to POST v2/task/{id}/start. Example: start_on: "start_request" Default: upload
binary_segmentation_mask	Boolean	Specifies whether a binary segmentation mask should be generated for the provided file.
instance_segmentation_mask	Boolean	Specifies whether an instance segmentation mask should be generated for the provided file.
mask-scale	Number	Specifies the ratio at which the mask file will be scaled down, range between 0 .. 100. Default: 100
quality	Number	Specifies image quality of anonymized images in JPEG format: 0 .. 100 Default: 90
compress-level	Number	Specifies image compression level of anonymized images in PNG format. Default: 5
kernel-size-face	Number	Specifies the kernel size for face blurring. See Customize Blurring Default: 0.35
kernel-size-person	Number	Specifies the kernel size for person blurring. See Customize Blurring Default: 95
kernel-size-license-plate	Number	Specifies the kernel size for license plate blurring. See Customize Blurring Default: 0.5
kernel-size-vehicle	Number	Specifies the kernel size for vehicle blurring. See Customize Blurring Default: 61
face-anonymization-gradient-start	Number	Specifies the gradient start value for face blurring. See Customize Blurring Default: 0.3
face-anonymization-gradient-stop	Number	Specifies the gradient stop value for face blurring. See Customize Blurring Default: 0.0
license-plate-anonymization-gradient-start	Number	Specifies the gradient start value for license plate blurring. See Customize Blurring Default: 0.3
license-plate-anonymization-gradient-stop	Number	Specifies the gradient stop value for license plate blurring. See Customize Blurring Default: 0.0
face_threshold	Float	Specifies detection threshold from 0..1 for faces. Default: 0.5
vehicle_threshold	Float	Specifies detection threshold from 0..1 for vehicles. Default: 0.4
person_threshold	Float	Specifies detection threshold from 0..1 for persons. Default: 0.4
license_plate_threshold	Float	Specifies detection threshold from 0..1 for license plates. Default: 0.5

200: OK Response body with JSON

Response body JSON containing file information and parameters:

{
'customer_id': '2c46d468-ee8c-4317-b4d4-aff8462f4543', 
'task_id': 1690264444814157, 
'create_time': '2023-07-25T05:54:04.814157', 
'delete_time': None, 
'name': None, 
'debug': False, 
'score': False, 
'anonymization_method': 'blur', 
'face': True, 
'license_plate': False, 
'person': False, 
'vehicle': False, 
'format': 'whole', 
'bbox': False, 
'ignores': '', 
'mask_scale': 100, 
'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': None, 
'start_on': 'upload', 
'extraction_types': None, 
'binary_segmentation_mask': False,
'instance_segmentation_mask': False,
'face_threshold': 0.5, 
'vehicle_threshold': 0.4, 
'person_threshold': 0.4, 
'license_plate_threshold': 0.5, 
'task_status': 'new', 
'webhook_status': set, 
'upload_url': 'https://cloudapi-customer-uploads-v2-prod-eu-central-1.s3.amazonaws.com/xxx-xxxx-xxxx-xxxx-xxxx/xxxxxxxx/1/original?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxx%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20230725T055404Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Security-Token=xxx……', 
'upload_url_expiration_duration': 3600
}

400: Bad Request Parameter doesn

{
"status_code":400, 
"error": "Could not create task. {parameter} parameter caused an error. This parameter does not exist."
}

400: Bad Request Parameter received unexpected value

{
"status_code":400, 
"error": "Could not create task. {parameter} parameter received an unexpected value."
}

400: Bad Request Parameter value value caused an error

{
"status_code":400, 
"error": "Could not create task. {parameter} parameter value caused an error. {Error cause}"
}

400: Bad Request Request body is not correct

{
"status_code":400, 
"error": "Could not create task. Request body is not correct. {Error cause}"
}

400: Bad Request JSON body missing

{
"status_code":400, 
"error": "Could not create task. Please add a JSON body."
}

400: Bad Request Task files are deleted

{
"status_code": 404,
"error": "Task is deleted. Please upload a new task."
}

500: Internal Server Error

{
"status_code":500, 
"error": "An unexpected error occurred. If the problem persists, please contact Celantur support ([e-mail])."
}

Get task

GET https://api.celantur.com/v2/task/{id}

Retrieve a specific task. The anonymized_url is included in the response body in case the task_status is done and the anonymized image can be downloaded.

In case the task failed, the task_status is set to failed and a "failure_cause" property will be added to the response body.

Path Parameters

Name	Type	Description
id*	String	id of the task

Headers

Name	Type	Description
Authorization	String	Authorization

200: OK Task as JSON

{
    "task_id": "1692464405235520",
    "create_time": "2023-07-27T13:25:05.295539",
    "delete_time": null,
    "debug": false,
    "score": false,
    "anonymization_method": "blur",
    "face": true,
    "license_plate": false,
    "person": false,
    "vehicle": false,
    "format": "whole",
    "bbox": false,
    "ignores": "",
    "mask_scale": "100",
    "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",
    "license_plate_anonymization_gradient_start": "0.3",
    "license_plate_anonymization_gradient_stop": "0",
    "start_on": "upload",
    "extraction_types": [],
    "face_threshold": "0.9",
    "vehicle_threshold": "0.4",
    "person_threshold": "0.4",
    "license_plate_threshold": "0.5",
    "original_url": "https://cloudapi-customer-uploads-v2-dev-eu-central-1.s3.amazonaws.com/xxx-xxx-xxx-xxx-xxxx/xxxxx/1/original?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxxF%2F20230727%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20230727T132849Z&X-Amz-Expires=14400&X-Amz-SignedHeaders=host&X-Amz-Security-Token=xxxx……..",
    "anonymized_url": "https://cloudapi-customer-uploads-v2-dev-eu-central-1.s3.amazonaws.com/xxxx-xxx-xxxx-xxxx-xxxxx/xxxxxxxxxx/1/anonymized.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxxx%2F20230727%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20230727T132849Z&X-Amz-Expires=14400&X-Amz-SignedHeaders=host&X-Amz-Security-Token=xxxxx……",
"anonymized_url_expiration_duration": 14400
	"webhook": "https://example.com/webhook/dev?param=test",
"webhook_status": "sent",
"binary_segmentation_mask": true,
"instance_segmentation_mask": true,
"binary_segmentation_mask_url": "https://cloudapi-customer-uploads-v2-dev-eu-central-1.s3.amazonaws.com/xxx-xxx-xxx-xxx-xxxx/xxxxx/1/original?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxxF%2F20230727%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20230727T132849Z&X-Amz-Expires=14400&X-Amz-SignedHeaders=host&X-Amz-Security-Token=xxxx…",
  "instance_segmentation_mask_url": "https://cloudapi-customer-uploads-v2-dev-eu-central-1.s3.amazonaws.com/xxx-xxx-xxx-xxx-xxxx/xxxxx/1/original?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxxF%2F20230727%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20230727T132849Z&X-Amz-Expires=14400&X-Amz-SignedHeaders=host&X-Amz-Security-Token=xxxx……",
"metadata_url": "https://api.celantur.com/v2/task/xxxxxxxxxxxxxxxx/metadata"
}

200: OK Task as JSON with task failure cause

{
	"task_id": task_id,
	…
	"task_status": "failed",
	"failure_cause": "IMAGE_DEFECT|TASK_FILE_DOESNT_EXIST|INTERNAL_ERROR|CONTENT_TYPE_ERROR"
}

400: Bad Request MIssing task ID

{
"status_code":400, 
"error": "Getting task results failed. Please enter a task ID."
}

400: Bad Request Task ID not an integer

{
"status_code":400, 
"error": "Wrong format for Task ID. {task_id} is not an integer."
}

400: Bad Request No task with specified task ID found

{
    "status_code":400, 
    "error": "Task ID not found. There is no task with task ID {task_id}."
}

500: Internal Server Error Unexpected error

{
"status_code":500, 
"error": "An unexpected error occurred. If the problem persists, please contact Celantur support ([e-mail])."
}

Get task status

GET https://api.celantur.com/v2/task/{id}/status

Returns the status of the specified task. The anonymized_url is included in the response body in case the task_status is “done” and the anonymized image can be downloaded.

In case the task failed, the task_status is set to failed and a "failure_cause" property will be added to the response body.

Path Parameters

Name	Type	Description
id*	String	id of the task

Headers

Name	Type	Description
Authorization*	String	Authorization token

200: OK Task status

{
"task_id": 1690464305295539,
"task_status": "done",
"delete_time": null, 
"webhook": "https://example.com/webhook/dev?param=test",
"webhook_status": "sent",
"anonymized_url": "https://cloudapi-customer-uploads-v2-dev-eu-central-1.s3.amazonaws.com/6b6986c2-20ee-45f9-b8b0-bb56c10cb6c0/1642464305211532/1/anonymized.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAVKZ73AQDDJGIR2DP%2F20230727%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20230727T133010Z&X-Amz-Expires=14400&X-Amz-SignedHeaders=host&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEMb%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDGV1LWNlbnRyYWwtMSJGMEQCIDOIQJSmlTa7ih%2F0Diy%2FEiAGTb4lEXo%2B17PxaPn0kDBjAiBDEfQp2iGNPENpbKrvlBBPVrg8hbAz2LQ8jm…E2wPUG3NN9HF2czMOJgRipr4jGlBX1P0xXH%2FWRy5ztcPmW1WOfxXRbuq637uqmTDdIR%2F55oq8zTLaFZ5TRDDh4ommBjqfAYPDyQCDbX0HdhPY5az54JKHKyov3OjEIgrLINWfFxlplHp5GK4RMNbsfA0%2Fusqt0JGwhIyb8kMz7jGEgzPLuOlEle89XwmhZP9gGaJy7oe8bJQK3t6ikuArv8BphnKfiLkP%2BSZc%2Bn%2BhGCT3sMxc9w5LtjzfNz33oYro2NkORSRCLdeTLEBBpRHAEX4ZlhxDEJr5QSAWGx7ceb7GWqcfqQ%3D%3D&X-Amz-Signature=d3e1e3e6ecbbba5457927a1236fd9251bcd762d2e43fa4969bb10481d57d79a9",
    "anonymized_url_expiration_duration": 14400,
"metadata_url": "https://api.celantur.com/v2/task/xxxxxxxxxxxxxxxx/metadata"
}

200: OK Task status for failed task with failure cause

{
	"task_id": task_id,
	…
	"task_status": "failed",
	"failure_cause": "IMAGE_DEFECT|TASK_FILE_DOESNT_EXIST|INTERNAL_ERROR|CONTENT_TYPE_ERROR"
}

400: Bad Request No task with specified task ID found

{
"status_code":400, 
"error": "Task ID not found. There is no task with task ID {task_id}."
}

400: Bad Request Task ID is not an interger

{
"status_code":400, 
"error": "Wrong format for Task ID. {task_id} is not an integer."
}

500: Internal Server Error Unexpected error

{
"status_code":500, 
"error": "An unexpected error occurred. If the problem persists, please contact Celantur support ([e-mail])."
}

Get task metadata

GET https://api.celantur.com/v2/task/{id}/metadata

Returns the metadata of the specified task. Metadata contain a detections property containing a list of detections of the corresponding file.

204 with an empty body is returned when :

- No detections where found

- The task has not finished processing yet

- The task failed

Path Parameters

Name	Type	Description
id*	String	id of the task

Headers

Name	Type	Description
Authorization*	String	Authorization token

200: OK Task metadata with detections

{
    "task_id": 1693905790526783,
    "detections": [
        {
            "score": 0.9993058443069458,
            "offset": [
                443.0,
                533.0
            ],
            "color": null,
            "bbox": [
                619.0,
                639.0,
                794.0,
                813.0
            ],
            "parent_image": "",
            "id": 0.0,
            "type_label": "face",
            "type": 103.0,
            "is_anonymised": true
        },
      ...
    ]
}

204: No Content No detections, task_status failed or task has not finished processing yet

400: Bad Request No task with specified task ID found

{
"status_code":400, 
"error": "Task ID not found. There is no task with task ID {task_id}."
}

400: Bad Request Task ID is not an integer

{
"status_code":400, 
"error": "Wrong format for Task ID. {task_id} is not an integer."
}

500: Internal Server Error Unexpected error

{
"status_code":500, 
"error": "An unexpected error occurred. Please try creating a task again. If the problem persists, please contact Celantur support ([e-mail])."
}

List tasks

GET https://api.celantur.com/v2/task/list

List tasks and filter by creation time and task status.

Use pagination by specifying the next_page_key parameter.

Query Parameters

Name	Type	Description
create_time_before*	String	Filter: Return tasks which were created before the specified date. Format: YYYY-MM-DD
create_time_after*	String	Filter: Return tasks which were created after the specified date. Format: YYYY-MM-DD
task_status	String	Filter by specified task status. Has to be either "new", "queued", "processing", "done" or "failed". Default: None
next_page_key	String	The task_id that specifies the starting position of a page. The task with the provided task_id is not part of the page.
limit	Number	Maximum number of tasks on a page. If the parameter is smaller than the minimum or larger than the maximum the parameter will automatically be set to minimum or maximum value. Minimum: 10 Maximum: 300 Default: 10

Headers

Name	Type	Description
Authorization*	String	Authorization token

200: OK

{
    "limit": 5,
    "count": 5,
    "next_page_key": 1689161781804287,
    "items": [
        {
            "task_id": 1689161328607410,
            "create_time": "2023-07-12T11:28:48.607410",
            "task_status": "done"
        },
        {
            "task_id": 1689161451227087,
            "create_time": "2023-07-12T11:30:51.227087",
            "task_status": "done"
        },
        {
            "task_id": 1689161743300320,
            "create_time": "2023-07-12T11:35:43.300320",
            "task_status": "done"
        },
        {
            "task_id": 1689161768856287,
            "create_time": "2023-07-12T11:36:08.856287",
            "task_status": "done"
        },
        {
            "task_id": 1689161781804287,
            "create_time": "2023-07-12T11:36:21.804287",
            "task_status": "done"
        }
    ]
}

400: Bad Request Format error of create_time_before/create_time_after

{
    "status_code": 400,
    "error": "Please enter a properly formatted time for the create_time_before value. Correct format:  YYYY-MM-DD"
}

400: Bad Request Wrong task_id format

{
    "status_code": 400,
    "error": "Wrong format for task_id. Please enter an integer."
}

400: Bad Request Wrong task_status

{
    "status_code": 400,
    "error": "Please enter a correct task_status. Task status value can only be one of ['new', 'queued', 'processing', 'done', 'failed']"
}

400: Bad Request create_time_* parameters are missing

{
    "status_code": 400,
    "error": "No create_time_* parameters have been specified."
}

400: Bad Request create_time_after parameter is later than or equal to create_time_before

{
    "status_code": 400,
    "error": "Please check your create_time_* parameters. create_time_after can not be 
              later than/equal to create_time_before."
}

500: Internal Server Error Unexpected error

{
    "status_code": 500,
    "error": "An unexpected error occurred. If the problem persists, please contact Celantur support ([e-mail])."
}

Sign in (authorization)

POST https://api.celantur.com/v2/signin

Provide your username and password credentials (of your app.celantur.com account) as a JSON payload to authenticate, and receive your AccessToken to use Celantur Cloud API.

{ "username": "[e-mail]", "password": "password" }

Request Body

Name	Type	Description
username*	String	Username as JSON property
password*	String	Password as JSON property

200: OK Authentication result

{
    "AccessToken": "eyJraWQiOiJr…Wa_CNpFRyNIjbt5qjAED1-oH8pEKpO-KPTttuSGHw",
    "ExpiresIn": 3600,
    "TokenType": "Bearer",
    "RefreshToken": "eyJjd...t8OWzmXJpmPnuNbBzr1vPA",
    "IdToken": "eyJraWQiOiI1aTlFa…ZIttv0gNRJRp39LvyzAn5LJWJBw7Ju8szRRBA"
}

400: Bad Request Incorrect username or password

{
   "message": "Incorrect username or password.",
   "code": "NotAuthorizedException",
   "time": "2023-07-31T07:13:56.569Z",
   "requestId": "ce5c6036-18de-4476-9388-59ddcded7943",
   "statusCode": 400,
   "retryable": false,
   "retryDelay": 57.558191461534605
}

Delete task files.

DELETE https://api.celantur.com/v2/task/{id}/files

Deletes the files and detections associated with the specified task.

In case the task files are already deleted, any newly uploaded files through upload URL will also be deleted.

Path Parameters

Name	Type	Description
id*	String	id of the task

Headers

Name	Type	Description
Authorization*	String	Authorization token

200: OK Task deleted

{
"files_deleted": true,
"task_id": "{task_id}"
}

400: Bad Request Task is already deleted

{
"status_code": 400,
"error": "Task with ID 1696335137350403 already deleted."
}

400: Bad Request No task with specified task ID found

{
"status_code":400, 
"error": "Task ID not found. There is no task with task ID {task_id}."
}

400: Bad Request Task ID is not an interger

{
"status_code":400, 
"error": "Wrong format for Task ID. {task_id} is not an integer."
}

500: Internal Server Error Unexpected error

{
"status_code":500, 
"error": "An unexpected error occurred. If the problem persists, please contact Celantur support ([e-mail])."
}