Documentation

API Documentation

Everything you need to integrate Blur Stuff into your own application. Detect sensitive information, selectively anonymize detections, and process images, videos, and documents.

Getting started

Quick Start

The Blur Stuff API accepts files through HTTP requests and returns detection results or anonymized files.

Base URL

https://blurstuff.up.railway.app/api/v1

Example

POST /images/anonymize
curl -X POST \
"https://blurstuff.up.railway.app/api/v1/images/anonymize?targets=faces&mode=pixelate" \
-F "file=@image.jpg"

Basics

Requests

File-processing endpoints accept multipart/form-data requests.

Parameter Description
file The file to process.
detections JSON-encoded detection data. Required by selected anonymization endpoints.

Responses

Detection Response

Detection endpoints return the regions identified by Blur Stuff. Each detection contains its bounding-box coordinates, confidence score, and unique detection ID. Detections are grouped by their target type.

Detection object

{
"x1" : 120 ,
"y1" : 80 ,
"x2" : 260 ,
"y2" : 240 ,
"confidence" : 0.94 ,
"id" : "face_1"
}
Field Description
x1 Left coordinate of the detection bounding box.
y1 Top coordinate of the detection bounding box.
x2 Right coordinate of the detection bounding box.
y2 Bottom coordinate of the detection bounding box.
confidence Confidence score produced by the detector.
id Unique identifier assigned to the detection.

Image detection response

The image detection endpoint returns detections grouped by target. The target name is used as the JSON key containing its detections.

{
"faces" : [
{
"x1" : 120 ,
"y1" : 80 ,
"x2" : 260 ,
"y2" : 240 ,
"confidence" : 0.94 ,
"id" : "face_1"
}
],
"plates" : [
{
"x1" : 420 ,
"y1" : 310 ,
"x2" : 580 ,
"y2" : 360 ,
"confidence" : 0.88 ,
"id" : "plate_1"
}
]
}

Video detection response

Video detections are returned as a list of frame results. Each result contains the frame number, timestamp, and detections found on that frame.

[
{
"frame" : 0 ,
"timestamp" : 0.0 ,
"detections" : {
"faces" : [
{
"x1" : 120 ,
"y1" : 80 ,
"x2" : 260 ,
"y2" : 240 ,
"confidence" : 0.94 ,
"id" : "face_1"
}
]
}
}
]

Document detection response

Document detections are returned as a list of page results. Each page contains detections grouped by target and a page number identifying the page where the detections were found.

[
{
"text" : [
{
"x1" : 120 ,
"y1" : 180 ,
"x2" : 520 ,
"y2" : 220 ,
"confidence" : 0.97 ,
"id" : "token_1"
}
],
"pii" : [
{
"x1" : 120 ,
"y1" : 180 ,
"x2" : 520 ,
"y2" : 220 ,
"confidence" : 0.97 ,
"id" : "pii_1"
}
],
"page" : 1
}
]
Note: Detection coordinates are returned in the original image or page coordinate system. For video responses, the frame and timestamp identify when the detections occurred.

Selective anonymization

Selected Detections

The anonymize-selected endpoints allow you to anonymize only specific detections instead of automatically anonymizing everything detected in the file.

POST /images/anonymize-selected

Anonymizes only the detections supplied by the client. The detections are provided through the detections multipart form field.

Field Description Required
target The type of information being anonymized. Yes
x1 Left coordinate of the detection. Yes
y1 Top coordinate of the detection. Yes
x2 Right coordinate of the detection. Yes
y2 Bottom coordinate of the detection. Yes
confidence Optional detection confidence score. No
id Optional identifier for the detection. No

Detection format

[
{
"target" : "faces" ,
"x1" : 0.25 ,
"y1" : 0.15 ,
"x2" : 0.45 ,
"y2" : 0.50
}
]

Example request

curl -X POST \
"https://blurstuff.up.railway.app/api/v1/images/anonymize-selected?mode=blur&padding=0.2" \
-F "file=@image.jpg" \
-F 'detections=[{"target":"faces","x1":0.25,"y1":0.15,"x2":0.45,"y2":0.50}]'
POST /documents/anonymize-selected

Anonymizes only the selected detections in a document. The detection format follows the same structure used by image selective anonymization.

Coordinates: normalized bounding-box coordinates between 0 and 1.

Example detection

[
{
"target" : "pii" ,
"x1" : 0.10 ,
"y1" : 0.30 ,
"x2" : 0.80 ,
"y2" : 0.40
}
]

Example request

curl -X POST \
"https://blurstuff.up.railway.app/api/v1/documents/anonymize-selected?mode=blur" \
-F "file=@document.pdf" \
-F 'detections=[{"target":"pii","x1":0.10,"y1":0.30,"x2":0.80,"y2":0.40}]'

Detection

Detection Targets

Use the targets query parameter to choose what Blur Stuff should detect.

Multiple targets can be provided as a comma-separated list. If omitted, the API defaults to faces.

Faces

faces

License plates

plates

Text

text

Personal information

pii

Important

text and pii cannot be used together.

Anonymization

Anonymization Modes

Anonymization endpoints support several ways of hiding detected information. Use the mode query parameter.

Blur

Blurs the detected region.

Pixelate

Pixelates the detected region.

Solid

Covers the region with a solid block.

Noise

Replaces the region with generated noise.

Emoji

Covers the detected region with an emoji.

Inpaint

Attempts to fill the detected region.

Default: pixelate

Anonymization

Padding

Use the padding query parameter to expand the detected bounding box before applying anonymization.

Property Value
Type float
Minimum 0.0
Maximum 1.0
Default 0.2
/images/anonymize?targets=faces&mode=blur&padding=0.2

Endpoints

Images

Detect and anonymize sensitive information in images.

Preview

POST /api/v1/images/preview

Generates a preview representation of an uploaded image.

Detect

POST /api/v1/images/detect

Detects sensitive information in an uploaded image and returns the detected regions.

POST /api/v1/images/detect?targets=faces,plates

Anonymize

POST /api/v1/images/anonymize

Detects and anonymizes the selected targets in an uploaded image.

POST /api/v1/images/anonymize?targets=faces&mode=pixelate&padding=0.2

Anonymize selected

POST /api/v1/images/anonymize-selected

Anonymizes only the detections selected by the client.

POST /api/v1/images/anonymize-selected?mode=blur&padding=0.2

Selected detections must be supplied through the detections form field as JSON.

Endpoints

Videos

Detect and anonymize sensitive information in video files.

Detect

POST /api/v1/videos/detect

Detects sensitive information throughout a video.

Anonymize

POST /api/v1/videos/anonymize

Detects and anonymizes sensitive information throughout a video.

POST /api/v1/videos/anonymize?targets=faces&mode=blur

Endpoints

Documents

Process supported documents and anonymize sensitive information.

Detect

POST /api/v1/documents/detect

Detects text and potentially sensitive information in a document.

Anonymize

POST /api/v1/documents/anonymize

Detects and anonymizes sensitive information in a document.

Anonymize selected

POST /api/v1/documents/anonymize-selected

Anonymizes only the selected detections in a document.

Infrastructure

Health & Readiness

Check whether the API is running and whether its detection models are ready.

Health

GET /api/v1/health

Returns whether the API is running.

Readiness

GET /api/v1/health/ready

Checks whether the detection models are ready to process requests.

Reference

Errors

When a request cannot be processed, the API returns an appropriate HTTP status code along with an error response.

Status Meaning
400 Invalid request or unsupported input.
500 Failed to encode or generate the requested output.
503 Service or detection models are unavailable.
{"error": "example"}