> 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/concept.md).

# 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 and videos while preserving data privacy. This service allows users to protect personal information by blurring or obfuscating identifiable objects such as faces, persons, license plates and vehicles. By leveraging this API, developers can seamlessly integrate 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 typically take a few seconds to process. Videos take longer, depending on duration and resolution.

<figure><img src="https://1992407480-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fr2aH3h1rP4SjkhFlr7Mp%2Fuploads%2FemZipAmZvskE1XjvtUdp%2Fimage.png?alt=media&amp;token=ce66c576-2bf9-4619-9eef-42682798dc1e" alt=""><figcaption><p>HTTPS workflow diagram of Celantur Cloud API</p></figcaption></figure>

## Supported files

**Images:** JPEG (`image/jpeg`) and PNG (`image/png`). Maximum size: 100 MiB.

**Videos:** MP4 (`video/mp4`), QuickTime/MOV (`video/quicktime`) and AVI (`video/x-msvideo`). Limits:

* Maximum file size: 1 GB
* Maximum duration: 10 minutes
* Maximum frame count: 18,000
* Maximum resolution: 4K (3,840 px on the longest side)

Set the corresponding `Content-Type` header when uploading to the `upload_url`. If the content type is missing or generic, the file format is detected from the file contents.

## Entities

* **Task**: Represents the asynchronous anonymization process on the server side.
* **Original file**: An image or video containing personal data which needs to be anonymized.
* **Anonymized file**: An image or video with personal data anonymized.
* **Metadata/Detections**: JSON representation of detected personal information on the image, or on video frames.
* **Binary segmentation mask**: The binary segmentation mask for the provided image. Image tasks only.
* **Instance segmentation mask**: The instance segmentation mask for the provided image. Image tasks only.
* **Upload URL**: A pre-signed URL the original file 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 file 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.

Endpoint: [API Endpoints](/cloud-api/api-endpoints.md#sign-in-authorization)

### 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 anonymization requirements, including the objects to be anonymized and optional video parameters such as `keep-bit-rate` and `no-object-tracking`. The API response provides the task’s configuration in JSON, including a unique **task ID** and an **upload URL** to which the file has to be uploaded, in order to start the anonymization task.

* Endpoint: [API Endpoints](/cloud-api/api-endpoints.md#create-anonymization-task)

### 3. Uploading the file

With the task ID and upload URL obtained in the previous step, the original image or video can now be uploaded to the API. Users can transfer their files securely to the provided upload URL with a **PUT request**. Use content-type `image/jpeg` or `image/png` for images, and `video/mp4`, `video/quicktime` or `video/x-msvideo` for videos. Once the upload is complete, the anonymization task commences asynchronously (unless `start_on` is `start_request`; see [API Endpoints](/cloud-api/api-endpoints.md#start-anonymization-task)). If the uploaded file is not a supported image or video, the task status will be set to `failed` along with the failure cause `CONTENT_TYPE_ERROR` or `IMAGE_DEFECT`.

### 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”.

* Endpoint: [API Endpoints](/cloud-api/api-endpoints.md#get-task-status)
* Alternatively, [Webhooks](/cloud-api/webhooks.md) can be used to be notified when a task has been finished.

### 5. Downloading the anonymized file

Once the task is finished, users can download the anonymized image or video from the task's **anonymized URL**. This URL is pointing to an AWS S3 bucket where the files are stored, ensuring secure and reliable access to the anonymized result. The S3 bucket employs strong encryption mechanisms to safeguard the confidentiality and integrity of the anonymized data.

### 6. Downloading metadata and segmentation masks

Once the task is finished, users can also download the metadata. Detections are created by default. Creation of segmentation masks need to be activated during the initial creation of the task [API Endpoints](/cloud-api/api-endpoints.md#create-anonymization-task). Segmentation masks are supported for images, not for videos.

* Endpoint: [API Endpoints](/cloud-api/api-endpoints.md#get-task-metadata)

## 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](https://docs.google.com/document/d/1RLja9nrtc1lBNTdrCcbWmIL_u-O4XzkDlD5YzG6ytH0/edit?pli=1#heading=h.3se7prv71a5n) and [GET /task/id/status](https://docs.google.com/document/d/1RLja9nrtc1lBNTdrCcbWmIL_u-O4XzkDlD5YzG6ytH0/edit?pli=1#heading=h.vt20aek6oa6z) with the following values:
  * IMAGE\_DEFECT: The uploaded file is corrupt, cannot be read, or a video exceeds the allowed size, duration, frame count or resolution. Please check if the file is valid and within the limits in [#supported-files](#supported-files "mention").
  * 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 the uploaded file will automatically be deleted.

## Data retention

All files are retained for **five days after task creation** on Celantur servers and then permanently deleted.

## 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 file) 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”?**
  * Check the `failure_cause` field in the [API Endpoints](/cloud-api/api-endpoints.md#get-task) or [API Endpoints](/cloud-api/api-endpoints.md#get-task-status) response. If that is not sufficient, contact Celantur and tell us the task ID.