Concept
Understanding the concepts behind Celantur Cloud API
Introduction
The Celantur Cloud API is a REST API and provides a secure, scalable and efficient way to anonymize images while preserving data privacy. This service allows users to protect personal information within images by blurring or obfuscating identifiable objects such as faces, persons, license plates and vehicles. By leveraging this API, developers can seamlessly integrate image anonymization into their applications or workflows.
The service is asynchronous, therefore it allows users to submit requests (tasks) that are processed in the background, enabling non-blocking operations. Users can check the status of tasks or retrieve results later, enhancing efficiency and responsiveness in handling time-consuming workloads. Uploaded images might take a few seconds to process.
Entities
Task: Represents the asynchronous image anonymization process on the server side.
Original image: An image containing personal data which needs to be anonymized.
Anonymized image: An image with personal data anonymized.
Metadata/Detections: JSON representation of detected personal information on the image.
Binary segmentation mask: The binary segmentation mask for the provided image.
Instance segmentation mask: The instance segmentation mask for the provided image.
Upload URL: A pre-signed URL the original image is being uploaded to, in order to start the anonymization. The upload URL expires after 3600 seconds (60 minutes). A new task needs to be generated if the upload URL has expired.
Anonymized URL: A pre-signed URL the anonymized image can be downloaded from. The URL is re-generated every time a request is sent to the GET v2/task and GET v2/task/{id}/status endpoints. The URL expires after 14400 seconds (4 hours). The expiration duration is reset when the URL is re-generated.
Binary segmentation mask URL: A pre-signed URL the binary segmentation mask can be downloaded from. The URL expires after 14400 seconds (4 hours). The expiration duration is reset when the URL is re-generated.
Instance segmentation mask URL: A pre-signed URL the instance segmentation mask can be downloaded from. The URL expires after 14400 seconds (4 hours). The expiration duration is reset when the URL is re-generated.
Workflow
1. Authorization
To access the Celantur Cloud API, users must first authorize themselves by providing a username and password. This step ensures that only authorized users can utilize the service and keep data secure. Use your existing account credentials for https://app.celantur.com, or create a new account.
2. Creating a Task
After successful authentication, users can initiate the anonymization process by creating a task through the POST /v2/task endpoint. A task defines the specific image anonymization requirements, including the areas to be anonymized and the desired anonymization thresholds. The API response provides the task’s configuration in JSON, including a format unique task ID and an upload URL to which the image has to be uploaded to, in order to start the anonymization task.
3. Uploading the Image
With the task ID and upload URL obtained in the previous step, the original image can now be uploaded to the API. Users can transfer their images securely to the provided upload URL with a PUT request and content-type image/jpeg or image/png . Once the upload is complete, the anonymization task commences asynchronously. If the file uploaded to the upload_url is not of the proper content-type the the task status will be set to failed along with the failure cause CONTENT_TYPE_ERROR
4. Checking Task Status
During the anonymization task, users can check the status of their task by querying the /task/id/status endpoint. The API will return information about the task's status, indicating whether it is “new”, “queued”, “processing”, “done” or “failed”.
Alternatively, Webhooks can be used to be notified when a task has been finished.
5. Downloading Anonymized Image
Once the task is finished, users can download the anonymized image from the task's anonymized URL. This URL is pointing to an AWS S3 bucket where the images are stored, ensuring secure and reliable access to the anonymized image. The S3 bucket employs strong encryption mechanisms to safeguard the confidentiality and integrity of the anonymized data.
6. Downloading metadata and segmentation masks
Task status
A task has one of multiple stati:
“new”: The task has been created and persisted in the database.
“queued”: The task has been put in the queue and is waiting to be processed.
“processing”: The task is being processed.
“done”: The task has been successfully done.
“deleted”: All files and detections of the task were deleted.
“failed”: The task failed. A “failure_cause” property will be added to the response body of GET v2/task/id and GET /task/id/status with the following values:
IMAGE_DEFECT: The uploaded file is corrupt and can not be read. Please check if the file is valid.
TASK_FILE_DOESNT_EXIST: The uploaded file was not uploaded successfully.
INTERNAL_ERROR: An internal error occurred. Please get in touch with Celantur.
CONTENT_TYPE_ERROR: The uploaded file has the wrong content-type. In this case uploaded file will automatically be deleted.
PARAMETER_ERROR_FORMAT: The format entered for image is wrong for image size. Please check the format for the given image size.
FAQ
My upload URL expired, what can I do?
A new task needs to be generated if the upload URL has expired.
My anonymized URL (for downloading the anonymized image) expired, what can I do?
The URL is re-generated every time a request is sent to the GET v2/task and GET v2/task/{id}/status endpoints.
How do I find out what went wrong if the task status is “failed”?
Please contact Celantur and tell us the task ID.
Last updated
