v1 API Endpoints (deprecated)

Overview

API URL: https://api.celantur.com/v1/

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

Upload image

POST https://api.celantur.com/v1/file

Upload image that is processed with the specified method.

The payload is limited to 4.45 MB. This limitation will be removed in the upcoming weeks.

Query Parameters

Name	Type	Description
method*	String	Specifies anonymization method: blur, pixelate, blacken, detect detect generates only binary and instance segmentation masks and metadata. No anonymized image will be generated. Default: blur
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
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).
ignores	String	Specifies pixel coordinates of areas on the image in which no anonymization will be applied (as JSON). The JSON string must be encoded, see Correctly encode strings for query parameters Example: [{"topLeftX":182, "topLeftY":154, "width":2000, "height":2000}]
mask-scale	Number	Specifies the ratio at which the mask file will be scaled down, range between 0 .. 100. Default: 100
save-mask	String	Specifies whether only mask files should be generated. This speeds up processing time by not creating an anonymized image: all, binary, instance detect generates only binary and instance segmentation masks and metadata. No anonymized image will be generated. Default: all
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
webhook	String	A webhook URL to which a POST request is sent to after successful processing. The URL must be encoded, see Correctly encode strings for query parameters More details here: Webhooks
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

Headers

Name	Type	Description
Authorization*	String	Authorization token
Content-Type*	String	"image/jpeg" or "image/png"

Request Body

Name	Type	Description
-*	object	The image. Payload is limited to 10 MB.

200: OK Response body with JSON

Response body JSON containing file information and parameters:

{
  "customer_id": "customer_id",
  "file_id": "file_id",
  "upload_time": "24/01/2023, 14:07:51",
  "delete_time": null,
  "name": "example.jpg",
  "debug": false,
  "score": false,
  "method": "blur",
  "face": true,
  "license_plate": false,
  "person": false,
  "vehicle": false,
  "format": "whole",
  "bbox": false,
  "ignores": [],
  "mask_scale": 100,
  "save_mask": "all",
  "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": null,
  "file_status": "queued",
  "webhook_status": "empty"
}

Correctly encode strings for query parameters

When setting format, ignores and webhook values, strings must be encoded.

String encoding in Python

webhook_url = 'https://example.com/webhook/dev?sender=celantur&approve=always'

# encode the URL you want to send the webhook to
# returns 'https://example.com/webhook/dev?sender=celantur%26approve=always'
webhook_url_encoded = webhook_url.encode()

See further string encoding examples in Java, C#, JavaScript and cUrl.

Get file status

GET https://api.celantur.com/v1/file/{id}/status

Path Parameters

Name	Type	Description
id*	String	id of the file

Headers

Name	Type	Description
Authorization	String	Authorization

200: OK File status as JSON

{
  "file_id": "f8bd9047-9c21-401b-89e4-ff54392e377a",
  "file_status": "done",
  "delete_time": null
}

Get anonymized file

GET https://api.celantur.com/v1/file/{id}/anonymized

Path Parameters

Name	Type	Description
id*	String	id of the file

Headers

Name	Type	Description
Authorization*	String	Authorization token

200: OK File

{
    // Response
}

Get image binary segmentation mask

GET https://api.celantur.com/v1/file/{id}/binary-mask

Path Parameters

Name	Type	Description
id*	String	id of the file

Headers

Name	Type	Description
Authorization*	String	Authorization token

200: OK Binary segmentation mask

{
    // Response
}

Get image instance segmentation mask

GET https://api.celantur.com/v1/file/{id}/instance-mask

Path Parameters

Name	Type	Description
id*	String	id of the file

Headers

Name	Type	Description
Authorization*	String	Authorization token

200: OK Instance segmentation mask

{
    // Response
}

Get metadata

GET https://api.celantur.com/v1/file/{id}/metadata

Returns metadata (detected objects) in JSON format

Query Parameters

Name	Type	Description
id*	String	id of the file

200: OK Metadata in JSON format

{
   "customer_id":"2c46d468-ee8c-4317-b4d4-aff8462f4543",
   "file_id":"04b4db09-3b1d-4e2e-8141-935cadad6dcd",
   "detections":[
      {
         "score":"0.9995585083961487",
         "offset":[
            "1209",
            "2752"
         ],
         "color":"None",
         "bbox":[
            "1209",
            "2752",
            "2529",
            "6477"
         ],
         "parent_image":"04b4db09-3b1d-4e2e-8141-935cadad6dcd.jpg",
         "id":"0",
         "type_label":"face",
         "type":"103",
         "is_anonymised":true
      },
      {
         "score":"0.9993017911911011",
         "offset":[
            "2133",
            "2803"
         ],
         "color":"None",
         "bbox":[
            "2133",
            "2803",
            "3444",
            "6553"
         ],
         "parent_image":"04b4db09-3b1d-4e2e-8141-935cadad6dcd.jpg",
         "id":"0",
         "type_label":"face",
         "type":"103",
         "is_anonymised":true
      }
   ],
   "webhook": null,
   "upload_time": "20/04/2023, 07:17:37",
   "kernel_size_vehicle": "61",
   "score": false,
   "name": "a1b69a69-50dd-4541-a6ba-13ce26ec767d.jpg",
   "method": "blur",
   "vehicle": false,
   "compress_level": "5",
   "delete_time": null,
   "ignores": [],
   "webhook_status": "empty",
   "bbox": false,
   "face_anonymization_gradient_start": "0.3",
   "debug": false,
   "file_status": "done",
   "license_plate_anonymization_gradient_start": "0.3",
   "person": false,
   "mask_scale": "100",
   "license_plate_anonymization_gradient_stop": "0",
   "face": true,
   "kernel_size_person": "91",
   "quality": "90",
   "kernel_size_face": "0.35",
   "face_anonymization_gradient_stop": "0",
   "save_mask": "all",
   "kernel_size_license_plate": "0.5",
   "format": "whole",
   "license_plate": false
}

Get original file

GET https://api.celantur.com/v1/file/{id}/original

Path Parameters

Name	Type	Description
id*	String	id of the file

Headers

Name	Type	Description
Authorization*	String	Authorization token

200: OK Original image

{
    // Response
}

List files

GET https://api.celantur.com/v1/list

Returns a paginated JSON list of all files ('items' in this context) a user has sent.

The JSON result contains information about the total item count and respective total page count depending on the specified limit. E.g.: {'total_item_count': 46, 'total_page_count': 10, 'items': [...]}

The total page calculation: total item count / limit = total page count

Query Parameters

Name	Type	Description
page*	Number	The page which will be queried
limit*	Number	The number of items per page

Headers

Name	Type	Description
Authorization*	String	Authorization token

200: OK List of all files by page

{
  "total_item_count": "134",
  "total_page_count": "67",
  "items": [
    {
      "customer_id": "customer_id",
      "file_id": "file_id1",
      "detections": " ",
      "bbox": false,
      "debug": "True",
      "delete_time": null,
      "face": "True",
      "file_status": "queued",
      "format": "whole",
      "ignores": "[{\"topLeftX\": 182, \"topLeftY\": 154, \"width\": 2000, \"height\": 2000}]",
      "license_plate": false,
      "mask_scale": "100",
      "method": "blur",
      "person": false,
      "save_mask": "all",
      "score": "True",
      "upload_time": "10/01/2023, 16:01:23",
      "vehicle": false,
      "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
    },
    {
      "customer_id": "customer_id",
      "file_id": "file_id2",
      "detections": " ",
      "bbox": false,
      "debug": "True",
      "delete_time": null,
      "face": "True",
      "file_status": "queued",
      "format": "{\"number\": [2, 2], \"overlap\": [0, 0]}",
      "ignores": "[{\"topLeftX\": 182, \"topLeftY\": 154, \"width\": 2000, \"height\": 2000}]",
      "license_plate": false,
      "mask_scale": "100",
      "method": "blur",
      "person": false,
      "save_mask": "all",
      "score": "True",
      "upload_time": "11/01/2023, 08:20:02",
      "vehicle": false,
      "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
    }
  ]
}

Sign in (authorization)

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

Provide username/password as JSON payload to receive authorization token.

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

Request Body

Name	Type	Description
json*	String	Credentials

200: OK Authentication result

{
  "ChallengeParameters": {},
  "AuthenticationResult": {
    "AccessToken": "acces_token",
    "ExpiresIn": 3600,
    "TokenType": "Bearer",
    "RefreshToken": "ref_token",
    "IdToken": "id_token"
  }
}