---
title: ⬇️ Image Download Endpoint
slug: image-download-endpoint
docTags: 
createdAt: 2025-07-13T14:23:24.333Z
---

The **Image Download** endpoint allows you to retrieve the final masked image associated with a completed job.

⚠️ **Important:** The masked image can be downloaded **only once**. After the first successful download, the file is **permanently deleted** from our temporary storage.
⏳ Additionally, files that are **not downloaded within one hour** of completion will be automatically deleted.
📥 Only images whose status is `ReadyToDownload` can be downloaded via this endpoint.

***

## 📦 Endpoint Overview

- **URL**: `GET https://app.maskit.ai/api/v1/masking/image-download`
- **Authentication**: `X-Api-Key` header (required)
- **Response**: Processed image as binary stream (e.g. image/jpeg or image/png)
- **Use Case**: Retrieving the masked image after a successful job

***

## 📝 Query Parameters

| Parameter | Type   | Required | Description                                |
| --------- | ------ | -------- | ------------------------------------------ |
| `jobId`   | string | ✅        | The unique identifier of the submitted job |

***

## 🔐 Authentication

Include your API key in the request header:

```text
X-Api-Key: YOUR_API_KEY
```

***

## 🔁 Response

### Success (200 OK)

Returns the image stream in the **same file format as the original upload**.
Supported formats include: `JPEG`, `JPG`, `PNG`, and `WEBP`.

The response includes appropriate headers:

- `Content-Type`: `image/jpeg`, `image/png`, or `image/webp`
- `Content-Disposition`: `attachment; filename="masked_filename.ext"`

### Error Responses:

| Code | Description                                                |
| ---- | ---------------------------------------------------------- |
| 400  | Missing job ID or image is not ready                       |
| 401  | Missing or invalid API key                                 |
| 404  | Job not found or does not belong to the authenticated user |
| 500  | Internal server error                                      |

***

## ⚠️ Single Download & Expiry Policy

To ensure privacy:

- Each masked image can be downloaded **only once**.
- Files that are **not downloaded within one hour** will be **automatically deleted**.
- Only jobs with status `ReadyToDownload` can be retrieved.
- If you miss the window or fail to save the image after downloading, you must reprocess the original image.

***

## 🚀 Example cURL Request

```bash
curl -X GET "https://app.maskit.ai/api/v1/masking/image-download?jobId=YOUR_JOB_ID" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -OJ
```

This command downloads the final masked image and saves it as `masked_result.jpg`.