API Endpoints

Celantur Cloud API endpoints

Overview

API URL:

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

Celantur Cloud API anonymizes images and videos.

Images: JPEG (image/jpeg) and PNG (image/png). Maximum size: 100 MiB.

Videos: MP4 (video/mp4), QuickTime/MOV (video/quicktime) and AVI (video/x-msvideo). Maximum size 1 GB, duration 10 minutes, 18,000 frames, and 4K (3,840 px on the longest side).

See Supported files for details.

Create anonymization task

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

Creates a task for anonymizing images or videos.

Uploading a file to the upload_url starts the anonymization process (unless start_on is start_request). Use content-type image/jpeg or image/png for images, and video/mp4, video/quicktime or video/x-msvideo for videos. If the uploaded file is not a supported type, the task status will be set to failed along with the failure cause CONTENT_TYPE_ERROR or IMAGE_DEFECT.

Required parameters for a task are anonymization_method and at least one of 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 how the input image is to be tiled. See Format / Tiling for more information. Pass pre-defined tiling as string, e.g. "pano:8000", and custom tiling as object, e.g. {"number": [2, 2], "overlap": [0, 0]}

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 Start anonymization task.

Example:

start_on: "start_request"

Default: upload

binary_segmentation_mask

Boolean

Specifies whether a binary segmentation mask should be generated. Image tasks only; ignored for videos.

instance_segmentation_mask

Boolean

Specifies whether an instance segmentation mask should be generated. Image tasks only; ignored for videos.

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: 91

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

keep-bit-rate

Boolean

Video only. Encode the anonymized video at a bitrate close to the original, so the output file size stays similar. Adds about 10% to 20% processing time. Ignored for images.

Default: false

no-object-tracking

Boolean

Video only. Disables Object Tracking, which is enabled by default and reduces flickering of anonymized objects across video frames. Ignored for images.

Default: false

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,
'keep_bit_rate': False,
'no_object_tracking': False,
'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
}

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

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

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

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

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

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

{
"status_code":500,
"error": "An unexpected error occurred. If the problem persists, please contact Celantur support (hello@celantur.com)."
}

Start anonymization task

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

Starts processing for a task that was created with start_on set to start_request. The file must already have been uploaded to the task's upload_url.

If start_on is upload (the default), processing starts automatically after upload and this endpoint is not needed.

Path Parameters

Name

Type

Description

id*

String

id of the task

Headers

Name

Type

Description

Authorization*

String

Authorization token

{
    "message": "Task successfully added to queue for processing."
}

{
    "message": "Task already started on file upload."
}

{
    "message": "Task status is queued. The task is already being started."
}

{
    "status_code": 409,
    "error": "Could not start task. No file available. Please upload a file to the upload URL of the task."
}

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

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

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

{
    "status_code": 500,
    "error": "An unexpected error occurred. If the problem persists, please contact Celantur support (hello@celantur.com)."
}

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 file 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

{
    "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",
    "keep_bit_rate": false,
    "no_object_tracking": false,
    "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_mask_url": "https://cloudapi-customer-uploads-v2-dev-eu-central-1.s3.amazonaws.com/xxx-xxx-xxx-xxx-xxxx/xxxxx/1/binary-mask.png?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_mask_url": "https://cloudapi-customer-uploads-v2-dev-eu-central-1.s3.amazonaws.com/xxx-xxx-xxx-xxx-xxxx/xxxxx/1/instance-mask.png?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"
}

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

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

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

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

{
"status_code":500,
"error": "An unexpected error occurred. If the problem persists, please contact Celantur support (hello@celantur.com)."
}

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 file 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

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

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

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

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

{
"status_code":500,
"error": "An unexpected error occurred. If the problem persists, please contact Celantur support (hello@celantur.com)."
}

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 image, or of frames in a video.

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

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

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

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

{
"status_code":500,
"error": "An unexpected error occurred. Please try creating a task again. If the problem persists, please contact Celantur support (hello@celantur.com)."
}

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

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

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

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

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

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

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

{
    "status_code": 500,
    "error": "An unexpected error occurred. If the problem persists, please contact Celantur support (hello@celantur.com)."
}

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": "username@usermail.com", "password": "password" }

Request Body

Name

Type

Description

username*

String

Username as JSON property

password*

String

Password as JSON property

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

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

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

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

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

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

{
"status_code":500,
"error": "An unexpected error occurred. If the problem persists, please contact Celantur support (hello@celantur.com)."
}

PreviousExamples

NextWebhooks

Last updated 1 month ago

Overview

Create anonymization task

Headers

Request Body

Start anonymization task

Path Parameters

Headers

Get task

Path Parameters

Headers

Get task status

Path Parameters

Headers

Get task metadata

Path Parameters

Headers

List tasks

Query Parameters

Headers

Sign in (authorization)

Request Body

Delete task files.

Path Parameters

Headers