> For the complete documentation index, see [llms.txt](https://doc.celantur.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.celantur.com/cloud-api/api-endpoints.md). # API Endpoints ## Overview **API URL:** ``` https://api.celantur.com/v2/ ``` {% hint style="info" %} Celantur Cloud API supports only images at the moment. Support for videos will be added soon. {% endhint %} ## 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 how the input image is to be tiled. See /pages/I7oMH2TYkzRNbCRjwcOq#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]}

| | 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: /pages/0DGfEHu0aPCWIkfM0MxI

| | 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 /pages/kNLnfXcN7zFLsuxgsFe3

Default: 0.35

| | kernel-size-person | Number |

Specifies the kernel size for person blurring. See /pages/kNLnfXcN7zFLsuxgsFe3

Default: 95

| | kernel-size-license-plate | Number |

Specifies the kernel size for license plate blurring. See /pages/kNLnfXcN7zFLsuxgsFe3

Default: 0.5

| | kernel-size-vehicle | Number |

Specifies the kernel size for vehicle blurring. See /pages/kNLnfXcN7zFLsuxgsFe3

Default: 61

| | face-anonymization-gradient-start | Number |

Specifies the gradient start value for face blurring. See /pages/kNLnfXcN7zFLsuxgsFe3

Default: 0.3

| | face-anonymization-gradient-stop | Number |

Specifies the gradient stop value for face blurring. See /pages/kNLnfXcN7zFLsuxgsFe3

Default: 0.0

| | license-plate-anonymization-gradient-start | Number |

Specifies the gradient start value for license plate blurring. See /pages/kNLnfXcN7zFLsuxgsFe3

Default: 0.3

| | license-plate-anonymization-gradient-stop | Number |

Specifies the gradient stop value for license plate blurring. See /pages/kNLnfXcN7zFLsuxgsFe3

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

| {% tabs %} {% tab title="200: OK Response body with JSON " %} Response body JSON containing file information and parameters: ```javascript { '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 } ``` {% endtab %} {% tab title="400: Bad Request Parameter doesn" %} ```json { "status_code":400, "error": "Could not create task. {parameter} parameter caused an error. This parameter does not exist." } ``` {% endtab %} {% tab title="400: Bad Request Parameter received unexpected value" %} ```json { "status_code":400, "error": "Could not create task. {parameter} parameter received an unexpected value." } ``` {% endtab %} {% tab title="400: Bad Request Parameter value value caused an error" %} ```json { "status_code":400, "error": "Could not create task. {parameter} parameter value caused an error. {Error cause}" } ``` {% endtab %} {% tab title="400: Bad Request Request body is not correct" %} ```json { "status_code":400, "error": "Could not create task. Request body is not correct. {Error cause}" } ``` {% endtab %} {% tab title="400: Bad Request JSON body missing" %} ```json { "status_code":400, "error": "Could not create task. Please add a JSON body." } ``` {% endtab %} {% tab title="400: Bad Request Task files are deleted" %} ```json { "status_code": 404, "error": "Task is deleted. Please upload a new task." } ``` {% endtab %} {% tab title="500: Internal Server Error " %} ```json { "status_code":500, "error": "An unexpected error occurred. If the problem persists, please contact Celantur support (hello@celantur.com)." } ``` {% endtab %} {% endtabs %} ### ## 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 | {% tabs %} {% tab title="200: OK Task as JSON" %} ```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" } ``` {% endtab %} {% tab title="200: OK Task as JSON with task failure cause" %} ```json { "task_id": task_id, … "task_status": "failed", "failure_cause": "IMAGE_DEFECT|TASK_FILE_DOESNT_EXIST|INTERNAL_ERROR|CONTENT_TYPE_ERROR" } ``` {% endtab %} {% tab title="400: Bad Request MIssing task ID" %} ```json { "status_code":400, "error": "Getting task results failed. Please enter a task ID." } ``` {% endtab %} {% tab title="400: Bad Request Task ID not an integer" %} ```json { "status_code":400, "error": "Wrong format for Task ID. {task_id} is not an integer." } ``` {% endtab %} {% tab title="400: Bad Request No task with specified task ID found" %} ```json { "status_code":400, "error": "Task ID not found. There is no task with task ID {task_id}." } ``` {% endtab %} {% tab title="500: Internal Server Error Unexpected error" %} ```json { "status_code":500, "error": "An unexpected error occurred. If the problem persists, please contact Celantur support (hello@celantur.com)." } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="200: OK Task status" %} ```json { "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" } ``` {% endtab %} {% tab title="200: OK Task status for failed task with failure cause" %} ```json { "task_id": task_id, … "task_status": "failed", "failure_cause": "IMAGE_DEFECT|TASK_FILE_DOESNT_EXIST|INTERNAL_ERROR|CONTENT_TYPE_ERROR" } ``` {% endtab %} {% tab title="400: Bad Request No task with specified task ID found" %} ```json { "status_code":400, "error": "Task ID not found. There is no task with task ID {task_id}." } ``` {% endtab %} {% tab title="400: Bad Request Task ID is not an interger" %} ```json { "status_code":400, "error": "Wrong format for Task ID. {task_id} is not an integer." } ``` {% endtab %} {% tab title="500: Internal Server Error Unexpected error" %} ```json { "status_code":500, "error": "An unexpected error occurred. If the problem persists, please contact Celantur support (hello@celantur.com)." } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="200: OK Task metadata with detections" %} ```json { "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 }, ... ] } ``` {% endtab %} {% tab title="204: No Content No detections, task\_status failed or task has not finished processing yet" %} {% endtab %} {% tab title="400: Bad Request No task with specified task ID found" %} ```json { "status_code":400, "error": "Task ID not found. There is no task with task ID {task_id}." } ``` {% endtab %} {% tab title="400: Bad Request Task ID is not an integer" %} ```json { "status_code":400, "error": "Wrong format for Task ID. {task_id} is not an integer." } ``` {% endtab %} {% tab title="500: Internal Server Error Unexpected error" %} ```json { "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)." } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="200: OK " %} ```json { "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" } ] } ``` {% endtab %} {% tab title="400: Bad Request Format error of create\_time\_before/create\_time\_after" %} ```json { "status_code": 400, "error": "Please enter a properly formatted time for the create_time_before value. Correct format: YYYY-MM-DD" } ``` {% endtab %} {% tab title="400: Bad Request Wrong task\_id format" %} ```json { "status_code": 400, "error": "Wrong format for task_id. Please enter an integer." } ``` {% endtab %} {% tab title="400: Bad Request Wrong task\_status" %} ```json { "status_code": 400, "error": "Please enter a correct task_status. Task status value can only be one of ['new', 'queued', 'processing', 'done', 'failed']" } ``` {% endtab %} {% tab title="400: Bad Request create\_time\_\* parameters are missing" %} ```json { "status_code": 400, "error": "No create_time_* parameters have been specified." } ``` {% endtab %} {% tab title="400: Bad Request create\_time\_after parameter is later than or equal to create\_time\_before" %} ```json { "status_code": 400, "error": "Please check your create_time_* parameters. create_time_after can not be later than/equal to create_time_before." } ``` {% endtab %} {% tab title="500: Internal Server Error Unexpected error" %} ```json { "status_code": 500, "error": "An unexpected error occurred. If the problem persists, please contact Celantur support (hello@celantur.com)." } ``` {% endtab %} {% endtabs %} ## 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": "username@usermail.com", "password": "password" }` #### Request Body | Name | Type | Description | | ------------------------------------------ | ------ | ------------------------- | | username\* | String | Username as JSON property | | password\* | String | Password as JSON property | {% tabs %} {% tab title="200: OK Authentication result" %} ```javascript { "AccessToken": "eyJraWQiOiJr…Wa_CNpFRyNIjbt5qjAED1-oH8pEKpO-KPTttuSGHw", "ExpiresIn": 3600, "TokenType": "Bearer", "RefreshToken": "eyJjd...t8OWzmXJpmPnuNbBzr1vPA", "IdToken": "eyJraWQiOiI1aTlFa…ZIttv0gNRJRp39LvyzAn5LJWJBw7Ju8szRRBA" } ``` {% endtab %} {% tab title="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 } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="200: OK Task deleted" %} ```json { "files_deleted": true, "task_id": "{task_id}" } ``` {% endtab %} {% tab title="400: Bad Request Task is already deleted" %} ```json { "status_code": 400, "error": "Task with ID 1696335137350403 already deleted." } ``` {% endtab %} {% tab title="400: Bad Request No task with specified task ID found" %} ```json { "status_code":400, "error": "Task ID not found. There is no task with task ID {task_id}." } ``` {% endtab %} {% tab title="400: Bad Request Task ID is not an interger" %} ```json { "status_code":400, "error": "Wrong format for Task ID. {task_id} is not an integer." } ``` {% endtab %} {% tab title="500: Internal Server Error Unexpected error" %} ```json { "status_code":500, "error": "An unexpected error occurred. If the problem persists, please contact Celantur support (hello@celantur.com)." } ``` {% endtab %} {% endtabs %}