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

| {% 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 %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://doc.celantur.com/cloud-api/api-endpoints.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.