🎭 Process Image Endpoint

9 min

The Process Image endpoint queues an uploaded image for asynchronous masking. It applies anonymization to sensitive elements such as faces, people, or license plates based on your parameters, and returns a jobId that can be used to track the result.

This flow is optimized for robust integration into both synchronous and event-driven pipelines. You can poll for completion or enable webhook delivery for hands-free operation.

📦 Endpoint Overview

URL: POST https://app.maskit.ai/api/v1/masking/process-image
Content-Type: multipart/form-data
Authentication: X-Api-Key header (required)
Response: JSON object containing the jobId
Use Case: Asynchronous masking with polling or webhook callback

📝 Request Parameters

Send the following fields as multipart/form-data:

Field	Type	Required	Default	Description
image	file	✅	–	The image file to process (JPEG or PNG).
faces	boolean	❌	true	Whether to detect and mask faces.
humans	boolean	❌	true	Whether to detect and mask full human bodies.
licensePlates	boolean	❌	true	Whether to detect and mask license plates.
shape	string	❌	Mask	Shape used to mask areas: Mask (soft polygon) or Rectangle (bounding box).
method	string	❌	Blur	Masking method: Blur or BlackFill.
blurStrength	int	❌	30	Gaussian blur strength when method=Blur.
edgeBlurSize	double (0.0–1.0)	❌	0.2	Softness applied to the edges of masked regions.
metadata	string	❌	–	Optional metadata string (e.g. user ID, context) attached to the job.
useWebhook	boolean	❌	false	If true, result is delivered via webhook once ready.

🔐 Authentication

Include your API key in the request header:

X-Api-Key: YOUR_API_KEY

Refer to the API Key & Webhook Secret page to generate and manage your credentials.

🔁 Response

{
  "jobId": "9f52f3d9-1c84-4b1d-bf7c-2f0b9383fa17"
}

Use the jobId with the Image Status endpoint to check processing progress.
Once ready, retrieve the final masked image via the Image Download endpoint.

Error Responses:

Code	Description
400	Invalid or missing parameters
401	Missing or invalid API key
500	Server error while processing the image

🔔 Webhook Delivery

If you set useWebhook=true, the final masked image will be delivered to your configured webhook URL as a multipart/form-data POST request.

For full details, including HMAC validation and payload structure, see the Webhook documentation.

🚀 Example cURL Request

curl -X POST "https://app.maskit.ai/api/v1/masking/process-image" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]" \
  -F "faces=true" \
  -F "humans=true" \
  -F "licensePlates=true" \
  -F "shape=Mask" \
  -F "method=Blur" \
  -F "blurStrength=30" \
  -F "edgeBlurSize=0.2" \
  -F "useWebhook=true"

This command uploads an image for masking and enables webhook delivery once it's processed.