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

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`

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"

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.

Name

Type

Description

object

The image.

Payload is limited to 10 MB.

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

Name

Type

Description

id*

String

id of the file

Headers

Name	Type	Description
Authorization	String	Authorization

Name

Type

Description

Authorization

String

Authorization

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

Name

Type

Description

id*

String

id of the file

Headers

Name	Type	Description
Authorization*	String	Authorization token

Name

Type

Description

Authorization*

String

Authorization token

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

Name

Type

Description

id*

String

id of the file

Headers

Name	Type	Description
Authorization*	String	Authorization token

Name

Type

Description

Authorization*

String

Authorization token

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

Name

Type

Description

id*

String

id of the file

Headers

Name	Type	Description
Authorization*	String	Authorization token

Name

Type

Description

Authorization*

String

Authorization token

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

Name

Type

Description

id*

String

id of the file

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

Name

Type

Description

id*

String

id of the file

Headers

Name	Type	Description
Authorization*	String	Authorization token

Name

Type

Description

Authorization*

String

Authorization token

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

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

Name

Type

Description

Authorization*

String

Authorization token

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

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

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

{ "username": "username@usermail.com", "password": "password" }

Request Body

Name	Type	Description
json*	String	Credentials

Name

Type

Description

json*

String

Credentials

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

Previousv1 (deprecated)Nextv1 Webhooks (deprecated)

Last updated 8 months ago

Overview

Upload image

Query Parameters

Headers

Request Body

Correctly encode strings for query parameters

Get file status

Path Parameters

Headers

Get anonymized file

Path Parameters

Headers

Get image binary segmentation mask

Path Parameters

Headers

Get image instance segmentation mask

Path Parameters

Headers

Get metadata

Query Parameters

Get original file

Path Parameters

Headers

List files

Query Parameters

Headers

Sign in (authorization)

Request Body